config.php

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.

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.

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.

Cookie settings

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

• $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

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.