Config.php options

All of the information XenForo needs to connect to your database server is located in the library/config.php file.

Depending upon how you installed XenForo, config.php may have created by copying the contents of the original library/config.php.default file, or the XenForo installer may have created if for you.

Normally, the config file contains just a handful of settings, which are just enough to allow your XenForo to function, but there are a range of additional options that you can add to change the way that XenForo operates.

Warning

These options control fundamental functionality of your XenForo installation, and incorrect configuration may render your site inoperable. If you run into problems, undo your changes to config.php and try again.

Variables in config.php

The following is a list of all settings that can be controlled through config.php. These variable names must be entered exactly as displayed here, or the setting will be ignored. Variable names and values are case-sensitive.

In each case, the variable name is shown with its default value, for example:

$config['variableName'] = 'default-value';


Database connection

  • $config['db']['host'] = 'localhost';
  • $config['db']['port'] = 3306;
  • $config['db']['socket'] = null;

The name or IP address, the port and socket of the database server that hosts your XenForo database. This information will be provided to you by your hosting provider.

  • $config['db']['username'] = '';
  • $config['db']['password'] = '';
  • $config['db']['dbname'] = '';

The username and password you use to connect to your database server, and the name of the database hosted on your server within which your forums are installed.

Advanced options

These options are not included as standard in the config.php, because for the most part, XenForo will use the default values. If you decide to use any of these settings, be sure to fully test the operation of your forums before leaving the system to run in a production environment.

Site-wide feature disable

Some XenForo systems can disabled completely from the config file, without having to enter the Admin control panel at all. Setting any of these options to false will disable the corresponding functionality entirely.

Note

If a system is disabled through the config.php file, it can not be re-enabled through the Admin control panel - only an edit to the config file will restore the system's functionality.

The descriptions for these settings describe what will happen if you set their value to false.

  • $config['enableMail'] = true;
  • $config['enableListeners'] = true;
  • $config['enableTemplateModificationCallbacks'] = true;
  • $config['enableGzip'] = true;
  • $config['enableContentLength'] = true;
  • $config['enableTfa'] = true;
  • $config['enableClickjackingProtection'] = true;
  • $config['enableReverseTabnabbingProtection'] = true;

enableMail

Completely disables all email-sending features throughout XenForo. No email will be sent at all, ever.

enableListeners

Disables all code event listeners in XenForo. This will largely turn off all add-on functionality, and can be useful for recovering access to your system and control panel if an add-on has gone wrong and broken your ability to do so.

enableTemplateModificationCallbacks

Disables the ability of template modifications to perform their operation using a PHP callback. Similarly to enableListeners, this switch can be used to regain access to a system rendered inoperable by a broken callback.

enableGzip

By default, XenForo will compress the final HTML and CSS output of pages it generates using the gzip compression system, which is then invisibly decompressed by your visitors' browsers when the data is received. This can significantly speed up page loading times, but if you want to disable this feature and have the HTML and CSS sent as uncompressed plain text, disable this setting.

enableContentLength

Normally, XenForo will send a Content-Length HTTP header. In some server configurations, the content may be modified between XenForo sending it and it being received by the end user. In this situation, the Content-Length header may not be updated correctly so it should be disabled.

enableTfa

Disables two-factor authentication (2FA), the system whereby users need to log in with a username and password, and an additonal piece of information, such as a code from their phone. Useful if you have lost access to your admin control panel, or if you want to prevent any users from employing 2FA at all.

enableClickjackingProtection

Normally, XenForo sends the X-Frame-Options HTTP header with a value of SAMEORIGIN as a means to prevent click-jacking from malicious scripts.

When enabled, this option prevents clickjacking attacks by placing your forum in an iframe and tricking the user into clicking something. However, this can also disable valid uses of iframe embedding. Disable this only if you understand the implications.

enableReverseTabnabbingProtection

When enabled, this option prevents reverse tabnabbing-based phishing attacks that are triggered when your users click links to external sites. However, this protection may interfere with external services that rely on changing how link clicks are processed (such as to include affiliate links). Disable this only if you understand the implications.

