Skip to main content

Manage VirtualHosts with nine-manage-vhosts

What is a Virtual Host?​

Virtual Hosting is the simultaneous operation of multiple websites (domains) on a common host (server).

Each of these environments is called a Virtual Host and can be individually configured for hosting. Thus, multiple domains or IP addresses can be used or user-specific ports can be configured.

What is nine-manage-vhost?​

On Nine Managed (V)Servers, nine-manage-vhosts is used by default to manage websites. This makes it easier and faster to manage the Virtual Hosts. This VirtualHost configuration tells the web server where the data is located and under which address the page can be called up.

nine-manage-vhosts supports the web servers Apache2 as well as Nginx and is compatible with the FTP administration tool "FTPAdmin".

Basically, nine-manage-vhosts -h displays the help text with all options.

www-data@server:~ $ # sudo nine-manage-vhosts -h
Manage your virtual hosts, users and certificates.

Usage:
  nine-manage-vhosts user create <name> [--no-password | --ask-password | --password=<password>]
  nine-manage-vhosts user update <name> (--no-password | --ask-password | --password=<password>)
  nine-manage-vhosts user remove <name>
  nine-manage-vhosts user list [--json]
  nine-manage-vhosts webserver reload
  nine-manage-vhosts virtual-host create <domain> [--user=<user>] [--webroot=<webroot>] [--template=<template>] [--template-variable=<template-variable>]... [--no-notify-services]
  nine-manage-vhosts virtual-host update <domain> [--user=<user>] [--webroot=<webroot>] [--template=<template>] [--template-variable=<template-variable>]... [--no-notify-services]
  nine-manage-vhosts virtual-host remove <domain> [--no-notify-services]
  nine-manage-vhosts virtual-host show <domain>
  nine-manage-vhosts virtual-host list [--json]
  nine-manage-vhosts virtual-host notify-services <domain> [--force]
  nine-manage-vhosts alias create <alias_domain> --virtual-host=<domain> [--no-notify-services]
  nine-manage-vhosts alias remove <alias_domain> --virtual-host=<domain> [--no-notify-services]
  nine-manage-vhosts certificate create --virtual-host=<domain>
  nine-manage-vhosts certificate remove --virtual-host=<domain>
  nine-manage-vhosts certificate list
  nine-manage-vhosts certificate renew-expiring
  nine-manage-vhosts certificate register-client --contact-email=<contact-email>
  nine-manage-vhosts template list [--json]
  nine-manage-vhosts -h | --help
  nine-manage-vhosts -v | --version

Options:
  --user=<user>                    Specify the user whose home directory the web app is located in.
  --no-password                    Do not set a password for user.
  --ask-password                   Prompt for user password.
  --password=<password>            Specify the user's password.
  --webroot=<webroot>              Specify the absolute document path.
  --template=<template>            Specify the template of the virtual host. Defaults to configured default template.
  --virtual-host=<domain>          Specify the virtual host for which the alias should be created.
  --contact-email=<contact-email>  Specify the contact email address to use for registration.
  --json                           Print machine readable output (JSON).
  -h --help                        Show this help.
  -v --version                     Show version.

First Steps​

Connection to the Server​

