Website Configuration Reference

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 example.com will used, and you should substitute this for your domain.

All configuration for this domain will be in the /srv/example.com/ 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 example.com are in the /srv/example.com/public/htdocs 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 www.example.com and example.com, so theres no need to prefix the domain with www.
• If you want to serve different content for www.example.com and example.com, you can create /srv/www.example.com 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 server.example.host, if you run dig +short randomname.server.example.host 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 example.com.testing.server.example.host. 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.

PHP Configuration

PHP is the scripting language which the popular Content Management Systems and most websites is written in. It's very popular due to it's flexibility and ease of use, which means that the development of PHP moves quickly, with new versions released every year or so.

With PHP development moving quickly, the Debian release cycle being every two years, and the common need to run sites on older versions, it's not uncommon to see an instance where you need a different version of PHP than the one bundled with the operating system.

Selecting a PHP Version

This isn't currently possible to do automatically on Sympl 11 and earlier, there are community-supported work-arounds. Sympl 12 adds support for selectable PHP versions, and this functionality is being back-ported to earlier versions.

This section refers to functionality which is only in Sympl 12, but will be back-ported to other versions.

To select a PHP version for a specific site, place the PHP major and minor versions (such as '5.6', '7.3' or '8.1') in the file config/php and run sudo sympl-php-configure.

This will then install the relevant PHP version from https://deb.sury.org if required, along with the typical PHP packages, and configure the site to use that PHP version. Note there is a small extra disk space requirement for each extra version of PHP installed.

If other PHP modules/extensions are required for the site, their package names can be placed in config/php-modules, and they will be installed automatically the next time sudo sympl-php-configure is run. Package names are the name of the Debian packaged modules without the PHP version, so the php8.1-tidy package would be listed in the file as tidy. PHP extensions can also be installed manually using apt.

All sites default to a pool named 'default' unless specified otherwise in config/php-pool. If you require any configuration changes, or wish to adjust resources for a site, you should configure it with it's own pool. Note that each pool has its own memory requirements and PHP instances standing by, so running a large number of pools will consume more RAM on your server.

.htaccess vs .user.ini

This section refers to functionality which is only in Sympl 12, but will be back-ported to other versions.

When using the default PHP version (ie: not specifying one) the site will run under the default PHP version for the distribution (ie: PHP 8.2 for Debian Bookworm) using 'mod_apache'. This will parse PHP variables and overrides via the .htaccess file in the web content directory, allowing you to make changes on a per-directory basis.

Running a site under 'FPM' as the configured sites do means they are only passed the relevant file, so require the same configuration entries in a slightly different format in the file .user.ini file, in the same location as .htaccess.

If you don't already have a .user.ini file in place, Sympl will automatically create and manage one for you each time sudo sympl-php-configure is run.

PHP Command Line

This section refers to functionality which is only in Sympl 12, but will be back-ported to other versions.

In some instances, you may need to run the PHP from the command line but need a version other than the default. To do so, rather than using the plain php example.php command, simply append the version, for example php8.1 example.php.

Extended Configuration

This section refers to functionality which is only in Sympl 12, but will be back-ported to other versions.

Sympl supports a number of other extended configuration options, including selectable user and group that the PHP pool should be executed as, with config/php-user and config/php-group respectively. These default to www-data, but if must exist if they are changed, and cannot be system users (ie: with an ID below 1000). Note that these settings also inherit the values of public-user and public-group if set.

As the PHP pool files are managed automatically by Sympl to ensure that PHP continues running, manual changes to the pool configurations will be overwritten on each run. If a change to a pool configuration is required, extra configuration lines can be added to /etc/sympl/php/<version>/includes.d/<pool_name>.conf. The pool name is defined as <pool_name>[_<username>[_<groupname>]] with the username and group being optional if not left on the default.

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/example.com/public/ directory, and setting both a domain-specific temp directory and session directory as /srv/example.com/php_tmp/ and /srv/example.com/php_sessions/ 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/example.com/config/disable-php-security, 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 where a PHP version is not selected.

This can be enabled with the command line...

For Sympl 10.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 11.x

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

For Sympl 12.x

sudo ln -s /etc/php/8.2/mods-available/sympl-web-lockdown.ini /etc/php/8.2/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.

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 example.org (new domain) to example.com (existing domain) you would use

ln -s /srv/example.com /srv/example.org

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, example.com is the site which already exists, and example.org is the new domain.

Aliasing public/htdocs/ Only

mkdir -p /srv/example.org/public
ln -s /srv/example.com/public/htdocs /srv/example.org/public/htdocs
touch /srv/example.org/config/disable-php-security

Aliassing public/ and Subdirectories

mkdir -p /srv/example.org
ln -s /srv/example.com/public /srv/example.org/public
touch /srv/example.org/config/disable-php-security

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 the security of the sites.

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/example.com/config/ip, 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.

Hidden Files and Directories

This section refers to functionality which is only in Sympl 12, but will be back-ported to other versions.

By default, Sympl blocks any hidden files or directories (those with filenames that start with a dot, '.') from being served via the web, such as .user.ini, .htaccess, files in .git and so on.

If needed, this can be turned off by creating the file config/allow-hidden, but when doing so you should ensure access to any sensitive files are restricted by .htaccess.

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/example.com/config/ssl-only.

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/example.com/config/hsts 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 www.example.com, preventing anyone from using example.com 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.

Filesystem Permissions

By default, Sympl adjusts the permissions of files and directories in /srv/example.com/public 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/example.com/config/disable-filesystem-security.

See Filesystem Security for more information.

Logging

By default, the Apache logs are written to /srv/example.com/public/logs, 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/example.com/public/htdocs/stats, making them available at https://example.com/stats.

To trigger the generation, create a file at /srv/example.com/config/stats, 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/example.com/config/stats-htaccess 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/example.com/public/cgi-bin/ and they will then be served at http://example.com/cgi-bin/ 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/example.com/conf/apache.d/. 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 example.com

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/php	Selects the PHP version the site should be run under. Remove the file to default to the bundled version for your distribution.	More...
.../config/php-modules	A list of PHP modules/extension package names for the site which will be installed automatically.	More...
.../config/php-pool	Defines the alphanumeric name of the PHP pool for the site.	More...
.../config/php-user	The local system user to run the PHP process as.	More...
.../config/php-group	The local group to run the PHP process as.	More...
.../config/disable-php-security	Existence of this file will disable some of the PHP security functions in the automatically generated Apache configurations.	More...
/etc/sympl/php/<version>/includes.d/<pool_name>.conf	Configuration changes for a specific PHP pool should be placed here.	More...
.../config/allow-hidden	Existence of this file will allow the website to serve files which are usually hidden.	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.