Apache

We use Apache as our web server.

Configuration

The Webserver can be configured with the .htaccess file in your webroot which in most cases is sufficent. But some directives are not available in the .htaccess context and they therfore must be configured in the ~/cnf/apache.conf file which is included on vhost level. Please note that the file does not exist by default and must be created manually.

Hint

The use of .htaccess should be preferred if possible, as incorrect configurations do not result in the web server no longer being able to be started in the event of a server restart.

Hint

After changes in ~/cnf/apache.conf you need to apply the configuration with apache-apply

Examples

Warning

The code blocks mentioned here serve as an example. Please check yourself if everything works correctly, especially if you have other configurations in your .htaccess file.

Custom MIME Type

AddType text/cache-manifest .appcache

Favicon per Domain

RewriteEngine On
RewriteCond %{HTTP_HOST} ^myhost.com$
RewriteRule ^favicon\.ico$ /images/favicon-myhost.ico

Custom Maintenance Page

# you can provide a string or a filepath
ErrorDocument 404 "<H1>Page not found</H1>"
ErrorDocument 503 /503.html

IP Protection

# Block all connections
Require all denied

# Except explicitly allowed IP's
# Allow single IP
Require ip 192.168.1.12

# Allow multiple IP's
Require ip 192.168.1.12 2001:db8::12

# Allow IP Range
Require ip 192.168.1.0/24
Require ip 2001:db8::/32

Warning

When the ip protection is used in conjunction with Enable password protection (basic auth) from the cockpit, the password protection takes precedence and the ip restriction is no longer applied.

IP Protection and Basic Auth

To set up IP protection together with basic auth, you have to configure both together. First we need to create the user credentials htpasswd -c ~/cnf/user.htpasswd bob. Add the following example to your Apache configuration, and make sure you adjust the AuthUserFile path and the required IPs. When everything is set up, also make sure Enable password protection is disabled in the Cockpit for the affected website.

# Block all connections
Require all denied

# configure basic auth
AuthType Basic
AuthName "Restricted"
AuthUserFile "/home/<website_name>/cnf/user.htpasswd"

# Require a valid user and ip
<RequireAll>
  Require valid-user
  <RequireAny>
    Require ip 192.168.1.25
    Require ip 2001:DB8::12
  </RequireAny>
</RequireAll>

Custom Webroot

By default, the webroot directory is choosen according vendor recommendations, depending on the selected Type. Some deployment workflows require other locations, which you can select through the webroot option within the Custom JSON Website Level Configuration:

{
  "webroot": "deploy/current/html"
}

Warning

The directory specified here needs to be a real directory. Symlinks are not allowed. This applies only to the last directory in the path (in the example above, current can be a symlink but html cannot).

Custom Default Webroot

The “Custom Default Webroot” differs from the “Custom Webroot”. The “Custom Default Webroot” is the webroot used when a website on a server is accessed that does not exist yet, error documents and the default index file added when new websites get added.

This allows you to customize the look and feel of those system-pages e.g. to adapt it to your own corporate design.

The files provided on your Server by default can be copied from the default webroot git repository.

Best is to copy this whole repository to your own Gitlab (or Github) environment and make the needed changes to the files.

Then configure your server via “Custom JSON” on the server level to check out a specific version of your repository. Copy the snippet below and adapt it.

{
  "website::default::webroot::gitsource": "git@work.opsone.ch:open/default-webroot.git",
  "website::default::webroot::gitrevision": "d00433e671d9eec99ba8d56c3a08c4a7921c32b7",
  "website::default::webroot::gitkey": "-----BEGIN OPENSSH PRIVATE KEY-----\zAXktdjEABGAaC1AArZ5v...\n-----END OPENSSH PRIVATE KEY-----"
}

If you make changes to your files in your Git repository at a later time, just change the SHA-1 hash in that config to the one from your latest commit and let puppet roll update your server.

Warning

Make sure to change the config block above to fit to your own environment (3 things need to be changed).

Listen

By default, Apache will bind to the primary IP address of the eth0 interface and the ports 80 and 443. You can specify listen options explicitly per website, for example to use in concunction with Varnish.

The following options are available within the Custom JSON Website Level Configuration:

{
  "listen_ipv4_address": "127.0.0.1",
  "listen_ipv4_port": 8080,
  "listen_ipv6_address": "::1",
  "listen_ipv6_port": 8080
}

XSendFile

XSendFile is a feature that allows an application to hand over the download of a file to the web server by sending an X-Sendfile header. The file is then read directly from the web server and does not have to be processed by PHP. See mod_xsendfile for more information.

To enable XSendFile you need to enable the module in your .htaccess file:

# enable for all php scripts
XSendFile on

# enable only for download.php
<Files download.php>
  XSendFile on
</Files>

If you want to use a path outside webroot, you must first allow the path in the ~/cnf/apache.conf:

# allow ~/files to be served by XSendFile
XSendFilePath /home/example/files

Hint

After changes in ~/cnf/apache.conf you need to apply the configuration with apache-apply