TurnKey Linux Virtual Appliance Library

TKLBAM: Migration to v14.x from earlier versions of TurnKey Linux

There have been some significant changes in Debian Jessie (what TurnKey Linux v14.x is based on) from previous versions. This page is aimed at providing a general overview and some info on a couple of common issues. It is not exhaustive and you may well encounter other issues.

If you have strange things happen after migrating from an earlier version of TKL to v14.x then please post on the support forums and someone will be along to try to help ASAP. Also if you are a Hub user (or AWS Marketplace subscriber) then please also feel free to try our support portal (accessible when logged into the Hub).

Suggested migration workflow

It is suggested that you migrate from older (pre v14.x) versions of TurnKey in a staged process, something like this:
  1. Audit restored data in new server - check what is working and what isn't.
  2. Resolve issues noted in your audit, documenting as you go.
  3. Do the final migration.

1. Initial restore and audit

It is recommended that you do not touch your production server (where your backup comes from) until the migration is complete and you are 100% satisfied.

First check that your latest backup is fairly recent. Anytime within the last month (or so) should be adequate for now (although ideally you should be doing daily backups). Then restore your data to a test server and do a full audit. Take careful note of what is working and what isn't. Once you have the audit complete, take some time to do some research on anything you are unfamiliar with.

When searching for documentation/hints on specific issues, generally Google is your friend. Keep in mind that under the hood TurnKey is built on Debian, so generally stuff that applies to Debian, also applies to TurnKey.

When software is installed from upstream (e.g. TurnKey installs WordPress directly from WordPress themselves) it is highly recommended to consult their documentation too.

2. Work through issues found during audit

Consider this initial run purely a test. That way you can be fearless in your your tweaking. If you make something worse, or things get messy (e.g. trial and error without clean resolution) then you can just trash your test server and start again with a fresh restore.

Make sure you document everything you do; especially things that work. Try to focus on one problem at a time and keep working until each solution is complete. If you end up starting a fresh, any issues you have already completely resolved, don't need to be reapplied at this point. Any issues you have partially resolved, can be redone using your docs as reference.

3. Final migration

You've worked through all issues uncovered in your audit and documented their resolution. Back on your production server, where relevant and possible; put it in "maintenance mode" or otherwise lock it (so no new content is added). Then run a final backup.

Restore your new backup to a fresh new server. Take it out of "maintenance mode" (etc). Follow your docs to complete the migration so everything is working well.

Once you are 100% happy, then do any final tweaks (e.g. configure DNS to map to the new machine etc) to put it into production and do a backup of your new migrated server.

When you are ready you can destroy the old server. Note that some like to leave the old server running for a little while, just in case. Also it is recommended that before you destroy the server; within the Hub set "max backups" to 1 and force a final full backup. That will clear all the previous backups and leave you with a final legacy backup for archive/historical purposes.

Special notes for very old migrations

Some users have reported that when migrating from very old versions (e.g. v11.x) that the restored server will not boot. In cases such as that you may need to manually migrate your data. However TKLBAM can still be useful as a way of transferring your data to the new server. Instead of doing a full restore, just do a download:

tklbam-restore --raw-download=/path/to/dump/files

You can then manually transfer the files to where they need to go in the filesystem. The downloaded files should be in locations which are relative to the download directory. E.g. files that come from /var/www should be found in /path/to/dump/files/var/www

You'll still need to decide what to move and what not to, but it will make life a little easier.

Specific software

Webmin (all appliances)

As of v14.0 Webmin is now hidden behind stunnel. This means that if you restore from an earlier version you'll need to make some changes before Webmin will work again. In the Webmin server config file (/etc/webmin/miniserv.conf) make sure that you have these entries (add them or change them as appropriate):
Also double check that stunnel config (/etc/stunnel/stunnel.conf) has this (most likely right at the end):
accept  = 12321
connect =
If you have configured SSL certificates for Webmin (and/or Webshell), then you will most likely also need to configure stunnel to use them instead. E.g. adjust the lines in /etc/stunnel/stunnel.conf that says this:
cert = /etc/ssl/private/cert.pem

Apache (inc LAMP and about 70% of the library)

Apache config has had some significant changes, although the one that will break things is actually TurnKey related. We hardened the SSL in v14.0 and moved the default certificate location. We also included all the additional SSL/TLS config together (in /etc/apache2/mods-available/ssl.conf).

If you have a third party CA cert then this should not affect you (although you can move your cert if you desire). If you are using self signed certs, then simply removing reference to the old cert from your Apache vhost site files (in /etc/apache2/sites-available) should do the trick. E.g. here is the update in action on the Trac appliance.

There are other changes too that should probably be made (although Apache should still work without them). See links below for more info.

More info:

  • Apache docs: https://httpd.apache.org/docs/2.4/upgrading.html
  • Great post on Digital Ocean: https://www.digitalocean.com/community/tutorials/migrating-your-apache-c...


    Samba has gone from v3.x in all previous versions of TKL to v4.1/v4.2 in v14.x so again some significant changes. A helpful community member has solved the main issues and posted a clear outline in the forums here.