Configuring OpenX

The OpenX Administrator interface includes a number of pages wherein you can configure the system. The main configuration tools are:

About global settings

Global settings enable administrators to control many aspects of OpenX operations and are available in the My Account > Global settings tab. This tab is only visible if you are working as an administrator.

Global settings are stored in the configuration file, conf.php, and you must have write permission to make any changes to the file. To avoid accidental damage, when you finish making changes in the My Account > Global Settings pages lock the configuration file again by removing the write permission for the file.

Global settings - email

The Global settings > Email page enables you to manage the following settings:

  • You can change the Name, Email address and Company information that appears in the Email From Address information.
  • You can log all outgoing email messages in the Email log.
  • You can enter Email headers to add to each email message sent by OpenX.
  • The Enable qmail patch setting prevents a known bug in qmail. This bug causes emails sent by OpenX to show their headers within the body text of the email.

Global settings - banners

In the My Account > Global settings tab, an administrator can manage the following banner settings:

See also: Account preferences in the OpenX 2.6 User Guide for information about delivery preferences you can apply at account level.

Banner delivery settings

The global banner delivery settings are:

  • Allowed invocation types: If you disable any invocation tag type it will no longer be available as an option when users create zones. See also: Zone tags in the OpenX 2.6 User Guide.
  • Banner delivery cache settings: You can change the amount of time (in seconds) that OpenX allows before updating the banner delivery cache. The default value is 1200 seconds (20 minutes).
  • Banner delivery settings: You can control the following:
    • Evaluate banner delivery limitations during delivery: This setting is enabled by default. If you disable this option you might experience some increase in speed.
    • Obfuscate channel when delivering ads:  This setting obscures channel information when delivering banners.
    • Allow PHP code in ads to be executed: While it is possible to allow execution of PHP code in ads it should be noted that this represents a security risk.
    • 3rd Party Click Tracking Delimiter: This value is the default delimiter OpenX uses for tracking 3rd party clicks. See also: Third Party Click Tracking with OpenX
  • Invocation defaults: To Enable 3rd party click tracking, select which type from the drop-down menu. Available options are:
    • None
    • Generic
    • Rich media doubleclick
    • Rich media OpenX
  • P3P privacy policies: P3P privacy policies were introduced in Internet Explorer 6 to guard against unwanted cookies. P3P is enabled by default in OpenX and delivers a compact policy statement that the browser recognises. You can specify a file location for a separate P3P privacy policy if desired.
  • OpenX server access paths: Manage the pathnames to the OpenX administrator interface, delivery directories and image directories.
  • Delivery file names: Lists the filenames used for banner delivery.

If you change any settings in the Banner delivery settings remember to click Save Changes.

Banner Logging Settings

This section of the screen allows the OpenX administrator to control the different types of raw data that will be logged by OpenX. There are nine different options:

Request, Impression and Click Logging Settings

  • Log a request every time a banner is requested
  • Log an impression every time a banner is viewed
  • Log a click every time a viewer clicks on a banner

These three settings control whether OpenX should log raw requests, impressions, and/or clicks.

Note
The logging of impressions is almost always required for OpenX to operate correctly. In particular, the Maintenance Statistics Engine (MSE) will not run for the first time if no impressions have been logged. Do not disable impressions logging unless you are very familiar with the OpenX architecture, and have a specific reason to do so.

Information Lookup Logging Settings

  • Reverse lookup the hostnames of viewers when not supplied

This setting performs a reverse DNS lookup of the user's IP address when delivering banners, if the hostname is not already set, so that it can be logged to the raw data tables.

  • Try to determine the real IP address of viewers behind a proxy server

This setting causes OpenX to examine the HTTP headers and check if the viewer is coming through a proxy server. If so, the viewer's real IP address is determined and used for logging, if possible.

  • Extract the viewer's operating system and web browser information using phpSniff

"Additional Data" Logging Settings

