No. All typical day-to-day jobs, such as adding new web sites, or email addresses, or uploading content, can be done using SFTP, i.e. FTP over SSH, by creating files and directories. FileZilla is the recommended program for this.

This should not be viewed as a disadvantage; any confident computer user should be able to manage a Symbiosis system with the help of this documentation and the cost and security concerns of panel based systems are avoided altogether.

Unlike other control-panel systems, one of the aims of the Symbiosis system is to keep configurations for the various services as close to the Debian default as possible. This allows users to tailor these configurations as they need.

Although it is possible to access a Symbiosis system comand line as root (the equivalent of administrator on a Windows system), that is not recommended. Where it is necessary to run commands with root privileges, that should be done by prefacing them with sudo and supplying the admin password when prompted to do so. Most operations on a Symbiosis system must in any case be done by admin (or another limited user), not by root.

Yes! Symbiosis is released under the GNU General Public Licence, version 2 or later. All the source code is available for scrutiny on the Symbiosis project site. There is also a issue tracker to report any problems encountered, or to request improvements.

This documentation is released under the GNU Free Documentation Licence or later. It also has a project site, and issue tracker.

Symbiosis uses the following software, all of which is open-source:

What follows is step by step instructions to get up and running with controlling your server and setting up core services. The screen shots are taken from a Windows system, but all the programs used are also available for Mac OS X and GNU/Linux desktop systems.

Throughout the documentation, the example server used is example.vm.bytemark.co.uk. The example domain used is my-brilliant-site.com. These should be substituted as appropriate.

A server installed with Symbiosis will be running SSH, and will have had the admin user account created. This allows you to connect via SFTP to administer the machine.

The admin account should be used when administering a Symbiosis system to ensure that files and directories have the correctcode-sign.co.uk permissions.

Usage of SFTP is mandated for administrating the machine, as all data are passed over the network encrypted.

Throughout the documentation the example server name example.vm.bytemark.co.uk should be substituted for your own server name.

The following figure shows FileZilla’s layout after successfully logging in. The display is divided into four main sections, the top left pane shows a directory tree, with the directories on your local computer, labelled a. Beneath that is a listing showing the contents of the currently selected local directory, labelled b. Then the top right pane shows the directory tree of the remote machine. When logging in as admin this will show /srv (c). Finally beneath that is the contents of that directory. Initially this will only contain one directory named after the machine. In this case example.vm.bytemark.co.uk/ is shown (d).

Once you’ve been able to successfully connect to your server, via FileZilla, you may proceed to configure email, or setup your website.

This section demonstrates how to carry out some common tasks with the FileZilla client:

The previous section dealt with setting up a web page using the default domain associated with the machine. A Symbiosis system can host many domains without any extra configuration. This section deals with configuring a second domain.

It has been assumed that both your server is hosted at Bytemark, and that this second domain is using the Bytemark name servers. If this is not the case, then Section 15.1, “Default DNS records” sets out the DNS records needed for the following procedure to work.

For the purposes of this tutorial, the domain my-brilliant-site.com is being hosted on the machine example.vm.bytemark.co.uk.

Within a hour, the DNS records for my-brilliant-site.com will be generated and uploaded to the Bytemark domain name servers. Navigating to that site will then show our new index page.

At this point, the site will also be visible at both http://my-brilliant-site.com and http://www.my-brilliant-site.com. This is part of the Symbiosis setup; if different pages were required at www.my-brilliant-site.com, a separate directory tree should be created for www.my-brilliant-site.com, with a different content as needed.

As we’ve previously noted if there is a directory present upon your machine with the name /srv/my-brilliant-site.com/public/htdocs the contents of that directory will be served for both:

This works because although the prefix, "www.", is missing the actual domain is still found on your machine beneath the /srv prefix.

In the general case you can also direct your users to:

In short - the sub-domain used as a prefix is silently removed if the appropriate directory cannot be found upon your machine. The only additional step you’ll need to perform is to create the appropriate DNS entry, which is discussed in Section 15.2, “Adding a wild-card hostname record”.

It is possible to test the content associated with a new domain before it has been registered or had any DNS configuration done. This is done using the testing prefix.

If your machine is not hosted at Bytemark, or your machine name does not end in bytemark.co.uk then a wild-card DNS record is needed for this to work. This is discussed in Section 15.2, “Adding a wild-card hostname record”.

For example, to view the site my-brilliant-site.com which is hosted on the machine example.vm.bytemark.co.uk, simply head to http://my-brilliant-site.com.testing.example.vm.bytemark.co.uk/.

This testing URL is immediately available following the upload of the index.html or index.php files.

Note that there is no www at the start of the testing URL.

It has been assumed that the first few steps in Section 3.1, “Hosting a web page using your own domain” have been followed, i.e. that a directory has been created under /srv/ for the domain my-brilliant-site.com.

That is all that is needed to set up a new mailbox. To test we can immediately use the webmail application, SquirrelMail, supplied with Symbiosis.

We’ve seen in the previous section the basic steps required to configure a new email account upon a domain. For most users this is all the configuration that is required, however an advanced user might wish to take advantage of some more optional configuration.

