Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

Step 3: Create settings.php and the files directory

Last updated on
September 7, 2016 - 13:34

Drupal Config File "settings.php" and "services.yml" Overview

In order for Drupal to work, you have to configure where the database is, what the database is called, and the database credentials to access the database. This information is stored in the settings.php file which is located in:

sites/default

The settings.php file is common to Drupal 6, 7 and 8

When you first extract Drupal, it doesn't come with a settings.php file, instead it comes with default.settings.php. When you first install Drupal 7, it will attempt to copy and rename default.settings.php -> settings.php for you. There are some rare instances where you will need to do this manually which are covered in detail further down on this page.

New to Drupal 8 in the sites/default folder, is a file named default.services.yml. Just like default.settings.php, default.services.yml has to be renamed in order to work. However, this file is designed for overriding the core services.yml file if you need to override it and 99% of sites out there, won't ever need to override the core services.yml file. It is made available if you do need to override those settings though. In early development, this file was automatically copied and renamed during install, however Stop creating services.yml by default supersedes the early method. In other words, don't ever worry about default.services.yml / services.yml unless something tells you otherwise.

Finally, the purpose of having default.[config-file].php is so you can easily update Drupal, without overwriting the entire configuration that runs your site. Yes, there was a time when that happened...

Automatic settings.php Overview

By default, Drupal 7 and 8 will attempt to create and populate the settings.php file automatically when you use install.php to setup the site. The script also changes the permission on the file to secure it once it is finished and then creates a sites/default/files directory for housing all of your non-core files. Unfortunately, some types of shared/local hosting are configured so PHP and Apache run as the same user. This might result in the install script failing to execute the creation and population of the settings.php file, along with setting permissions and creating the files directory. If you get errors referring to the Settings file during installation, you will have to manually create the settings.php file and do a few more tasks before you can run install.php. Once it is created with write permissions, the installation script will automatically populate the proper information for your site config. Afterwards, you will have to re-secure the settings.php file.

At this point, jump to the next page step: Step 4: Run the installation script. If you run into problems with the installation due to the Settings, come back here and follow the Manual steps outlined below.

Manual settings.php Overview

Drupal 6, 7 and 8 come with a sample settings.php configuration file located at: sites/default/default.settings.php
Before you run the installation script (install.php), you need to copy default.settings.php file as a new file called settings.php and change its permissions to be writeable. After the installation, you will need to restrict the permissions again.

Manual settings.php Detailed Instructions

Step 1 - Navigation & Creation

Navigate to sites/default of your root Drupal install.

Copy the default.settings.php file and save the new file as settings.php in the same directory (see note below about renaming). If you have shell access (command line) run the following command from the directory that contains your Drupal installation files:


cp sites/default/default.settings.php sites/default/settings.php 

Note: Do not simply rename the file. The Drupal installer needs both files.

If you only have FTP access, you will have to download the file to your computer, rename it, then upload it. Some hosting providers have a file manager on the dashboard where the file can be copied and renamed.

Step 2 - Check the Permissions Are Writeable

By default, the sites/default directory and the settings.php file should be writeable. You can check that the permissions of sites/default and settings.php are writeable by issuing the following commands:


ls -l sites/ 

Permission on sites/default should be 755 [drwxr-xr-x]:


ls -l sites/default/settings.php 

Permission on settings.php should be 644 [-rw-r--r--]:

If they are anything but writeable, you can issue the following commands:


chmod 644 sites/default/settings.php 

Note: If you are in the same group as the web user, then changing the permissions to 664 will be sufficient.

Several FTP tools like Filezilla, Transmit, and Fetch allow you to change file permissions, using a 'file attribute' or 'get info' command. In this case the file permission should be set to 644. If your FTP client has checkboxes for setting permissions, check both the Read and Write boxes for "Owner", "Group", and "Others" (but leave the Execute boxes unchecked). For some situations, you may need a permission of 664. Some hosting providers allow a similar operation through the dashboard file manager.

Step 3 - Try the Install

At this point, give the install a go. See if you can get through the installation by running http://[yoursite]/install.php. If you are successful, the first page you will want to visit is Reports -> Status report (admin/reports/status)

On the reports page, look for a line that says: File system. If it says anything other than "Writeable", you will need to follow Step 4 below.

Next, look for a line that says: Configuration file. If it says anything other than "Protected", then you will need to re-secure the configuration files as described in Step 5 below.

Step 4 - Create the Files Directory

The installation should have created the sites/default/files directory for you, but in the off chance it didn't, you will need to create it manually and set the right permissions on it.


mkdir sites/default/files 

Note:On most linux systems, a newly created directory is already setup with the 755 permission. In case it isn't, you can issue the command:


chmod 755 sites/default/files 

This sets the files directory to 755 [drwx-rw-rw].

Depending on how your apache configuration is setup, you might have to instead run:


chmod 777 sites/default/files 

This sets the files directory to 777 [drwxrwxrwx]. It is less secure than 755, but there's nothing you can do about it if that's how your server is setup.

Step 5 - Post Install Permission Check

After the installation script has run, Drupal tries to set the permissions automatically to:

555 (read-execute) [dr-xr-xr-x] for the sites/default folder.
and
444 (read-only) [-r--r--r--] for the settings.php

