Website Configuration Reference

From Sympl Wiki
Jump to navigation Jump to search

This page is a detailed breakdown of all the configuration options and files available when configuring website hosting on Sympl.

As with all the other documentation here, the site will used, and you should substitute this for your domain.

All configuration for this domain will be in the /srv/ directory.

Sympl uses the Apache web server, along with the relevant version of PHP for your version of Debian, along with the typical PHP extensions. See Supported PHP Versions.

Getting Started

The files for are in the /srv/ directory which is the site root.

  • If this directory doesn't exist, is empty, or has no index.php or index.html, the default page will be served, mentioning there is no content on the site.
  • The content in the directory will be served for both and, so theres no need to prefix the domain with www.
  • If you want to serve different content for and, you can create /srv/ as a separate directory.
  • Within an hour of the directory creation, a new configuration will automatically be created for Apache.

More detailed information about how Sympl serves content can be found at How Web Hosting Works on Sympl.

Testing Your Sites

New sites can be tested before they are made live using the 'testing' domains. If your hosting provider provides a wildcard DNS entry on your server pointing to its hostname (and the default site is set to match), then sites can be accessed via this method.

You can confirm if this is the case using dig or a similar tool - if your server is named, if you run dig +short and get a response with the server's IP address, then this is the case.

If so, you can access any of the sites via this method in the format <domain_directory>.testing.<server_hostname>, for example Note that the www. should not be included in this case.

Note that this only applies to websites (not email, FTP and similar), and will not work fully in all instances, as some sites will redirect to their expected hostname or similar. If this is the case, you can test by editing your hosts file on your local computer.

Serving the Same Content on Multiple Domains.

In some cases you may want to accept traffic for and serve the same content for multiple domains, such as WordPress multi-site configurations.

Both of these assume you have the main site already configured and working.

Aliasing the Whole Domain

The most simple option is to alias the whole domain. This will result in the whole configuration including other services such as email, SSL certificates, and FTP sites all sharing the same domain.

To do this, you only need to create a symbolic link to the directory of the site you want to alias. Aliasing (new domain) to (existing domain) you would use

ln -s /srv/ /srv/

Aliasing the Web Content Only

Slightly more complicated, but more flexible is to alias only the public/ or public/htdocs/ directory. This allows separate email, SSL certificates and individual, which don't reference the main domain. Some sites access content at the directory above htdocs/, in which case you should link at the public/ point, otherwise public/htdocs/ is usually preferable as it provides separate logging and allows individual FTP access.

In the examples below, is the site which already exists, and is the new domain.

Aliasing public/htdocs/ Only

mkdir -p /srv/
ln -s /srv/ /srv/
touch /srv/

Aliassing public/ and Subdirectories

mkdir -p /srv/
ln -s /srv/ /srv/
touch /srv/

A Note on PHP Security

By default, PHP processes are restricted to the specific public/ directory. This is fine in normal use, but as the links created above are resolved to their targets, they don't match the paths expected and will cause PHP errors. As a workaround, creating the config/disable-php-security file for the new alias disables this restriction, slightly reducing security of the sites.

The next major update for sympl-web is expected to resolve this meaning the workaround is no longer needed.

Serving Content on an Alternate IP Address.

Note that the IP addresses must be valid IPs allocated and routed to your server for this to function.

By default, Sympl uses the primary IP addresses (both IPv4 and IPv6) to serve content on. To override this and serve content via another IP address, add the IPs to /srv/, followed by sudo sympl-configure-ips to automatically add the IP addresses to the relevant interface, and sudo sympl-configure-ips to adjust the apache configuration to use the new IPs, at which point you should update the DNS for the domain.

Enforcing HTTPS

By default, Sympl will attempt to download a Let's Encrypt SSL certificate for each site automatically, and will then adjust the Apache configuration to enable it.

In many cases you will likely want to enforce HTTPS usage on a domain to ensure end-to-end security, and this can be done easily by creating the file /srv/

This change will take effect automatically within the next hour, but requires a working certificate.

HTTP Strict Transport Security (HSTS)

Once SSL has been enforced, you may also want to ensure users only ever access the site via HTTPS. This can be done by enabling HSTS, which instructs the users browser to only connect via HTTPS for the next six months.

You should ensure the site is working properly via HTTPS before enabling this function, but once done, create the file /srv/ and the configuration will be updated within the next hour.

Redirecting to a Preferred Domain

In the event you want to force all traffic to the same domain name, this can be done with an Apache rewrite. This this example, we want to ensure the domain being used is always, preventing anyone from using without the www..

To do this, you would create a file named .htaccess in the htdocs/ directory with this content:

RewriteEngine on
RewriteCond %{HTTP_HOST} !^www.*$ [NC]
RewriteRule ^(.*)$ http://www.%{HTTP_HOST}/$1 [R=302,L]

What this set of rules do is:

  1. Enable the rewriting of content.
  2. If the hostname being used does not start with 'www.' (case insensitive)
  3. Temporarily redirect the request to the same hostname but with 'www.' added and don't process any rules.

Once this is working as expected, you can change the R=302 to R=301 to swap the temporary redirect to a permanent one which will be cached by the browser.

More information is available at Apache Rewrites.

PHP Security

By default, a number of rules are included in the Apache configuration which limit the access of sites running PHP, preventing a compromised site from accessing content outside the /srv/ directory, and setting both a domain specific temp directory and session directory as /srv/ and /srv/ respectively.

A default configuration is also in place for the ever-popular WordPress, which prevents PHP files from being accessed or executed from within the upload folder, which tend to be the source of most site compromises.