Although most users will prefer to receive and write their emails using a dedicated client (such as ThunderBird, or Microsoft Outlook) the Symbiosis system includes a mail client you can access with nothing more than a web-browser.

This section briefly documents using the Squirrelmail webmail system.

The following details might be needed when setting up a mail client to use an email account. The user of bob@my-brilliant-site.com on the machine example.vm.bytemark.co.uk has been chosen for these worked examples.

It is recommended that all communication with the mail server is conducted over encrypted connections, either using SSL, or TLS.

Incoming email can be collected using either the IMAP or POP3 protocols. IMAP is generally recommended over POP3 as it can handle folders, push notification, can selectively download message parts, and the email remains on the server enabling back-ups to be made.

Outgoing email is sent using SMTP. It is good practice to send any outgoing email via the Symbiosis server, rather than any relay service provided by your ISP.

For both sending and receiving email, the following login information would be used.

The default ports are used for all protocols. For further details see Section 13.1, “Port Configuration”.

It is common for Internet service providers to block the standard outgoing email port, i.e. port 25. If your email client complains that it cannot connect to your server on this port, then port 587 is provided as an alternative.

The file is a list of jobs, one per line. Each line specifies first the times and days at which a job should run, followed by the command to run.

The first five fields, which are separated by spaces, specify the time and date at which the job should run. The rest of the line is interpreted as the command.

In addition an asterisk can be used to indicate for every allowed value. For example, to execute the command echo Hello Dave. at 18:40 every day, the crontab line would read as follows.

40 18 * * * echo Hello Dave.

Three-letter names can also be specified for use in instead of numbers for days of the week and months.

Any output generated by a command will be sent to the root account, unless specified otherwise. If no output is generated, no email will be sent.

The fields can be specified in the following ways:

Ranges can also be specified across "boundaries". For example 22-2 in the hour field will be interpreted as 22, 23, 0, 1, 2; Nov-Feb in the month field will mean 11, 12, 1, 2.

There is also a selection of shortcuts available:

The full crontab format is explained in more detail in the crontab (5) manual page.

The output can be emailed to any recipient by specifying the MAILTO parameter at the top of the file.

For example, we would like to mail any output from our commands to bob@my-brilliant-site.com.

#
# send any output to Bob
#
MAILTO=bob@my-brilliant-site.com
#
# run at 9am every Monday - Friday
#
0 9 * * 1-5 wget http://www.my-brilliant-site.com/cron.php

As mentioned above, the backup script will attempt to ensure that your local backups are uploaded to a remote server, to protect against data loss if your system fails catastrophically.

For Bytemark customers this location should be determined automatically.

If this process fails, or you are not a Bytemark customer, you can specify the correct location in /etc/symbiosis/dns.d/backup.name. This should be a fully-specified rsync path.

Every day, when runs it generates output saying what has been backed up, and if there were any errors during the backup process. This email will get sent to the root account of the local hostname.

The Symbiosis system is comprised of many components, each working together to deliver a complete solution to your hosting needs. Different systems and components of your server will generate email notifications to alert you of important events and warnings. It is important that such emails are read.

By default all system-generated emails will be delivered to the root user of your primary domain. (This is the first domain which is configured when your machine is setup, and will probably be a name such as example.vm.bytemark.co.uk.)

Rather than make it mandatory that you read the root mailbox it is suggested that you configure email forwarding such that mail sent to root@example.vm.bytemark.co.uk is delivered to your personal email address.

A common means of compromising machines is known as a "dictionary attack", this involves a remote user (or computer) trying to connect to a server with a collection of thousands of usernames and passwords.

This dictionary of usernames and passwords will include common choices such as a username of "test" and a password of "test", along with many other less-likely looking candidates. Detecting these attempts is very straightforward, and is something that our system manages as documented in Section 14.2, “Blocking abusive remote hosts”.

The best defense is to ensure that when you add users, or change system passwords, that you never ever choose simple passwords which might be liable to be guessed, or included in an attackers' dictionary.

There is a regular test on all the passwords used to access email and FTP under Symbiosis, the output of which will get sent to the root email account, please see the note in earlier in this chapter regarding email notifications.

Over time security bugs can be found in software packages, and if such a problem is discovered in a package you’re using then your machine is at risk until it has been updated.

The Symbiosis system is configured to automatically download and install appropriate security updates to the packages in the base operating system and from the Symbiosis repository itself.

However if you’ve chosen to install additional, external, applications such as Wordpress you must ensure that you look for updates regularly. Often this can be done by subscribing to the application’s announcements mailing list.

So far connecting using SFTP has been documented. This is used to manage files on the machine. From time to time it can be necessary to have to run commands on the machine itself. This is where SSH comes in.

SSH allows shell access to a machine, which provides the ability to run commands directly on that machine. Shell access is the equivalent of the MS-DOS or cmd prompt on Windows PCs, or the terminal on machines running Mac OS X or Linux. SSH is an encrypted protocol, like SFTP, ensuring that all commands and passwords pass between your computer and the server are protected against eavesdroppers.

For Bytemark customers, SSH is also used to access the Console Shell of the machine.

