How to Bytemark

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.

Prerequisites

In this guide, we assume you are able to:

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 backup2l to 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 /srv/.
  • MySQL databases and database users, so applications shouldn’t require any major reconfiguring if they’re set to use a localhost MySQL database.
  • 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 /srv/my-brilliant-site.com/config/ip file.

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.

Migration process:

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 /var/backups/.

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 (/var/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 /etc/fstab:

/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 root@destination.example.uk0.bigv.io:/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/backups on the destination server using the root user

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.

  1. Restore the firewall rules.
  2. Restore the domain structure (anything under /srv/).
  3. 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 root or 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 debian-sys-maintenance user.

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.

However, the 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.

You are currently viewing Symbiosis user documentation. Symbiosis also has a comprehensive technical reference manual.

Bytemark Cloud used to be called "BigV"—nothing has changed except the name! We’re hiring! Please visit careers.bytemark.co.uk to find out more.