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-vhosts
with 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 HTTPproxy_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