PuTTY is a free and open-source SSH application, and available for download from its homepage. It is available for both Windows and Linux desktop machines.

Both Linux and Mac OS X desktop machines tend to come with the ssh command available.

First you must have an additional IP address routed to your machine. Your ISP should be able to do this.

Once your machine has been allocated an additional IP Address, you must tell your machine to accept traffic addressed to both your original and new IP addresses

This is a standard Debian procedure rather than something specific to Symbiosis, but for convenience it’s described here.

It has been assumed that the site requiring the new IP address is already configured as described in Section 3.1, “Hosting a web page using your own domain”.

Within an hour Symbiosis will include this change in your DNS data and upload the new data to the name servers. This will ensure that the system knows that your machine should listen upon an additional IP address, and it will also ensure that the DNS entries for the domain are updated to point to the dedicated IP address, and not the default IP of your machine.

In order to purchase an SSL certificate, you need to generate an SSL key and a certificate request on the Symbiosis machine.

With that request, you can buy a new certificate. To view the request, run cat ssl.csr. It will look like

-----BEGIN CERTIFICATE REQUEST-----
AIIB4zCCAUwCAQAwgaIxCzAJBgNVBAYTAkdCMRMwEQYDVQQIEwpNYW5jaGVzdGVy
MRMwEQYDVQQHEwpNYW5jaGVzdGVyMQ0wCwYDVQQKEwRCbGFoMQ8wDQYDVQQLEwZU
aGluZ3kxHjAcBgNVBAMTFW15LWJyaWxsaWFudC1zaXRlLmNvbTEpMCcGCSqGSIb3
DQEJARYacm9vdEBteS1icmlsbGlhbnQtc2l0ZS5jb20wgZ8wDQYJKoZIhvcNAQEB
BQADgY0AMIGJAoGBAMrTIaLKyvsxDz9WHhY5xJvHVKD+dmAuzpv2HichYejJQTTl
gXdfrrZjVWm45ZJy9TEcB5DM0qsQBSqseMner7YvAJJ3PlTd7o3Rkjztt1orP1e7
hAkpKLW2dQAvnr3RtK2w8mK+OdJYPSJfzoChCKlG64Un2VmgDfAiNMS4GCi1AgMB
AAGgADANBgkqhkiG9w0BAQUFAAOBgQBx1I52EXnKRL1YfPYIA8CXUeFRZzDbuVKQ
+fwP5Ig5BANBldMnRePY29RH7yJ2YRXTWHfo6erWT4DZVkJhLpWwBTqB/kGcjEjv
zN7D78VSSQzEb2fOcRcxd9fWmiIcIWINisjBv9gBbGH7L3UosOtdzEWyzpEjb+Or
nL4UrZV3JA==
-----END CERTIFICATE REQUEST-----

The entire output (including the BEGIN and END lines) should be copied and pasted into the appropriate part of the form when purchasing.

There are generally two types of SSL certificate: those that are self-signed, and those that are signed by a third-party. Self-signed certificates are free, but cause warnings to be produced in people’s browsers. Third-party certificates are purchased, and hopefully generate no warnings.

For an example of what a warning might look like in your browser, go to https://example.vm.bytemark.co.uk.

Purchasing a certificate is straightforward. The first part is the hardest: picking a supplier. There are many available, for example RapidSSL, Verisign, or Comodo.

During the purchase process, you will be asked for the certificate request. Instructions on how to do this are shown in Section 11.3, “Generating an SSL certificate key and request”.

Once purchased, you should end up with a new certificate, and possibly a "bundle". These should be downloaded onto your local computer. Installation of these is described in Section 11.5, “Uploading your new certificate, and optional bundle”.

Now we have our certificate, we need to upload it on to our machine. If you’ve generated the certificate on the machine, you can safely skip this procedure.

Once this procedure has been completed we can move on to the next section.

The final step is to combine our certificate and key, such that Apache can used them.

This file ssl.combined will now contain something like this.

-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQDK0yGiysr7MQ8/Vh4WOcSbx1Sg/nZgLs6b9h4nIWHoyUE05YF3
X662Y1VpuOWScvUxHAeQzNKrEAUqrHjJ3q+2LwCSdz5U3e6N0ZI87bdaKz9Xu4QJ
KSi1tnUAL5690bStsPJivjnSWD0iX86AoQipRuuFJ9lZoA3wIjTEuBgotQIDAQAB
AoGAF7jD2VdgkCp3vw+iazUMcq/IjR/V1oAC+Ci79BWqbuCC+N3S25RcScaqabgP
hQesn6hnQZ8MZl7b4Lv1585mjwmf+Sw7PAa09EiArpy3cg2Em6LpBBekPZs+aPIU
StLQnEZ1pCb1E1TVeWECQQCrM4BrdC4FymXSuANe5YXYhNPksNcWeujdLKVdgGjs
uXdLGWRgiAGqJo4teB1HjvbEWxYadZ6Zspvvc5qd4d6s
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIICvTCCAiYCCQDKfqq7e9IUIzANBgkqhkiG9w0BAQUFADCBojELMAkGA1UEBhMC
R0IxEzARBgNVBAgTCk1hbmNoZXN0ZXIxEzARBgNVBAcTCk1hbmNoZXN0ZXIxDTAL
BgNVBAoTBEJsYWgxDzANBgNVBAsTBlRoaW5neTEeMBwGA1UEAxMVbXktYnJpbGxp
MQ8/Vh4WOcSbx1Sg/nZgLs6b9h4nIWHoyUE05YF3X662Y1VpuOWScvUxHAeQzNKr
EAUqrHjJ3q+2LwCSdz5U3e6N0ZI87bdaKz9Xu4QJKSi1tnUAL5690bStsPJivjnS
WD0iX86AoQipRuuFJ9lZoA3wIjTEuBgotQIDAQABMA0GCSqGSIb3DQEBBQUAA4GB
ABWXBGPKldcqJsVzB6KYIEv8jLa7iYIsB5rdhP5zviC1d4rT6U0jsCsCt/H/UQtf
6Y2Jl6nRKNBkvROVT28TfZjEe3AiBoB5MTt9P0hfxYzKoxUwaBLzClLUfaeWY/qT
GAt5kCtYlBgNxMIXkNPj2weODunfpELBJ7ARKAa3+uIu
-----END CERTIFICATE-----