This setting examines the User-Agent string and extracts the information using the phpSniff application, which allows for the targeting of creatives by broad browser descriptions (e.g. using "Internet Explorer" instead of having to match every possible IE User-Agent string).

  • Store 'User-agent' data when logging
  • Store 'Page Info' data when logging
  • Store 'Referer' data when logging

These three settings control if OpenX should store the viewer's browser user-agent string, information about the page the creative was requested/delivered/clicked on, and/or the referring page to the raw data tables when logging creative requests, impressions and clicks (if the logging of these types is enabled).

The "Page Info" includes the logging of whether the page to which the creative was delivered was using SSL or not, the domain, the page itself, and any query strings passed into the page.

The "Referer" is the page that the viewer was on before they viewed the page the creative was requested/delivered/clicked on.

None of the above data are used by OpenX in any way, so for performance reasons you may want to leave all of these values disabled. However, the data can be useful when debugging OpenX, or if you want to perform your own processing of raw data. In this case, you are welcome to enable the logging.

Block Banner Logging Settings

This section of the screen allows the OpenX administrator to control which hosts/clients will or will not result in raw data being logged to the database.

  • Don't log any statistics for viewers using any of the following IP addresses or hostnames

If the request comes from one of the IP addresses entered, this setting will prevent raw data (requests/impressions/clicks) being logged to the database.

IP addresses can be entered in any of the following formats:

  • One IP address per line; and/or
  • Comma separated; and/or
  • Semi-colon separated.
  • Don't log statistics from clients with any of the following strings in their user-agent

This setting will prevent raw data from being logged to the database if the User-Agent contains any of the string values entered.

The string values that are entered are treated in a case-insensitive fashion, and should be entered as one string per line.

  • Only log statistics from clients with any of the following strings in their user-agent

If the User-Agent does not contain any of the string values entered, this setting will prevent raw data from being logged to the database.

The string values that are entered are treated in a case-insensitive fashion, and should be entered as one string per line.

Note
These three options essentially mean that logging of raw data is performed using the following process:

  1. A raw data item is created, ready to be logged;
  2. If the raw data item IS in the list of IP addresses, then it is NOT logged; otherwise
  3. If the raw data item IS in the list of "User-Agents that should not be excluded", then it IS logged; otherwise
  4. If the raw data item IS in the list of "User-Agents that should be excluded", then it is NOT logged; otherwise
  5. It is logged.
Tip
The IAB produce a list of known spiders and bots that is available to members which is suitable for use in the above settings. However, if you are not an IAB member you can find a database of different User-Agent strings at User-Agents.org.

OpenX recommend that you use at least the following User-Agent strings in the "Don't log statistics from clients with any of the following strings in their user-agent" setting:

  • slurp
  • googlebot
  • msnbot

However, it is recommended that you regularly review the User-Agents that visit your site. This is to ensure that you are not excluding valid User-Agents, and/or allowing invalid User-Agents to log raw data.

Banner storage settings

The banner storage settings are:

  • Allowed banner types: All banner types are enabled by default. If you disable a banner type it will no longer be available for selection when users add banners to the system. See also: Banner types in the OpenX 2.6 User Guide.
  • Webserver local banner storage: You can store banners in a local directory or on an external FTP server. If you change from local storage to FTP storage you must enter host name, directory, login name and password.

Global settings - conversion tracking

In the Global settings > Conversion tracking page you can manage settings for conversion tracking.

  • Conversion tracking is enabled by default. Untick the checkbox if you want to disable this feature.
  • You can specify the number of seconds to allow for the Default Ad Impression Connection Window when you are using conversion tracking.
  • You can specify the number of seconds to allow for the Default Ad Click Connection Window when you are using the conversion tracking feature.

Global settings - database