If you need to configure settings for how cookies are set on your visitors' browsers, you can use the following settings, but be warned, incorrect or invalid values for these settings may leave you and your visitors unable to log in to your XenForo user account, including the admin control panel.

The primary reason for changing these values is to accommodate multiple XenForo installations on the same domain. If you have only a single XenForo installation on your domain, there is no need to change these settings.

Only change these values if you really need to, and you know what you're doing. If you encounter problems, reset these values to their defaults.

  • $config['cookie']['prefix'] = 'xf_';

All cookies are identified by name, and the names of cookies set by XenForo are all normally prefixed with xf_ to allow them to be distinguished from cookies set by other systems. One consequence of changing this value is that it will reset the Remember me setting for all your logged in visitors, who will need to log in again on their next visit to your site.

The value of your prefix should use letters, numbers and underscores only, and is case-sensitive.

  • $config['cookie']['path'] = '/';

Using the default value of /, cookies set by XenForo will be available in all areas of your website. If you need to change this so that XenForo cookies are only available within a specific part of your website, change the value to include the directory path to the correct area of your site, starting with the root location of your site, /.

Example values

  • '/' XenForo cookies are available to all areas of your website.
  • '/forum/' XenForo cookies can only be read by pages located within the forum directory, which resides at 'http://example.com/forum', where example.com is your site address.
  • '/path/to/other/folder/' XenForo cookies can only be read by pages located in the path/to/other/folder directory, located at http://example.com/path/to/other/folder.
    • Cookies can not be read by pages located in folders above this location, ie:
    • http://example.com/path
    • http://example.com/path/to
    • http://example.com/path/to/other

Warning

If you specify a cookie path that does not allow cookies to be set within the XenForo root directory, XenForo will be unable to read the cookies it sets, and critical operations like logging in will fail.

  • $config['cookie']['domain'] = '';

Similiar to the cookie path setting, this allows you to specify a domain upon which your cookies can be read. It is unusual to need to set this value to anything other than the default, but as with the cookie path, you should be very careful if you change it, because entering a value that prevents XenForo from reading its own cookies will break important functionality, like the ability to stay logged in.

The reason for setting this value would be to allow cookies to be shared on multiple subdomains, for example a setting of .example.com would allow cookies to be accessed on all subdomains of example.com, such as www.example.com and other.example.com. In most instances, this setting can be left with its default setting.

Example values

  • '' allows cookies to be read only on the domain on which they were set
  • '.example.com' allows cookies to be read on example.com and any subdomain thereof
  • 'subdomain.example.com' allows cookies to be read only on subdomain.example.com

Data and script locations

If you want to change the location that XenForo stores the data and scripts it keeps in files, such as avatars, attachments and javascript files, you can do so by altering these settings.

  • $config['externalDataPath'] = 'data';
  • $config['externalDataUrl'] = 'data';
  • $config['internalDataPath'] = 'internal_data';
  • $config['javaScriptUrl'] = 'js';

Path variables

In each of these cases, a variable name ending with Path refers to an internal file system path on the server, relative to the directory in which XenForo is installed. Relative paths start at the XenForo installation directory. This can be set outside the web root.

If your XenForo installation lives at /users/yourname/htdocs/xenforo, then the following examples show how different values relate to this path:

  • data - /users/yourname/htdocs/xenforo/data
  • ../another-folder - /users/yourname/htdocs/another-folder

These variables can also use an absolute path from the server root, such as /users/yourname/htdocs/xenforo/data.

URL variables

Variables whose name ends with Url refer to a the path relative to your XenForo directory as visible from your web root. Relative URLs start at your XenForo installation directory. If your XenForo installation resides at http://example.com/xenforo, the following examples show how different values will be evaluated:

  • data - http://example.com/xenforo/data
  • ../another-folder - http://example.com/another-folder
  • /a-root-folder - http://example.com/a-root-folder
  • /xenforo/my-folder - http://example.com/xenforo/my-folder

You may a full URL, including the domain name, such as:

  • http://example.com/xenforo/data
  • //example.com/xenforo/data

Warning

Directories specified as paths must be writeable by the web server (chmod 777) or data will not be able to be stored in these locations by XenForo.