Once you’ve configured the SSL certificate, as described in the previous sections, you’ll find that your site is accessible to users over HTTP and HTTPS.

If you prefer to ensure that each visitor to your website uses the SSL-protected site you can make it mandatory by creating a .htaccess file inside your web directory root.

Continuing our example you might create the file /srv/my-brilliant-site.com/public/htdocs/.htaccess with the following contents:

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

These contents use Apache’s .htaccess file in combination with mod_rewrite to ensure that all visitors will be redirected to the secure version of your site.

This is covered in more detail in Chapter 3, Website setup.

All the files required for a website for the domain my-brilliant-site.com are kept in /srv/my-brilliant-site.com/public/htdocs.

If you wish to use CGI scripts for your domain, then simply copy them to a directory named cgi-bin/ beneath the public/ directory. They must all be marked as executable. This means setting the permissions to 755. In FileZilla, right click the file and select File Permissions… from the menu. The file should have Execute set for the owner, group, and public permissions.

For example, for my-brilliant-site.com the scripts would live in /srv/my-brilliant-site.com/public/cgi-bin.

Any executable files in that directory will now be treated as CGI scripts for your domain. For example if you created the file /srv/my-brilliant-site.com/public/cgi-bin/test.cgi This would be referred to as: http://my-brilliant-site.com/cgi-bin/test.cgi

Each hosted website will have visitor statistics automatically generated and accessible at http://my-brilliant-site.com/stats/. These statistics will be updated once per day, and the raw access logs will be made available as /srv/my-brilliant-site.com/public/logs/.

These daily statistics can be disabled by creating the file config/no-stats.

For example, for my-brilliant-site.com, creating the file /srv/my-brilliant-site.com/config/no-stats will ensure that statistics are no longer generated for that domain. If you wish to remove any existing statistics, remove the directory /srv/my-brilliant-site.com/public/htdocs/stats/.

It is also possible to customise the statistics generated by editing the file public/htdocs/stats/webalizer.conf. This file is documented at the Webalizer project website.

You can view new websites before any DNS changes are made.

For example, if the virtual machine example.vm.bytemark.co.uk is hosting www.my-brilliant-site.com, i.e. the directory /srv/my-brilliant-site.com/public/htdocs has been created, then the website can immediately be viewed at http://my-brilliant-site.com.testing.example.vm.bytemark.co.uk.

There are some important things to note though: - There is no www part added to the domain name — it is just the directory name prepeneded to .testing.example.vm.bytemark.co.uk. - This testing alias isn’t guaranteed to work in all cases, for complex site setups it might not work entirely as expected. - The testing alias only allows the testing of websites. Therefore FTP logins, email delivery, or checking is explicitly unsupported.

In this scenario, you have registered two domains for example my-domain.com and my-domain.co.uk, but you want the same content to be served at both addresses. There is no need to create two separate directory structures, you can just set up one directory structure and then create a soft link (aka symbolic link or symlink) to the second.

Browsing to my-domain.co.uk will show the same content that appears at my-domain.com.

Here is an example configuration layout for the domain my-brilliant-site.com.

Secure Sockets Layer is a technique used to encrypt communication between two machines on a network. It uses a system of public and private keys to encrypt and decrypt the connection — the public key is used by the sender to encrypt, and the private key is used by the receiver to decrypt. This protocol is used not only for transactions involving a web server and browser, but also by the email servers and their clients.

In addition to the public key encryption, there is a system of trust that validates that the certificate presented actually belongs to the server that is presenting it. This system involved having the certificate signed by a trusted authority. Web browsers and email clients tend to come with a selection of certificates from trusted authorities pre-installed, which allows them to verify a previously unseen certificate as valid.

Having a certificate signed by a trusted authority involves having varying degrees of identity checks made, and paying a fee. Vendors that are able to sell you a certificate include Rapid SSL and Comodo.