When you install OpenX you specify which username, password and type of database to use. You can change those settings in the Global settings > Database page. They are stored in the configuration file, and this file must be unlocked to make any changes.

  • Database Type: This field contains the database type you set up for your OpenX installation. OpenX 2.6 supports MySQL and PostgreSQL database types.
  • Database Hostname: This field contains the hostname or the IP address of the database server.
  • Database Port Number: This field contains the port number of the database server. The default port number for a MySQL database is 3306.
  • Database Username: This field contains the username to enter when you want to login to the database.
  • Database Password: This field contains the password to enter when you want to login to the database.
  • Database Name: A database server typically contains a number of databases used for different users and projects. This field contains the name of the database that is set up for your OpenX system.
  • Database Optimisation: If you tick the Use Persistent Connections checkbox you can improve OpenX delivery and even decrease the load on the server. However, this option is not suitable for websites with a lot of visitors because the load on the server can actually increase and become larger than when using normal connections. The benefit of using regular or persistent connections depends on the number of anticipated visitors and the hardware you are using. If OpenX is using too many resources, check this setting. Persistent connections are turned off by default.

Global settings - debug logging

In the Global settings > Debug logging page you can enable or disable the Audit trail feature. You can also manage general debug logging settings. See also:  About the audit trail

Use the Debug logging settings to manage:

  • Enable Debug Logging is set by default.
  • You can Include method names in debug logs.
  • You can Include line numbers in debug logs.
  • The Debug Log Type is set to File.
  • The Debug Log Name, Calendar, SQL Table, or Syslog Facility.
  • You can set the Debug Priority Level to one of:
    • PEAR_LOG_DEBUG - Most information
    • EAR_LOG_INFO - Default information
    • PEAR_LOG_NOTICE
    • PEAR_LOG_WARNING
    • PEAR_LOG_ERR
    • PEAR_LOG_CRIT
    • PEAR_LOG_ALERT
    • PEAR_LOG_EMERG - Least information
  • The Debug Identification String.
  • The mCal, SQL Server Username field contains the SQL server username to use if you are using mCal.
  • The mCal, SQL Server Password field contains the SQL server password to use if you are using mCal.

Global settings - geotargeting

Geotargeting databases identify the geographic location of website visitors based on their IP address. Targeting ads based on location can lead to higher clickthrough rates. These are achieved because you can target creatives at the visitors who are most likely to respond. OpenX offers a free MaxMind geoIP database plug-in that will target ads based on the visitor's country and city information. For more complex targeting, such as targeting based on zip or area code, you can purchase and install other plug-ins from MaxMind.

Visit the MaxMind website for information about the range of geoIP databases you can use with OpenX.

Geotargeting is disabled when you install OpenX. To enable geotargeting

  1. Select the Geotargeting option in the My Account > Global settings tab.
  2. To enable the free MaxMind GeoIP database, simply select this option in the Geotargeting Module Type field and click Save. It is not necessary to enter a pathname.
  3. To enable another MaxMind database that you downloaded, enter the database pathname in the relevant field and click Save. 
  4. You can also Save the GeoIP data in the database logs and Show geotargeting delivery limitations even if GeoIP data unavailable. This option makes it possible to view GeoIP delivery limitations for banners even when the data is not being used.

After you enable the geoIP database you can start applying these as delivery limitations on banners. See also: Banner delivery options in the OpenX 2.6 User Guide for information about applying geotargeting as a banner delivery limitation.

Global settings - maintenance

In the Maintenance Settings section, you can:

  • The Automatically perform maintenance during delivery if scheduled maintenance is not set up option is enabled by default.
  • You can change the Maintenance Operation Interval (minutes) to adjust how often maintenance is performed. OpenX uses this information to calculate delivery priorities. You are unlikely to notice a difference in these priorities for some weeks because OpenX requires several weeks' information before it can make meaningful adjustments to the calculations. It is not advisable to change this value without good reason, or without allowing a reasonable period to elapse before expecting to notice any changes in delivery. 

    Operation intervals are described in detail in the Priorisation engine developer white paper.


  • The option to Delete raw statistics after processing is enbaled by default. This option reduces the amount of information stored in the database.
  • You can change the Grace period before deleting processed statistics (seconds) to reduce (or extend) the amount of time raw statistics are stored in the database before they are deleted.

In the Priority Settings section you can select to Update advertisement priorities immediately when changes made in the UI. Select this checkbox to ensure priorites are updated immediately. When this setting is not selected, advertisement priorities are updated during the next scheduled maintenance.

