Ease Apache 2 server administration with a2tools

a2tools is a command-line tool easing and automating the daily administration of a Apache 2 server on Debian. This howto describe its installation and usage.

This howto is tested on :

• Debian 10.0 Buster

Requirements

This howto requires :

• a Apache 2 HTTP server, as described by Install Apache 2 on Debian.

This howto recommends :

• biapy-updater, for automatic software updates.
• the installation of Let’s Encrypt client acme.sh, as described by Install (Let’s Encrypt) certbot client acme.sh on Debian.

Installation

Detect if sudo is available (“command” is used if not):

cmdProxy='command'
command type -f 'sudo' &>'/dev/null' && cmdProxy='sudo'

Install the tool :

${cmdProxy} wget "https://raw.github.com/biapy/howto.biapy.com/master/apache2/a2tools" \
    --quiet --no-check-certificate --output-document="/usr/local/bin/a2tools"

Declare the downloaded file as executable:

${cmdProxy} chmod +x "/usr/local/bin/a2tools"

Automatic updates

Configure biapy-updater automatic updates to check for new versions of the software:

command grep --quiet 'a2tools' '/etc/biapy-updater.conf' \
    || ${cmdProxy} tee -a '/etc/biapy-updater.conf' <<< 'a2tools'

Usage examples

The details of the tool usage is given by :

sudo a2tools --help

Simple Virtual Host

Create a virtual host serving a folder :

sudo a2tools "www.domain.com" "/opt/www.domain.com"

Redirection

Create a virtual host redirecting a domain and all of its sub-domains to another web site:

sudo a2tools --template='redirect' \
        --alias="*.domain.com" \
        "domain.com" "http://www.domain.com/"

Reverse proxy

Create a virtual host serving a web site hosted on another server (by reverse proxy) :

sudo a2tools --template='reverse-proxy' \
        "www.domain.com" "http://domain.server.lan/"

For the reverse proxy to work, a VirtualHost named “www.domain.com” must be configured on the remote host (a.k.a. “domain.server.lan”).

If the remote host use Apache 2, it is recommended to apply the settings described by Get the real IP address of a visitor accessing to a Apache 2 server behind a reverse proxy.

Removal of a domain

Delete all virtual host for a domain:

sudo a2tools --remove "www.domain.com"

Secure host (HTTPS)

Any HTTPS host needs the creation of a valid SSL certificate for its domain name, as described by Create a SSL / TLS certificate on Debian or the use of acme.sh certbot (Let’s Encrypt) client.

Create a HTTPS virtual host with the –ssl=’auto’ option to automatically create a Let’s Encrypt certificate:

sudo a2tools --ssl='auto' 'www.domain.com' '/opt/www.domain.com'

Create a HTTPS virtual host with the –ssl option having for argument the name of the chosen SSL certificate (generally, the domain name of the web site), if you have an existing certificate :

sudo a2tools --ssl='www.domain.com' 'www.domain.com' '/opt/www.domain.com'

If the chosen certificate is a wildcard valid for all sub-domains, use:

sudo a2tools --ssl='*.domain.com' 'www.domain.com" '/opt/www.domain.com'

Note: Adding an argument to the –ssl option is equivalent to use these options:

sudo a2tools --ssl \
        --private-key="/etc/ssl/private/www.domain.com.key" \
        --public-key="/etc/ssl/certificates/www.domain.com.crt" \
        --root-ca="/etc/ssl/roots/www.domain.com-root.ca" \
        --chain-ca="/etc/ssl/chains/www.domain.com.ca" \
       'www.domain.com' '/opt/www.domain.com'

Limitations of SSL with Internet Explorer version 8 and bellow

Internet Explorer 6 to 8 on Windows XP miss a functionality that allow to have more than one SSL certificate by IP address. To host many sub-domains on a same server, the use of wildcard certificates (ie. “*.domain.com”) is recommended.

To host several domains on one server without errors with Internet Explorer, use the “–bind-ip” option to specify the IP address linked to the chosen SSL certificate. If you own a OVH server, assign a failover IP to the server.