As standard, a Symbiosis machine will come with an SSL certificate installed. However it will be a “self-signed” certificate, i.e. one that has not been signed by a trusted authority. This means that whenever a program connects to your machine using SSL a warning will be shown saying something along the lines of unable to verify certificate because the issuer is unknown. This does not affect the security of the connection,

Verifying a self-signed certificate as trusted can be done using the certificate’s fingerprint, on the machine using openssl. The default certificate on a Symbiosis machine is kept in /etc/ssl/ssl.combined. First, the fingerprint of the certificate needs to be determined. To do this run the following, as root:

openssl x509 -noout -in /etc/ssl/ssl.combined -fingerprint

That should output something similar to

SHA1 Fingerprint=B8:C7:1B:3F:EC:94:F2:9F:77:BC:09:60:CD:E3:EF:E0:04:F4:23:6A

Now that we have the fingerprint, we can compare it against that presented in a browser or email client. The fingerprint of a certificate should be shown in the application’s certificate viewer, allowing a comparison to be made between the fingerprint on the machine, and the one being presented in the application.

The nature of SSL is such that only one certificate can be used per service per IP address. This typically means that a new IP address is needed for a website that needs a new SSL certificate.

The mail servers have been set up with standard port assignments as follows. These are all the standard ports for the protocols.

In order for a domain to be configured to accept email, one of two things must be present. Either the domain must have a mailboxes/ directory present, or one of the files config/default_forward or config/aliases must be present.

For example, if the domain my-brilliant-site.com would like to host mail normally, i.e. one mailbox per user hosted on the same machine, then the directory /srv/my-brilliant-site.com/mailboxes should be created. Then in there, one directory per user should be created. If bob@my-brilliant-site.com would like to receive mail, then /srv/my-brilliant-site.com/mailboxes/bob/ should be created.

Assuming that this is the only directory inside /srv/my-brilliant-site.com/mailboxes then only mail addressed to bob@my-brilliant-site.com will be accepted. Any other mail addressed to my-brilliant-site.com will be rejected.

If you would like to accept all mail for my-brilliant-site.com, regardless of who it is addressed to, then create the file /srv/my-brilliant-site.com/config/default_forward. The contents of this file should be a single email address, or a comma-separated list of email addresses. For example, to forward all mail to bob@my-brilliant-site.com, regardless of who it is addressed to, then /srv/my-brilliant-site.com/config/default_forward should contain bob@my-brilliant-site.com.

If you would like the domain nomail.my-brilliant-site.com not to receive any mail at all, then remove the directory /srv/nomail.my-brilliant-site.com/mailboxes and ensure that the file /srv/nomail.my-brilliant-site.com/config/default_forward does not exist.

The password for a mailbox should be set by the contents of a file named password inside a user’s mailbox directory. The contents of this file may be in plain text, or encrypted.

To encrypt a password on the command line, you can run the following command, substituting "my password" for your password. This encrypts the password using the SHA-512 algorithm.

echo -n "my password" | perl -e 'print crypt(<STDIN>,
                        "\$6\$".join("", (".", "/", 0..9, "A".."Z", "a".."z")
                        [rand 64, rand 64]));' > password

This just uses the standard crypt function available under most Linux platforms, as well as perl and PHP.

All email addresses can be used with a suffix. This allows people to filter their email by the To: address. The separator between the local part and suffix is the + sign.

For example, Bob signs up to a shopping site at http://example.com. He might use bob+example@my-brilliant-site.com his email address when signing up, such that he can filter all email from that shop.

There are two methods of forwarding email. The first is a per-mailbox forwarding service, and the second is a per-domain service. For the per-user service, a file named forward should be put in a user’s mailbox directory. The per-domain service uses the same file format as the per-user service, but the file should be uploaded to config/default_forward instead.

For example, bob@my-brilliant-site.com would set up a file called /srv/my-brilliant-site.com/mailboxes/bob/forward.

If all the mail for my-brilliant-site.com needed to be forwarded elsewhere, then the file would be called /srv/my-brilliant-site.com/config/default_forward.

Both of these files can be interpreted in two ways. Firstly they can be a comma separated list of email addresses. For example, if Bob wanted to forward his email onto Charlie and Dave, his forward file might read

charlie@example.com, dave@example.com

The second way these files are interpreted is as an Exim filter file. The full specification is documented at the Exim project site.

Here are some examples of what is possible.

To forward mail on, but keep a copy

# Exim filter
unseen deliver charlie@example.org, dave@example.com

To rewrite all mail for a domain to example.com. This is probably best used in config/default_forward.

# Exim filter
deliver $local_part@example.com

The Exim documentation has further examples of what is possible.

It is possible to set a vacation message for a user by putting a message in file called vacation in the user’s mailbox directory.

For example, for bob@my-brilliant-site.com, the message would go in /srv/my-brilliant-site.com/mailboxes/bob/vacation. On Bob’s return, the people who received vacation messages are logged to /srv/my-brilliant-site.com/mailboxes/bob/vacation.log. Once he’s read it, that file, along with /srv/my-brilliant-site.com/mailboxes/bob/vacation and /srv/my-brilliant-site.com/mailboxes/bob/vacation.db should all be removed.

