How to configure the Safe Mode Hack

While trying to install Contao with the install tool, you might have seen a warning that the local configuration file is not writable.

File permission issues ¶

The term "Safe Mode Hack" is actually misleading, because it implies that the problem was caused by the PHP safe_mode. However, it is caused by insufficient file permissions and can occur even if safe_mode is disabled, so it should be called "File Permission Hack" instead. PHP as an Apache module is typically run as wwwrun, www-data or nobody, whereas the files that you uploaded via FTP belong to you (e.g. web4 or ab5678). The server therefore denies the PHP script Contao access to those files.

Using FTP for file operations

To work around the permission problem, Contao establishes an FTP connection to modify files and folders. All you have to do is to enter your FTP login details in the local configuration file (system/config/localconfig.php).

$GLOBALS['TL_CONFIG']['useFTP']  = true;
$GLOBALS['TL_CONFIG']['ftpHost'] = 'domain.com';
$GLOBALS['TL_CONFIG']['ftpPath'] = 'httpdocs/';
$GLOBALS['TL_CONFIG']['ftpUser'] = 'ab5678';
$GLOBALS['TL_CONFIG']['ftpPass'] = '********';

Replace the login details above with your own and take special care when entering the ftpPath, which is the relative path from the FTP root directory to the Contao folder (e.g. html/, public_html/ or httpdocs/). The FTP root path is usually not the same as the document root path!

Setting write permissions

Obviously, the third-party plugins that are bundled with Contao are not using the Safe Mode Hack, so you have to adjust a few folder permissions to allow write access. Use your FTP program or SSH terminal to make the following folders writable (CHMOD 777). Despite what you might have read in a tutorial or the forums, onlythese three folders need to be modified when using the Safe Mode Hack!

• system/html
• system/logs
• system/tmp

From version 2.7.3 these folder permissions should be set automatically.

Checking the FTP connection

To check whether you have set the correct ftpPath, click the Check FTP connection button.