Always remember to click Save Changes after performing any of the above actions.

Global settings - synchronization

You can instruct OpenX to automatically check for updates to the software. This setting is enabled by default.

Click Save Changes if you change this setting. 

Global settings - user interface

In the Global settings > User interface page you can control various aspects of the user interface and SSL settings.

In the General Settings section you can:

  • Enable and disable the user interface, which is set to 'enabled' by default. If you are using multiple instances of OpenX in your installation you can disable the user interface in all instances except the master version.
  • Application Name: You can specify a custom name for the application.
  • Header File Location: You can enter the location of a header file (JavaScript; HTML) that will be included in the OpenX header.
  • Footer File Location: You can enter the location of a footer file to use.
  • Name of the custom logo file:You can enter the name of a logo file to use.
  • Color of the header foreground: You can specify the colour of the header foreground.
  • Color of the header background: You can specify the colour of the header background.
  • Color of the active tab: You can specify the colour of active tabs.
  • Color of the text in the header: You can specify the colour of the text in the header.
  • Use GZIP Content Compression: You can specify the use of GZIP compression.

In the SSL Settings section you can:

  • With the Force SSL Access on User Interface setting, you can enforce the use of SSL when using the adminstrator interface.
  • You can specify the SSL Port Used by Web Server.

N.B. When logged in as an administrator, if you disable the User Interface and then Save Changes, you will not be able to re-enable the user interface. If you find yourself experiencing this problem, please refer to this page to resolve it.

Managing maintenance operations

In the My Account > Maintenance tab you can manage the settings for a variety of maintenance operations. To manage a setting, select it from the following drop-down menu:

Maintenance: The Maintenance option checks if automatic maintenance is running correctly. If you click the Disable automatic maintenance link, OpenX displays the My Account > Global Setting >Maintenance option, where you can change existing settings.

Banner: OpenX uses a database banner cache speed up the delivery of banners. You must update this cache when you upgrade OpenX, or when you move OpenX from one server to another. If you click the Check banner cache link, OpenX checks your banner cache and notifies you of any errors.

Priority: OpenX calculates campaign priorities automatically. If you want to perform a manual calculation for troubleshooting purposes, click the Recalculate priority link.

Storage: The images used by local banners are usually stored inside the database, but you can store them in a directory to reduce the load on the database and increase speed. The option to move to a directory is available if you select Local directory as a storage option in the Global settings > Delivery settings tab. To change the storage option, enter the correct information in the Public URL and the Local directory fields.

Delivery limitations: Under some unusual circumstances, banner delivery rules can vary from the rules for banners and channels (the Access Control List rules). Click the Check ACLs link to check the rules are up-to-date if delivery priorities are not what you expect them to be.

Append codes: Under some unusual circumstances, banner delivery code can be unaware of tracker append code.  Click the Check append codes to validate the append codes in the database.

Encoding: OpenX 2.6 stores all data in the database in UTF-8 format. Where possible, your data is automatically converted to this encoding when you upgrade from earlier releases of OpenX. If you find corrupt charaters after an upgrade and you know the encoding that was used, you can use this tool to convert the data from that format to UTF-8.

Product updates

The Product Updates page allows you to check on the status of your current OpenX installation and to manage past updates.

Select Check for updates to view the status of the current version of your OpenX installation. This check provides useful information about the version of OpenX that you're running, and the versions of each part of the associated software bundle.

Select the Manage past updates and backups option to view information about your upgrade history, including details of backup tables that exist. From this page you can delete backup tables, logfiles and configuration backups.

User logs

In the My Account > User logs tab, administrators can view:

  • an audit trail of user activity on the system
  • a maintenance log

All events are logged, including user activities and system activities, such as when maintenance runs. The timestamp of each event is recorded and all user activities are associated with the users that performed them.

The audit trail is visible only to users with an administrator or manager role. You can filter the log for a specific advertiser or website, or for a particular day or period. A summary of the user log activities is provided in the Audit trail widget on the Home page.