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 directory 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

A redirection from HTTP to HTTPS is implemented by means of an .htaccess file. The file is placed in the folder where the redirection is to take place.

For example, example.org in the webroot, i.e. /home/www-data/example.org.

With the following command we create a .htaccess file in the path that we can edit immediately:

www-data@server:$ sudo nano /home/www-data/example.org/.htaccess

In the following section is the code part for the redirection, this can be copied into the .htaccess file:

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

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