These restrictions can be disabled by creating the file /srv/, and running sudo sympl-web-configure.

PHP Lockdown

Also available but not enabled by default is a 'lockdown' configuration, which limits a number of potentially dangerous functions in PHP for all sites when being run by Apache.

This can be enabled with the command line...

For Sympl 9.x

sudo ln -s /etc/php/7.0/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini
sudo service apache2 reload

For Sympl 10.x

sudo ln -s /etc/php/7.3/mods-available/sympl-web-lockdown.ini /etc/php/7.0/apache2/conf.d/01-sympl-web-lockdown.ini
sudo service apache2 reload

Note that this will significantly restrict PHP access, and will affect all sites on the same server, so you should confirm that all sites work as expected once this has been run.

Filesystem Permissions

By default, Sympl adjusts the permissions of files and directories in /srv/ to ensure web applications can update themselves correctly, and FTP users can make changes as desired.

This defaults to changing the files and directories to be readable, writable, and owned by the www-data user and the www-data group (which the sympl user is a member of). These defaults can be changed by placing the name or ID of the desired user and group into config/public-user and config/public-group.

This functionality can be coupled with individual PHP instances for each site (not yet implemented in Sympl) or can be disabled on each domain by creating the file /srv/

See Filesystem Security for more information.


By default, the Apache logs are written to /srv/, named as either access.log and error.log for HTTP requests, and ssl_access.log and ssl_error.log for HTTPS.

These are automatically rotated daily, and compressed after two days.

For any sites being served with mass hosting, the logs can be found at /var/log/apache2/zz-mass-hosting.access.log and /var/log/apache2/zz-mass-hosting.error.log .

Logging for any other traffic is written to /var/log/apache2/other_vhosts_access.log, with any errors for Apache itself at /var/log/apache2/error.log.

Web Statistics

Basic traffic statistics can be optionally generated for the domain from the web logs using AWFFull (or Webalizer on Sympl 10 and older), and are written to /srv/, making them available at

To trigger the generation, create a file at /srv/, and they will be generated automatically overnight for the previous day(s).

As they contain potentially sensitive information (i.e. client IPs), they are automatically protected by a username and password. To access them you must create a username and password in config/stats-htaccess using htpasswd:

Note: If the file already exists, you should omit the -c parameter or a fresh configuration file will be created and overwrite anything there.

htpasswd -c /srv/ username

You will be prompted for a password and confirmation, and you will then be able to log in.

A template for Webalizer will automatically be written to config/webalizer.conf when the statistics are created, and this can be edited as desired.

CGI Scripts

CGI Scripts are executable code of some kind (binaries or scripts) which are run directly on the operating system, and return the content for a page. Due to them being executable they can be a security risk, so caution should be taken when using them. Usage of CGI Scripts has mostly been supplanted by PHP, however some legacy code

To use CGI Scripts on your domain, you should copy them to /srv/ and they will then be served at as long as the files are set executable. Non-executable files will result in an error message rather than serving the content of the file.

Any files in the public/cgi-bin will not have their permissions updated by sympl-filesystem-security, so it is up to the user to ensure they are set securely, and readable only by the relevant users. Typically they are not be expected to be writable.

Custom Additions to the Apache Configuration

For sites with individual configuration files, custom additions can be made to the Apache configuration by adding files with the .conf extension to /srv/ These will be read when Apache is reloaded or started, and can be used to make changes to the configuration without using .htaccess files.

The configuration can be tested with sudo apachectl -t and Apache reloaded with sudo service apache2 reload.

Extreme care should be taken when using this feature, as an invalid configuration will prevent Apache from starting, as as such is considered a feature for advanced users only.

Further Modifying the Apache Configuration

The majority of typical changes to the Apache configuration can be made via relevant .htaccess files, with most of others available via conf/apache.d/.

In the event you need to make custom changes to the Apache configuration for an individual site, configuration files can be found in /etc/apache/sites-enabled. Note that if you do make any changes, the configuration will no longer be managed by Sympl and it won't make any changes if the templates are updated. If you want to revert to a Sympl generated configuration for a specific domain, you can do this with sudo sympl-web-configure --verbose

If you want to update the configuration of all sites, then you can edit the templates used to generate the Apache configurations, but you should take care when making any changes to ensure the result is valid. These can be found in /etc/sympl/apache.d, and the existing templated configurations can be regenerated with sudo sympl-web-configure --verbose. Note that any changes to the template files will prevent the templates from being automatically updated, pause updates to the sympl-web package until

Finally, if you want to create your own Apache configurations not managed by Sympl you can do, as it will not make any changes to them.

Configuration Reference

File or Directory Used For
.../config/ip Contains a list of IP addresses which a website will be bound to. Defaults to the primary IPs (IPv4 and IPv6) of your server. More...
.../config/ssl-only Redirects all non-HTTPS traffic for the site to HTTPS. More...
.../config/hsts Enables HSTS for HTTPS sites. More...
.../config/disable-php-security Existence of this file will disable some of the PHP security functions in the automatically generated Apache configurations. More...
.../config/disable-filesystem-security Existence of this file will disable the automatic filesystem security tasks on this domain. More...
.../config/public-user UID or user name of the user to change ownership of the public/ directory to. Defaults to www-data. More...
.../config/public-group GID or group name of the user to change ownership of the public/ directory to. Defaults to www-data. More...
.../config/stats This file enables automatic generation of web stats with Awffull/Webalizer More...
.../config/stats-htaccess A 'htpasswd' format file used to access the web stats. More...
.../config/apache.d/example.conf Apache config files to be included in the site configuration. More...

See also Configuration Reference for other configuration files.