If any of these paths and URLs are set incorrectly, important XenForo functionality will be broken. Change them only if you know exactly what you're doing.

externalDataPath

This defines the path to the 'data' directory, in which XenForo keeps files that are served directly to the browser through the web server, such as avatar images and attachment thumbnails. This directory must be within the web root.

externalDataUrl

Defines the location of the 'data' directory, in which XenForo keeps avatars and attachment thumbnails, as visible from your web server.

internalDataPath

Defines the path to the 'internal_data' directory, which contains files that are not served directly to web browser clients, such as attachments.

javaScriptUrl

Defines the location of the 'js' folder, in which XenForo expects to find the JavaScript files necessary for its functionality, as a path on the public web server. This directory must be within the web root.

Database adapter

  • $config['db']['adapterNamespace'] = 'Zend_Db_Adapter';

Controls the database connection adapter class that will be used.

Cache settings

For large XenForo sites, it can be advantageous to use a cache mechanism to speed up page generation.

The settings for caching all fall within the $config['cache'] section, and are discussed in more detail in the Cache section of this manual.

If you configure a cache, you can disable it at any time by setting the value of this option to false:

  • $config['cache']['enabled'] = false;

Cache settings

Other variables

  • $config['superAdmins'] = 1;

This is a comma-separated list of user IDs that are considered super administrators. Super administrators can create/delete other administrators and always access all parts of the control panel.

  • $config['rebuildMaxExecution'] = 8;

When performing data rebuilds or long running processes, they will only run for this number of seconds before the page is reloaded. Increasing this number can improve rebuild performance marginally, but some servers may forcibly kill the PHP process.

  • $config['globalSalt'] = '[%GLOBAL_SALT%]';

This variable defines a secret value which is used to salt the values of various caches, cookies and other data for the purpose of preventing the data being stolen or faked by malicious agents. Never reveal the global salt value to anyone as this would compromise the security of your XenForo installation.

Normally, XenForo will generate its own secure global salt, and you will only need to change it if you want to define your own.

  • $config['checkVersion'] = true;

If enabled, the system will check that the version number stored in the XenForo PHP scripts matches with the version number stored in your XenForo database, and will prevent access to the forums by regular visitors if the numbers do not match, as would be the case when you have just uploaded the files ready to run an upgrade, but have not actually run the upgrade process yet.

  • $config['passwordIterations'] = 10;

Configures the strength of the bcrypt-based password storage system. Higher numbers are more secure but each increment in the value of this setting will roughly double the amount of time it takes to generate or validate a password, leading to higher server usage.

  • $config['maxImageResizePixelCount'] = 20000000;

The maximum size of an image (in total numbers of pixels) that XenForo will attempt to resize. Images larger than this will simply not be resized and thus may be rejected. This is calculated using width × height.

  • $config['adminLogLength'] = 60;

The number of days to keep the log of all administrator activities in the admin control panel. After this number of days have elapsed since an action was logged, it will be pruned from the database.

  • $config['chmodWritableValue'] = 0;

If this value is non-zero, all files created by XenForo will be automatically chmodded to this value. Directories will be chmodded to this value as well, though they will also always be user-, group-, and world-executable as well. In most situations, XenForo will determine the correct chmod value automatically.

  • $config['jsVersion'] = ''; This value can be changed to force a refresh of all JS files. For developers, this has been superseded by the jsLastUpdate option.

  • $config['untrustedHttpClient'] = 'array()'; When XenForo makes an HTTP call to an untrusted external server, you may specify a specific adapter configuration. For example, this allows you to use an HTTP proxy service to stop your application server's IP from being leaked. The value should be an adapter configuration array like given in this Zend_Http_Client_Adapter_Proxy example.

Debug mode

Debug mode is a special state in which XenForo will run for debugging or development purposes.

  • $config['debug'] = false;

Setting this to true is necessary for certain functionality to operate, including Designer mode and Developer mode.

Warning

Never, never enable debug mode on a live production site exposed to the Internet.

Not only will execution and page generation run significantly more slowly than with debug mode disabled, but important information such as the state of internal SQL queries can be revealed to visiting users. Only enable debug mode if you are working on a private XenForo installation that is protected from any potential malicious visitors.