Home Download FAQ / Knowledge Base Screenshots Documentation Support

Migrating an existing Citadel installation to a new 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 a new host machine (regardless of whether it is on bare metal, or a virtual machine, or something else).

Citadel stores its data in a binary, architecture-specific format. As a result, you can only make a direct copy of the binary files if the target machine has the same CPU architecture as the source machine. For example:

The source (old) system should be running the same version of Citadel as the target (new) system. It is not recommended to migrate and upgrade Citadel in a single operation. If the source system is running an older version than the target system, you must first upgrade the source system before you can migrate it.

You will be using the ctdldump and ctdlload utilities. Please read the documentation for these utilities to understand how they work.

Step 1: shut down Citadel Server on the source system

For the most reliable copy, Citadel Server should not be running while you export its data. Shut down your service with a command like systemctl stop citadel and make sure it has stopped before proceeding.

Step 2: export (dump) your database

This step exports your Citadel database to a plain text file. Use a command like this:

cd /usr/local/citadel
./ctdldump -y >/tmp/dump.dat

Step 3: copy the dump file to the target system

If you don't know how to copy a file to another computer, you are probably in over your head and should seek help.

Step 4: shut down Citadel Server on the target system

This is the same as Step 1. Do not attempt to proceed while Citadel Server is running.

Step 5: import (load) your database

Let us assume that you have copied /tmp/dump.dat to your target system. You can import this dump file into Citadel with a command like this:

cd /usr/local/citadel
./ctdlload -y </tmp/dump.dat

Step 6: Start up Citadel Server on the target system

Your target system should now be a faithful reproduction of the source system. Start up the server with a command like systemctl start citadel

Step 7: Test and tune

Log in to the target system and look around to see if all of your data (users, rooms, messages, etc.) have been copied over accurately. If you need to make any adjustments (new IP addresses, etc) now is the time to do so.

There are no social media links here. Enjoy a friendly Citadel community instead. Or go outside.