Each domain can have a list of aliases. This is just a file that contains a list of local parts, and a list of places they should be sent on to. This file should be in the config directory and is named aliases.

For example, my-brilliant-site.com has a list of dummy addresses that should be sent on to Bob. So the aliases file would be kept at /srv/my-brilliant-site.com/config/aliases and contains the following.

webmaster   bob@my-brilliant-site.com
chairman    charlie@example.com
staff       bob@my-brilliant-site.com, charlie@example.com, dave@example.com

This ensures that webmaster@my-brilliant-site.com is sent to bob@my-brilliant-site.com; chairman@my-brilliant-site.com is sent to charlie@example.com; staff@my-brilliant-site.com is sent to bob@my-brilliant-site.com, charlie@example.com, and dave@example.com.

Here is an example configuration layout for the domain my-brilliant-site.com. All the following files are kept in /srv/my-brilliant-site.com/.

The configuration for SpamAssassin for the admin user is kept in /srv/.spamassassin/user_prefs. Here you can adjust what score is needed to reject spam, and which tests are used during scanning. This file will only appear after a mail has been received with spam detection turned on, but one can be created and configured before this occurs.

The file contains comments and instructions, and further tips can be found on the SpamAssassin wiki.

In brief, to cause more mail to be rejected, you need to reduce the threshold score. Therefore change the line reading # required_score 5 should be changed to required_score 4. Notice that the # has been removed at the start of the line to un-comment it.

Similarly if mail is being rejected, you can increase the score.

Further instructions can be found on the SpamAssassin wiki.

There is no facility to train the SpamAssassin Bayesian learner yet.

Headers are added to messages when spam or virus scanning is enabled. These can be used by email clients to filter email, for example in to spam or quarantine folders.

With spam scanning enabled, any email that is accepted has the following headers added

The score is determined by SpamAssassin, and is the basis for acceptance or rejection. The higher the score, the more certain SpamAssassin is that the message is unwanted. The default threshold for rejection is 5.

The bar is a length of pluses or minuses that provide an easy-to-parse representation of the score. A positive score is given pluses, a negative score minuses. For example a score of 5.6 would be represented as ++++++; a score of -2.2 would be represented as --.

The status is always either innocent or spam, depending on the score.

When virus scanning is enabled, the header X-Anti-Virus is added to messages that have been scanned. This is set to either infected or clean.

There are three lists from Spamhaus that can be used to reject email based on the sender’s IP address, namely

These lists are combined to form the Zen list.

The following instructions will enable use of these lists on our example domain my-brilliant-site.com.

That is all that is needed to start using the Spamhaus Zen blacklist. If you’d rather use a combination of lists create one or more of the following files:

All configuration of the firewall is conducted via the presence or absence of files in a number of directories beneath the prefix of /etc/symbiosis/firewall.

In short to allow an incoming connection to arrive at your machine, and be accepted, on port 22, you would create the file /etc/symbiosis/firewall/incoming.d/10-ssh. In this example there are two things that we’ve done:

There are two ways the files in the incoming.d and outgoing.d directories are used:

If you were wishing to ensure that your host would only accept incoming SSH requests from your office you might run something like this:

echo "office.my-brilliant-site.com" > /etc/symbiosis/firewall/incoming.d/10-ssh

This would ensure that when the firewall was generated incoming connections on the SSH port would be accepted from the host office.my-brilliant-site.com but not from anywhere else.

The firewall-blacklist tool runs once per hour, and is designed to scan your server’s logfiles for abusive behaviour from malicious remote hosts. Malicious activity which is detected will result in the remote host being denied further access to your server.

Currently we regard malicious activity as:

Disabling the firewall completely will disable the blacklisting behaviour, but you might also wish to disable that seperately.

To do so run the following two commands:

touch /etc/symbiosis/firewall/disabled.blacklist
firewall

TODO Refer to the FileZilla touching recipe instead.

(The first will ensure the blacklisting is disabled, and the second will ensure that this setting is honoured immediately.)

The firewall-whitelist tool runs once per hour, and is designed to perform the opposite task to the firewall-blacklist script - in short it is designed to ensure that any remote host which has successfully connected to your server in the past isn’t (accidentally) blacklisted in the future.

Every hour the script will examine the successful logins which have been observed within the past month. Each IP address which has successfully been the source of a login attempt will be permitted access to the system on a global basis, and will thus not be locked out.

By default outgoing connections by the web server have been disabled. This prevents many ways of infecting a machine with malicious software following a compromise in a web application.

However there are legitimate cases when a web application might need to make such a connection.

By default the firewall contains the rule:

/etc/symbiosis/firewall/outgoing.d/50-www-data

This rule is designed to prevent your webserver from making outgoing HTTP connections - if you have a PHP application which needs to make outgoing HTTP connections you will need to remove this file:

rm /etc/symbiosis/firewall/outgoing.d/50-www-data

Then rerun the firewall to make the changed configuration live:

firewall

The Symbiosis firewall package should allow you to carry out the most common tasks, simply by creating files named after the services you wish to permit or deny.

However there are times when you might wish to make your own custom additions, and for this purpose the firewall package allows you to run an unlimited number of custom scripts/programs once it has loaded the rules - these scripts may perform arbitrary actions, but will be most typically used to update the firewall rules, via the iptables command.

