How do I move my Citadel installation to another machine?

It is likely that your Citadel installation will outlive the hardware on which it runs. We have made several options available for migrating Citadel to new hardware.

Citadel stores its data in a binary, architecture-specific format. As a result, you can only make a direct copy of the binary files in the byte order and byte alignment are identical on the old and new hardware. So, for example, if you are moving from SPARC to Intel, or from 32-bit Intel to 64-bit AMD, this is not possible with a direct copy. For these cases we have made a migration tool available.

The source (old) system must be running Citadel 7.60 or newer. If you are running an older version, you must upgrade it first. We are committed to eliminating this requirement going forward – in other words, starting with version 7.60 we will make the over-the-wire export data format upwardly compatible.

You will also require OpenSSH v4 or newer, and a reasonably modern version of rsync, on both systems.

Go ahead and install the latest version of Citadel on the target (new) system. The target system must be running a version of Citadel that is either equivalent to, or newer than, the version on the source system.

Then log in to the console of the target system as root or root equivalent, and run the “ctdlmigrate” utility. You will be prompted for the host name or IP address of the source system, as well as the username and password of a host system account that has access to all Citadel files (once again it's easiest to just go with root or a root equivalent for this).

Then just sit back and watch it run. First, the Citadel databases will be exported to an XML format, downloaded across the wire, and imported into the target system. Afterwards, non architecture dependent files such as user photos and profiles, room info files, etc. will be copied over using rsync.

After the migration utility completes its work, simply shut down the source system, restart Citadel services on the target system, and you're up and running. You may wish to double check the configuration on the target system in case things like host IP address have changed.