(You must already be logged in to Gitlab or you’ll hit a 404)
Symbiosis migration guide
If you’re using Symbiosis to manage your server, then migrating your Symbiosis installation to a new server is reasonably straightforward. There are a few things to watch out for though, which we’ll cover below.
In this guide, we assume you are able to:
- use Symbiosis from the command-line e.g. over SSH.
- use a Cloud Server to create a new Symbiosis server, purchase a Bytemark Dedicated Server with Symbiosis or install Symbiosis on your own server.
- tolerate some planned downtime whilst the migration takes place.
What this guide covers
This guide applies to three main scenarios:
- moving from a legacy VM to a Cloud Server or a Dedicated Server.
- upgrading from Symbiosis Squeeze or Wheezy to Jessie and wanting a fresh installation to start from.
- restoring Symbiosis from an off-site backup taken with the included
backup2lto a fresh installation.
Importantly, this guide covers migrating anything you have installed and set up under
/srv/, as well as your Symbiosis configuration rules. This includes:
- your domains and websites.
- email mailboxes and spam-filtering rules.
- any applications that you’ve installed exclusively under those domains - that is, their files are all beneath
- MySQL databases and database users, so applications shouldn’t require any major reconfiguring if they’re set to use a
- firewall rules.
Important things to consider before you start
Are your IP addresses going to change?
This is almost certainly the case if you’re migrating between platforms, e.g., a legacy VM to a Cloud Server or a Cloud Server to a Dedicated Server.
Sites and applications hosted on their own IP address will need a new one if you can’t take them with you.
Cloud Servers make it easy to get extra IP addresses through the control panel. You’ll then have to update each domain’s IP address through the
Alternatively, you could take the opportunity to start using Server Name Indication (SNI). SNI lets you host multiple sites on the same IP address even if they use SSL. This will make future migrations even simpler and reduce the admin overhead that comes with managing lots of IP addresses per server.
Are you running anything that is installed outside the Symbiosis system described above?
If you are, this will not be migrated if you use the process below and is outside the scope of this guide.
Is your DNS managed by Symbiosis on Bytemark’s name servers?
If so, then this guide includes instructions on how to migrate the “authority” to set DNS records to the new (destination) server. This doesn’t apply if you’re restoring from a backup of a server that is no longer live.
If you’re not using Bytemark and Symbiosis to handle DNS, you’ll have to update your records by hand when you migrate over; remember to set your TTL as low as possible (300) well in advance of this.
1. Perform a complete backup of your current Symbiosis installation
Perform a fresh backup, even if your system has been backed up recently. Login to your server using the
admin user and run:
$ sudo backup2l -b
This will take a complete backup of your system and store it in
Note: If you’re restoring from an existing backup, then this step doesn’t apply.
2. Prepare the destination Symbiosis server
Create a new Cloud Server, e.g. via the web panel and choose
symbiosis as the distribution. A small, default server with 1 core, 1GB RAM and 25GB of SSD storage will cost £10 per month*. See below if you want some extra backup space.
If you’re ordering a new Dedicated Server from us, ensure you’ve specified
symbiosis as the preferred distribution in the order form.
Alternatively, if you want to install Symbiosis on your own server hardware, then you need to first install Debian 8.0 (Jessie) followed by the instructions in the Symbiosis documentation.
Legacy VM users and those who want extra backup space
The Legacy VMs are supplied with 50GB backup space.
With Cloud Servers, you get more storage space on your root disc for the same price but no automatic, separate backup space. By default, backups are stored in
/var/backups on your root disc. Symbiosis requires space for two full backups.
We recommend that when you create a server and choose to add an
Archive disc to your Cloud Server. 50GB is just £1 extra per month* and should hold all your backups. You can also add extra discs to your Cloud Server after you’ve created it.
Once you’ve added an extra disc, your server will show it as an additional drive with the default label
/dev/vdb/ (unless you changed it). You then need to format and prepare it.
Format the drive and name the volume
backup by running:
$ sudo mkfs.ext3 /dev/vdb -L backup
Now, we need to mount the drive at the default location where Symbiosis puts backups (
$ sudo rm /var/backups/localhost /var/backups/mysql
This clears out some empty directories. Now, use your favourite editor (e.g.
nano) to add the following line to
/dev/vdb /var/backups ext3 defaults 0 0
You will need
sudo. Finally, mount the new backup drive in the right place:
$ sudo mount /var/backups
That’s the end of the prep for your new server. To check this has worked properly, run:
$ df -h
This should show a line like:
/dev/vdb 50G 180M 47G 1% /var/backups
That means you’ve successfully mounted your new disc in the right place.
Note: now that you’ve prepared your new server, we’ll refer to it as the destination server.
* All prices exclude VAT.
3. Disable Symbiosis on the old server and update the backup
To avoid the risk of data being different between the “old” (source) server and the destination, we need to disable most of the Symbiosis services.
Login to the source server as
admin over SSH. Disable the auto-restart functionality of Symbiosis by running:
$ sudo touch /etc/symbiosis/monit.d/disabled
After that, you need to shut down Apache and stop emails from being accepted by the server. This is necessary so that nothing changes in the next step:
$ sudo service apache2 stop $ sudo service exim4 stop
Note: this is the first visible impact that this migration will have on your users - they will not be able to view websites on the server or send/receive email. Once your server has migrated and the DNS updated, any emails that did not get delivered during that time should be redelivered by the sender’s email servers.
At this point, your source server should be in a “static” state and you must run another backup. This is to account for any changes on the source server since the first backup.
$ sudo backup2l -b
This incremental backup will be quicker than the first backup unless you’ve decided to take a pause between the steps above.
4. Transfer backups from the source to the destination server
The simplest way to do this is to use
rsync to copy the backups from the source to the destination. You will need your
root user password on the destination to perform this transfer (by default, this is the same as the
admin user on Symbiosis).
On the source server, run:
$ sudo rsync -avz --progress /var/backups email@example.com:/var
Note: there is no slash at the end of the above command.
Whilst this is taking place, you’ll see a progress report and file transfer speeds. Time for a cup of tea?
Note: if you’re restoring your Symbiosis server from backups you should simply copy the backups to
/var/backupson the destination server using the
Once your backups have transferred to the destination server, you need to decommission the source server.
If you use Symbiosis to handle your domains on Bytemark name servers, make sure you get in touch with support to help you transfer the authority for those domains to your new server.
5. Extract the backups on the destination server
Login to the destination server as
admin over SSH.
You now need to extract the backup, in the following suggested order.
- Restore the firewall rules.
- Restore the domain structure (anything under
- Restore the databases to the right place.
To restore files to their original location: you must execute the
backup2l commands whilst located in the filesystem root. To do this, run:
$ cd /
Otherwise, the restored files will end up in the wrong place in the filesystem.
Note: The following commands may take some time to execute and do not show “verbose” output.
Restore firewall rules
Run the following command to restore firewall rules:
/$ sudo backup2l -r /etc/symbiosis/firewall/
Your own IP address will have been automatically whitelisted by Symbiosis when you logged in successfully over SSH.
If you have erased any of the default firewall rules on your old server (e.g.
50-reject-www-data), you will have to erase them again. Make sure no other firewall rules are likely to lock you out.
Restore the domain structure
Now, restore the main bulk of your data - the domain structure under
/srv/ by running:
/$ sudo backup2l -r /srv
Restore the MySQL databases
The databases and their users are stored in the backups and must be extracted before any dependent applications can use them.
We’ve written a script that automates this step, rather than having to do each database manually.
Run the following command:
$ cd /srv/ $ wget https://raw.githubusercontent.com/BytemarkHosting/symbiosis-pieces/master/symbiosis-mysql-restore
Once you’ve got the script, simply run it and follow the prompts.
$ bash symbiosis-mysql-restore -u root
You will need the MySQL root password of the destination server (by default this password is the same as the
admin login user).
The database import will also import all the users from the source server’s database, but this also imports system users from the source server and overwrites any credentials that already exist on the destination server. This includes both the
root user and the
root user password will now be the MySQL
root user password from the source server. You can now switch to using that password, or reset it if you prefer.
debian-sys-maintenance user must be reverted back to the password that existed on the destination server prior to the database import. You can find this password in plain text by running:
$ sudo cat /etc/mysql/debian.cnf
Then using something like phpMyAdmin (or MySQL commands), simply replace the
debian-sys-maintenance user password with the one listed in the file above. You will need to use the
root user again.
5. Adjust IP addresses of the destination server and grant authority to make DNS changes
If you have specified IP addresses per domain in Symbiosis, you will now have to check and change them on the destination server if required. This is particularly important if:
- you use Symbiosis to manage DNS records for your domains on Bytemark’s name servers.
- you know you have set specific IP addresses for sites on your server, e.g. if they use SSL.
The IP addresses are listed in
/srv/my-brilliant-site.com/config/ip (changing the example!).
This is a good opportunity to implement SNI, as mentioned previously.
Note: SNI lets you host multiple sites on the same IP address even if they use SSL. This will make future migrations even simpler and reduce the admin overhead that comes with managing lots of IP addresses per server.
If you have a simple Symbiosis set up, with no specific IPs set per site, then you shouldn’t have to make any changes.
Once you’re confident that any IP address issues have been resolved, you can grant your destination server the authority to make changes to your DNS records on Bytemark’s name servers, if appropriate. Run the following command whilst again being located in the filesystem root:
$ cd / /$ sudo backup2l -r /root/BytemarkDNS
Finally, make your DNS changes live and await propagation. On Symbiosis you can force this to happen quicker by running:
$ sudo symbiosis-dns-generate --verbose
Note: If you use another method to manage DNS, e.g. a domain registrar’s control panel and name servers, then make the necessary changes now.
DNS can take a while to propagate, but we set the TTL (Time To Live) for records managed by Symbiosis to 300 seconds - so, five minutes or so. Some caches that aren’t configured properly will add to this time, but the majority of people should be able to get to your new site after five minutes.
6. That’s it!
At this point, your new Symbiosis server should be working happily. Give it a day or two, check that fresh backups are taking place and then you can safely finish decommissioning the source server.
Got a problem or suggestion? Discuss this guide on our forum.