If you wish you may disable the firewall completely, allowing remote users to connect to any service you have running upon your machine.

We’d not recommend that you disable the firewall, because it does provide a increase in system security, but if you wish it is possible by executing the following two commands:

touch /etc/symbiosis/firewall/disabled
firewall

The default records generated are listed in /etc/symbiosis/dns.d/template in format used by TinyDNS. In the template given below, $domain should be substituted for domain, and $ip for an IP address. A brief explanation of each line is given.

If your domain is hosted elsewhere it would be prudent to create the records explained in notes 2, 3, and 4 in the listing below in order for everything to work as advertised.

DNS records template. 

#
#  Nameserver records. 
#
.$domain::a.ns.bytemark.co.uk:300
.$domain::b.ns.bytemark.co.uk:300
.$domain::c.ns.bytemark.co.uk:300

#
#  The domain name itself 
#
=$domain:$ip:300

#
#  Useful aliases. 
#
+ftp.$domain:$ip:300
+www.$domain:$ip:300

#
#  MX record 
#
@$domain:$ip:mx.$domain:15:300

If you would rather have a different template to be created for your domains, feel free to edit /etc/symbiosis/dns.d/template. Ensure that the pattern of $domain and $ip is followed for the generation to work.

In addition to these records for each domain, a wild-card A record is needed for the hostname such that the .testing. prefix works. If your machine is at Bytemark, this has already been setup for your machine’s Bytemark alias, for example example.vm.bytemark.co.uk.

If your machine is not hosted at Bytemark, or your hostname does not end in bytemark.co.uk then you will need to set this alias up. Adding the following line to your DNS file will work, assuming the domain is hosted at Bytemark. This assumes that your machine is called host.example.com and that your machine’s IP address is 1.2.3.4.

*.host.example.com:1.2.3.4

Bytemark Hosting offer wholesale spam protection for their hosting customers.

Of course this can be integrated into the Symbiosis system. For the domain my-brilliant-site.com the DNS file at /srv/my-brilliant-site.com/config/dns/my-brilliant-site.com.txt would need to be changed as follows.

Please note that this is a chargeable service.

Now within the next hour, mail will be routed via the Bytemark anti-spam machines.

The final step is to make sure that only mail from the Bytemark anti-spam machines will be accepted. To do this for a domain, create the file /srv/my-brilliant-site.com/config/bytemark-antispam. This will cause mail sent directly to your machine to be temporarily rejected, ensuring spammers cannot circumvent the anti-spam protection.

If you wish to move your domains between two machines running Symbiosis and using the Bytemark content DNS service, you must contact Bytemark Support to arrange the domain to be moved between content DNS accounts.

This results from the necessity for ensuring that only people with the proper authorisation can change live DNS data. Once a domain has been hosted on our network, a content DNS account will have sole authority for it.

If you purchase a second server and move some of your domains onto it, or purchase a domain from another Bytemark customer you must contact us to move authority for the domain into the correct account.

Until this is done, although the Symbiosis system will be creating and uploading data it will not be to the account with the authority to make the data live.

A crontab can also be tested. To do this you have to SSH to the machine, usually as admin to run the command.

For example, to test the my-brilliant-site.com crontab navigate to /srv/my-brilliant-site.com/config/ and run symbiosis-crontab --test crontab.

The my-brilliant-site.com crontab reads

# Send any output to Bob
#
MAILTO=bob@my-brilliant-site.com

#
# run at 18:40 every day
#
40 18 * * *       echo Hello Dave.

#
# run at 9am every Monday - Friday
#
0   9 * * mon-fri wget http://www.my-brilliant-site.com/cron.php

#
# Run once a month
#
@monthly          /usr/local/bin/monthly-job.sh

Therefore the output generated is

 Environment
 ------------------------------------------------------------------------
 HOME = /srv
 LOGNAME = admin
 PATH = /usr/local/bin:/usr/bin:/bin
 MAILTO = bob@my-brilliant-site.com
 ========================================================================

 Jobs next due -- Local time 2010-06-17T17:57:37+01:00
 ------------------------------------------------------------------------
 Date                       Command
 ------------------------------------------------------------------------
 2010-06-17T18:40:00+01:00  echo Hello Dave.
 2010-06-18T09:00:00+01:00  wget http://www.my-brilliant-site.com/cron.php
 2010-07-01T00:00:00+01:00  /usr/local/bin/monthly-job.sh
 ========================================================================

As a security measure, your MySQL server is not opened to the world. However you might wish to access it remotely for performing queries, or allowing other hosts to otherwise communicate with it.

Your MySQL server should be configured already to listen upon your external IP addresses. Therefore only two steps are needed to configure remote access: opening the firewall, and adding a user with remote privileges to the database.

backup2l is controlled via configuration file /etc/backup2l.conf, this file is well documented, but in brief it contains three important pieces of information:

The Bytemark Symbiosis system will replace the static file /etc/backup2.conf with a symbolic link to a generated file, which is produced by concatenating the contents of the /etc/symbiosis/backup.d directory.