If not, you will need to manually set them:


chmod 555 sites/default 

chmod 444 sites/default/settings.php 

These permissions are correct, and should not be changed, because changing these opens up a security risk.

OS specific instructions

Fedora Linux settings.php notes

If you have clean Fedora (or RHEL, CentOS, Scientific Linux) you have SELinux enabled by default after clean installation. There are few more steps to be done to be able to finish Drupal installation on SELinux enabled site to gain more security by SELinux.

If you don't want to use SELinux you may simply disable it, but this is not recommended as SELinux is able to block some exploits. Also you may turn SELinux into permissive mode to go through creating the settings.php file (because even if you have set the permissions for writing to settings.php, the install script will think you don't because SELinux is active and is blocking writing to settings.php file).

To go through installation, do this (as root):

  1. Enable allow_httpd_anon_write boolean:
    
    
    setsebool allow_httpd_anon_write=1 
  2. Change type of default directory and settings.php to public_content_rw_t (whole command is in one line):
    
    
    chcon -t public_content_rw_t sites/default sites/default/settings.php sites/default/files 

After the installation finishes, revert previous settings to benefit from SELinux:

  1. Disable allow_httpd_anon_write boolean:
    
    
    setsebool allow_httpd_anon_write=0 
  2. Reset security context:
    
    
    chcon -R -t httpd_sys_content_t sites/default 

OS X settings.php notes

For information about setting up a local MAMP (Mac, Apache, MySQL, and PHP) server, see HowTo: Create a local environment using MAMP.

For an external server, follow these steps:

Note: If you're using Snow Leopard, you must first enable the GD library. Unlike previous versions of OS X, Snow Leopard comes with a version of PHP that supports the GD library without having to recompile PHP. To enable the GD library in PHP, edit the /etc/php.ini file, and then remove the initial semicolon (which comments the line) from the following line:


;extension=php_gd2.dll 

After you remove the semi-colon, restart the Apache server. The GD libraries will then be available in PHP.

Rebuild PHP5 to include the GD tools according to the instructions here.

  1. Install Drupal 7.0 as /Users/xxx/Sites/drupal, where user xxx is in the _www group, and ensuring that the entire installation is group-writable. Create a soft link from
    /Library/WebServer/Documents/xxx to /Users/xxx/Sites.
  2. Re-writing seems to be enabled by default in Apache2 on Leopard. Enable PHP5 and virtual hosts in Apache2 by uncommenting the following lines in /etc/apache2/httpd.conf:
    
    
    #Dynamic Shared Object (DSO) Support #LoadModule libexec/apache2/libphp5.so #Virtual hosts (This is just a marker for what follows so you should leave the #.) #Include /private/etc/apache2/extra/httpd-vhosts.conf 
  3. Add a virtual host stanza to the /private/etc/apache2/extra/httpd-vhosts.conf file that has at least this in it:
    
    
    <VirtualHost *:80> DocumentRoot /Library/WebServer/Documents ServerName localhost <Directory /Library/WebServer/Documents> Options FollowSymLinks Indexes MultiViews AllowOverride All Order allow,deny Allow from all </Directory> </VirtualHost> 
  4. Add a variant of the RewriteBase /drupal line in the stock /Users/xxx/Sites/drupal/.htaccess file:
    
    
    IfModule mod_rewrite. RewriteEngine on # Modify the RewriteBase if you are using Drupal in a subdirectory or in a # VirtualDocumentRoot and the rewrite rules are not working properly. # For example if your site is at <a href="http://example.com/drupal" title="http://example.com/drupal" rel="nofollow">http://example.com/drupal</a> uncomment and # modify the following line: # RewriteBase /drupal RewriteBase /xxx/drupal # Rewrite URLs of the form & to the form index.php?q=x&. RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_URI} !=/favicon.ico<br /> RewriteRule ^(.*)$ index.php?q=$1 [L,QSA] IfModule 
  5. Make a copy of the /Users/xxx/Sites/drupal/sites/default directory tree as /Users/xxx/Sites/drupal/sites/localhost., and make sure this directory is writable by the _www group.
  6. Manually create the database in MySQL. Make a copy of
    /Users/xxx/Sites/drupal/sites/localhost/default.settings.php file as
    /Users/xxx/Sites/drupal/sites/settings.php, and then make this file writable by the _www group.

    Configure the database in /Users/xxx/Sites/drupal/sites/settings.php:

    
    
    $databases['default']['default'] = array( 'driver' => 'mysql', 'database' => 'databasename', 'username' => 'username', 'password' => 'password', 'host' => 'localhost', 'prefix' => 'main_', 'collation' => 'utf8_general_ci', ); 

You're now ready to install Drupal on your external server. Continue to Step 4: Run the installation script.

Windows (IIS) settings.php notes

On a Windows computer using Internet Information Server (IIS), complete the following steps:

  1. Right-click sites\default\settings.php.
  2. Grant Write permissions to IUSR_MachineName (IIS6) or IUSR (IIS7).

Note: On Windows Server 2008, you can also do this from the command line by running the following command from your sites\default directory:


icacls settings.php /grant IUSR:W 

The installer will change the file back to Read Only after installation, but you should verify this after installation.

For more information about modifying Windows file permissions, see the Troubleshooting FAQ.