By default, you will receive SSH/SFTP access for the system user "www-data" as well as a user account for the Nine Cockpit (https://cockpit.nine.ch/) when ordering a Managed (V)Server.

For more information about SSH and SFTP, see:

Via SSH you now have access to the file structure and are usually located in the folder "/home/www-data" after logging in to the server. This contains the folder "logs", in which you can view the access and error logs of the respective websites. The log files are named as follows:

If a VirtualHost is created for a user other than www-data, the logs would be located in the respective user folder according to the scheme "/home/<user>/logs/".

Manage a Virtual Host​

To publish a website, the following requirements must be met:

  • Register domain in the DNS system at https://cockpit.nine.ch/ (If you want to use the DNS servers of Nine, specify the name servers ns5.nine.ch and ns6.nine.ch with the registrar of the domain).
  • Create VirtualHost configuration on the server using nine-manage-vhosts
  • SFTP connection for uploading the website

Create a Virtual Host​

In order to publish the website, a virtual host is needed. The following example shows the command for creating a virtual host for the website (domain) examle.org.

www-data@server:~ $ sudo nine-manage-vhosts virtual-host create example.org
Virtual Host created: example.org
example.org
===========
              DOMAIN: example.org
                USER: www-data
             WEBROOT: /home/www-data/example.org
            TEMPLATE: default
  TEMPLATE VARIABLES: MODSEC
                      Off
                      PHP_VERSION
                      8.0
             ALIASES: www.example.org
                      example.org.server.nine.ch

To see the configuration, use:sudo nine-manage-vhosts virtual-host show example.org

In the example above, nine-manage-vhosts creates the configuration for http://example.org as well as http://www.example.org and the folder "/home/www-data/example.org" - if this does not already exist - into which the website can be uploaded. The often used subdomain "www". is created by default and does not have to be set up separately.

List Virtual-Hosts​

With the following command, you can list all virtual hosts and display their configurations:

www-data@server:~ $  nine-manage-vhosts virtual-host list
example.org
===========
    DOMAIN: example.org
                USER: www-data
             WEBROOT: /home/www-data/example.org/app
            TEMPLATE: default
  TEMPLATE VARIABLES: MODSEC
                      Off
                      PHP_VERSION
                      8.0
             ALIASES: www.example.org
                      example.org.server.nine.ch
                      example.net

Below you can see the definition of the individual parameters:

- DOMAIN: For virtual hosts, the domain is the name of the website, e.g. example.org.

- USER: User refers to the user who can access the virtual host.

- WEBROOT: The webroot is the folder or path where the website is stored.

- TEMPLATE: The template contains Apache configurations, such as SSL, timeout, headers etc.. It serves as a template and basic configuration.

- TEMPLATE VARIABLES: The Template Variables, on the other hand, are even more components of a template, so you can use a template for PHP etc that have been predefined by the Nine.

- ALIASES: An alias serves as a second name for your website.

Customise a Virtual Host​

To customise a Virtual Host entry, we do not use create, but update. In this example, we change the user to testuser:

www-data@server:~ $sudo nine-manage-vhosts virtual-host update example.org --user=testuser
Virtual Host created: example.org
example.org
===========
              DOMAIN: example.org
                USER: www-data
             WEBROOT: /home/www-data/example.org
            TEMPLATE: default
  TEMPLATE VARIABLES: MODSEC
                      Off
                      PHP_VERSION
                      8.0
             ALIASES: www.example.org
                      example.org.server.nine.ch

To see the configuration, use:sudo nine-manage-vhosts virtual-host show example.orgudo nine-manage-vhosts virtual-host create example.org

The following parameters can be changed with the update command:

  • USER
  • WEBROOT
  • TEMPLATE
  • TEMPLATE VARIABLES

Deployed as follows:

nine-manage-vhosts virtual-host update example.org --<parameter>=<value>

If you get the following error message, please make sure you're using the update command:

Error: Virtual Host example.org already exists

Change the used PHP version​

The template variable PHP_VERSION allows you to change the PHP version used by a Virtual Host.

The available PHP versions are dependent on the Ubuntu version of your server. We provide an overview in our article Which software versions are available on my server?.

www-data@server:~ $ sudo nine-manage-vhosts virtual-host update example.org --template-variable=PHP_VERSION=8.2
Virtual Host updated: example.org
example.org
=======
              DOMAIN: example.org
                USER: www-data
             WEBROOT: /home/www-data/example.org
            TEMPLATE: default
  TEMPLATE VARIABLES: TIMEOUT
                      300
                      MODSEC
                      Off
                      PHP_VERSION
                      8.2
             ALIASES: www.example.org
                      example.org.server.nine.ch

To see the configuration, use:sudo nine-manage-vhosts virtual-host show example.org

DocumentRoots – relative path​

By default, the web server displays the index file (index.php, index.html, ...) in the folder "/home/<user>/<domain>". However, depending on the application, a slightly modified folder structure may be necessary. For example, in such cases the content must be in the subfolder "app" or "public", depending on what the application requires.

For precisely this purpose, the option "--webroot" is useful for defining this folder. For the web application that requires the subfolder "app", the command would look like this:

www-data@server:~ $ sudo nine-manage-vhosts virtual-host create example.org --webroot=/home/www-data/example.org/app
example.org
===========
              DOMAIN: example.org
                USER: www-data
             WEBROOT: /home/www-data/example.org/app
            TEMPLATE: default
  TEMPLATE VARIABLES: MODSEC
                      Off
                      PHP_VERSION
                      8.2
             ALIASES: www.example.org
                      example.org.server.nine.ch

To see the configuration, use:sudo nine-manage-vhosts virtual-host show example.org

The following configuration of the VirtualHost just created shows in this example the use of the option "--webroot" with the subfolder "app":

www-data@server:$ sudo nine-manage-vhosts virtual-host show example.org
[...]
  ServerName example.org
  ServerAlias www.example.org
  ServerAlias example.org.server.nine.ch

  SetEnvIf Host "example.org.server.nine.ch" TEST_URL
  Header set X-Robots-Tag "noindex, nofollow" env=TEST_URL

  DocumentRoot /home/www-data/example.org/app

  ErrorLog /home/www-data/logs/example.org.error.log
[...]

Der angegebene Ordner muss im home-Ordner des Benutzers liegen.

ServerAliases – same content on multiple (sub-)domains​

In some cases, you may want to make the content of a website accessible under different domains or subdomains. To avoid having to copy and configure the website several times, a so-called "ServerAlias" can be used, which acts like a pseudonym for the website. The server displays the website with the configured addresses.

Example for creating an alias example.net to the existing website example.org:

www-data@server:~ $ sudo nine-manage-vhosts alias create example.net --virtual-host=example.org
example.org
===========
   DOMAIN: example.org
  ALIASES: www.example.org
           example.org.server.nine.ch
           example.net

SSL certificates and encryption​

Let's Encrypt​

Details on nine-manage-vhostswith Let's Encrypt can be found at nine-manage-vhosts with Let's Encrypt.

Additional certificate types​

In case Let's Encrypt certificates aren't suitable for your use case, we've compiled a comprehensive overview of additional SSL certificate products we're offering.

Snakeoil-certificate​

With nine-manage-vhosts, an SSL template for a VirtualHost is available with the template "default_snakeoil_https". The so-called "snakeoil"-certificate is used, which was automatically generated and signed by the server. This enables an encrypted connection. Please note that with the "Snakeoil"-certificate a warning message is displayed in the browser, as the certificate was not issued by an official certification authority.

To configure the website with the "Snakeoil"-SSL certificate - with the template "default_snakeoil_https" - the following command is required:

www-data@server:~ $ sudo nine-manage-vhosts virtual-host create example.org --template=default_snakeoil_https
example.org
===========
              DOMAIN: example.org
                USER: www-data
             WEBROOT: /home/www-data/example.org
            TEMPLATE: default_snakeoil_https
  TEMPLATE VARIABLES: MODSEC
                      Off
                      PHP_VERSION
                      8.2
             ALIASES: www.example.org
                      example.org.server.nine.ch

To see the configuration, use:sudo nine-manage-vhosts virtual-host show example.org

Redirections from HTTP to HTTPS​

When using Apache httpd as a Managed Service, the redirect can be configured with an .htaccess file.

The .htaccess file should be stored in the --webroot (document root) folder defined with nine-manage-vhost and contain the following directives.

RewriteEngine on
RewriteCond %{HTTPS} !on
RewriteRule .* https://%{SERVER_NAME}%{REQUEST_URI} [R=301,L,QSA]

If your .htaccess file already contains rewrite rules, you should place the above rule at the beginning.

Please note that there is no comparable alternative to .htaccess files for NGINX; in this case, redirection is only possible with a custom template.

If Apache httpd or NGINX is used as a proxy for e.g. a Node.js application, the redirection can be done with an existing template for nine-manage-vhosts.

Analyze Access Logfiles (goaccess)​

Real Time Access Logs​

You can use goaccess on the command line to real-time observe the access logs of a specific vhost:

www-data@server:$ goaccess -f /home/www-data/logs/example.org.access.log

Unless you have requested a custom log file format, choose the default

[ ] NCSA Combined Log Format

using the spacebar, then hit Enter to view the file.

Activate daily log analyzer​

Note: Starting with Ubuntu 20.04 Focal, the daily log analyzer is not available by default. If you would like to have this feature, feel free to contact us.

You can enable the daily log analyzer per vhost to produce monthly reports based on the logfiles of the vhost.

Keep in mind, that the process of generating reports out of access logfiles can be time and CPU resource intensive. So, do not activate this on all vhosts that you have on a server. It will generate a high load on the system if you have a lot vhosts with this job activated.

The cron jobs run per default in the morning, and produce the first result sets of yesterday's logfiles.

www-data@server:$ sudo nine-manage-vhosts job enable goaccess --virtual-host=example.org

The logfiles of the domain will be "parsed" in the next morning through cronjobs, and after that every morning under the WEBROOT directory of the specific vhost.

Old months (in this example July 2019) can be "regenerated" using the following commands:

www-data@server:$ nine-goaccess-parse-data -c 201907 example.org /home/www-data/example.org

To access the generated goaccess monthly reports, several users can be generated:

www-data@server:$ nine-goaccess-set-pw -a user1 /home/www-data/example.org
Enter new Password:
Adding password for user user1

  Your GoAccess Password has been successfully set in the file:

  /home/www-data/example.org/goaccess/.htpasswd

  You can now login on the Webinterface and inspect the monthly reports using the following credentials:

  GoAccess URL:  http://<yourdomain>/goaccess/
  GoAccess User: user1

INFO:
If you just activated the goaccess job, you need to wait for the next day initialization procedure when the access logs of yesterday are parsed and the first monthly report will be generated.
We add a timeout command in front of the goaccess parser of 20 minutes. That kills the jobs which are running for more than 20 minutes, to ensure that all statistics get through even if there is a massive logfile with lots of information in it to parse.

If the user1 already exists in the htpasswd file under /home/www-data/example.org/goaccess/.htpasswd, the password can be "changed" using the same command above.

The users can also be deleted:

www-data@server:$ nine-goaccess-set-pw -d user1 /home/www-data/example.org

Deactivate daily log analyzer​

If you do not want to analyze the logfiles anymore, then you can easily deactivate the analyzer job and remove the directories (in the userspace) associated with it:

www-data@server:$ sudo nine-manage-vhosts job disable goaccess --virtual-host=example.org
www-data@server:$ rm -rvf ~www-data/example.org/goaccess
www-data@server:$ rm -rvf ~www-data/example.org/.goaccess

Enhanced configuration​

Templates​

Besides the default and Let's Encrypt templates there are additional proxy templates available. These templates can be used to transform either the apache2 or nginx web server into a local reverse proxy.

  • proxy: Proxy vHost with HTTP
  • proxy_snakeoil_https: Proxy vHost with HTTPS (snakeoil certificate)
  • proxy_letsencrypt_https: Proxy vHost with HTTPS (Let's Encrypt)
  • proxy_letsencrypt_https_redirect: Proxy vHost with Redirect from HTTP to HTTPS (Let's Encrypt > only needed with apache)

With the template-variable PROXYPORT you can set a custom TCP port on localhost to which the web server will then proxy any traffic to.

All proxy templates support WebSocket connections. The same port will be used as configured for HTTP.

An example command to create a simple proxy vhost:

www-data@server:$ sudo nine-manage-vhosts virtual-host create example.org --template=proxy --template-variable PROXYPORT=8080
Virtual Host created: example.org
example.org
===========
              DOMAIN: example.org
                USER: www-data
             WEBROOT: /home/www-data/example.org
            TEMPLATE: proxy
  TEMPLATE VARIABLES: PROXYPORT
                      8080
             ALIASES: www.example.org
                      example.org.server.nine.ch

To see the configuration, use:sudo nine-manage-vhosts virtual-host show example.org

For making use of Let's Encrypt you can use the 'proxyletsencrypt' template.

Some web applications require special configuration options. For example, the Python web framework Django always needs a WSGI configuration.

If you need a custom template for you application or use case, please your request to . Creating a custom template will be charged at our hourly rate of CHF 250 .

To create a new virtual host with such a template, have a look at the following example:

www-data@server:$ sudo nine-manage-vhosts virtual-host create example.org --template=django
Virtual Host created: example.org
example.org
===========
              DOMAIN: example.org
                USER: www-data
             WEBROOT: /home/www-data/example.org
            TEMPLATE: django
  TEMPLATE VARIABLES: TIMEOUT
                      300
                      MODSEC
                      Off
                      PHP_VERSION
                      8.2
             ALIASES: www.example.org
                      example.org.server.nine.ch

To see the configuration, use:sudo nine-manage-vhosts virtual-host show example.org

If you want to use pre-defined settings on an existing virtual host, you can apply a template to that virtual host:

www-data@server:$ sudo nine-manage-vhosts virtual-host update example.org --template=default_example

With the following command you can get a list of all available templates:

www-data@server:$ sudo nine-manage-vhosts template list

Timeout​

You can change the template variable TIMEOUT (seconds), to set the PHP-FPM ProxyTimeout in the default templates or the ProxyTimeout of the proxy templates.

www-data@server:$ sudo nine-manage-vhosts virtual-host update example.org --template-variable=TIMEOUT=1200

This example above ensures, that long-running php-fpm processes (or proxied requests), can run longer than the default of 300 seconds (1200 seconds).

Customize PHP CLI version​

The available PHP CLI versions can be displayed with the following command:

www-data@nine01:~ $ sudo nine-manage-vhosts php-cli list
php8.0
php8.1
php8.2
php8.3

The available PHP versions can be run directly.

www-data@nine01:~ $ php8.0 --version

The currently active version can be displayed as follows:

www-data@nine01:~ $ sudo nine-manage-vhosts php-cli show
php8.0

The default version can be customized as follows:

www-data@nine01:~ $ sudo nine-manage-vhosts php-cli update php8.2
PHP version successfully updated to php8.2