Additionally we’ve configured the backup software to easily execute a number of scripts before and after the backup is performed:

To list the contents of your backup area you need to run backup2l with the "-l" flag:

~# backup2l -l
all.1: /etc/.pwd.lock
all.1: /etc/GeoIP.conf.default
all.1: /etc/X11/Xresources/x11-common
all.1: /etc/X11/Xsession
all.1: /etc/X11/Xsession.d/20x11-common_process-args
all.1: /etc/X11/Xsession.d/30x11-common_xresources
all.1: /etc/X11/Xsession.d/40x11-common_xsessionrc
all.1: /etc/X11/Xsession.d/50x11-common_determine-startup
...

Here you will see the contents of the /etc directory which have been archived.

If you’d like to restrict this view you can apply a regular expression to filter the results. For example we can list the files which match the pattern passwd with this command:

~# backup2l -l passwd
Listing locations...
all.1: /etc/exim4/passwd.client
all.1: /etc/passwd
all.1: /etc/passwd-
all.1: /etc/phpmyadmin/htpasswd.setup
all.1: /etc/pure-ftpd/pureftpd.passwd
...

To illustrate how this works, an example is used. We’re looking for a backup of the file /etc/passwd.

That has restored the file to etc/passwd in the current directory. It is not recommended to run this program in the / directory, as any existing files will get overwritten.

It is also possible to pick which version of a file you wish to restore.

We have now successfully restored the file to etc/passwd in the current directory. We can check by running ls -la etc/

total 16
drwxr-xr-x  2 root  root  4096 2008-09-09 09:56 .
drwxr-xr-x 14 root  root  4096 2008-09-09 09:51 ..
-rw-r--r--  1 root  root  1118 2008-06-19 11:29 passwd

The Symbiosis system assumes that it is running upon a host provided by Bytemark, with access to an associated external storage area.

As documented every executable located in the directory /etc/symbiosis/backup.d/post-backup.d is executed at the conclusion of a successful backup.

By default only a single script is included, which attempts to determine the name of the remote backup space associated with your machine and copy the local backup directory of /var/backups to this remote location.

TODO The daily offsite backup will protect you - document retrieval, via a script.

The symbiosis-monit command is responsible for testing each of the available services, and restarting the failed ones. By default it is executed every two minutes, such that it may respond quickly to failures.

At any time you wish to check upon the health of your system you may launch it manually, when connected to your server via SSH.

kvm4:~# symbiosis-monit
= Bytemark Virtual Hosting service test report ========================

 * Host: kvm4.vm.bytemark.co.uk
 * Tests started at: Fri, 11 Jun 2010 15:55:45 +0100

 * apache2: PASS
 * clamav-daemon: PASS
 * clamav-freshclam: PASS
 * cron: PASS
 * dovecot: PASS
 * exim4: PASS
 * mysqld: PASS
 * pure-authd: PASS
 * pure-ftpd: PASS
 * spamassassin: PASS
 * sshd: PASS

 * 11/11 tests passed on first attempt.
 * Tests finished at: Fri, 11 Jun 2010 15:55:46 +0100

= End of service test report ==============================================

In this case all services are working correctly, so "PASS" was reported instead of the failing "FAIL". The possible output status are:

If you already had a password configured for the MySQL database prior to installing our packages it will be unchanged. The password for the root user is only changed if it is unset when the packages are installed or updated for the first time.

The Debian MySQL packages create a local user for automated use, so if you’re unsure of your MySQL password you may this login to reset it. You may find details of the Debian login contained in the file /etc/mysql/debian.cnf.

You, or a customer with FTP or SFTP/SSH access, may become locked out of the machine if repeated attempts are made to access the machine incorrectly

If you believe you’ve become locked out, via the firewall, it is possible to fix this if you have another means of connecting to your server.

Every evening your system will be configured to update itself. This ensures that you’ll have any Debian-provided security updates applied to your system. It will also update your system to the latest available collection of the Bytemark Symbiosis packages.

If your system fails to update you may correct this by running, as root:

apt-get update
apt-get dist-upgrade
apt-get -f install

The mail-server and FTP-server we’re running will refuse to work with directories which are owned by the root user.

If you find that you’ve added a new site/mailbox to your system and it doesn’t work but existing ones do then this is most likely the source of the problem.

Unless you’re handling ownership in a special way you may reset the permissions to avoid this problem by running the following command:

chown -R admin.admin /srv/

If you run into problems with the configuration of SSL-based sites please get in touch, this support is still very new and there might be a couple of kinks to work out of the process.

The most common problem is that you need to install a "bundle" or keychain file.

If the missing keychain/bundle is the problem you’ll see this logged in the Apache SSL error file beneath /var/log/apache2. Each generated SSL-site will use its own logfile - rather than the global access.log and error.log file. So taking a look at that could be useful with the shell command:

tail /var/log/apache2/*ssl*.log

You should be able to validate the combined SSL private key and certificate via the use of the openssl tool; run the shell command:

openssl verify /srv/my-brilliant-site.com/config/ssl.key
..
error 18 at 0 depth lookup:self signed certificate
OK

You’re looking for the "OK" at the end, rather than the error message which is harmless.