How to export and import CompleteFTP configuration between servers and versions

CompleteFTP Manager has no Export configuration command, and people looking for one usually conclude that the settings cannot be moved. They can. The entire configuration, every user, password, group, folder, permission, site, protocol setting, event trigger, SSH host key, TLS certificate and licence activation, lives in a single file called config.db. Copying that file is the export, and putting it where a new installation will find it is the import. The installer has an import prompt and no export button because the export is a file copy.

Two names are used throughout, because a migration has two machines in it and almost every mistake below comes from doing something to the wrong one:

  • the source server is the machine the configuration is coming from.
  • the target server is the machine it is going to.

Which situation are you in?

Answer from what you already know, and read one case only.

Case What you are doing Read
A Installing a newer release of CompleteFTP on the machine it already runs on. No second machine involved. Case A
B Moving to a Windows machine, from Windows or from Linux Case B
C Moving to a Linux machine, from Linux or from Windows Case C
D Taking a copy you can restore onto the same machine later Case D

B and C are decided by the target server's platform, not the source server's. Both move the same file, and the file is identical either way. What differs is the tool that brings the configuration up to the installed release once it arrives: on Windows that is the installer or cftpconfig, on Linux it is the completeftp config new command, and neither exists on the other platform. Moving between platforms adds one more rule, which is in both sections: an activation issued for Windows is rejected on Linux, and an activation issued for Linux is rejected on Windows.

Two things that are not cases:

  • If the source server's configuration file is named config.sdf rather than config.db, read If you are on an older release before you start. It changes how the file is imported.
  • Two servers cannot be combined into one. There is no merge tool and no user-import command; see failure mode 7 for what to do instead.

The short version

Case A needs none of this: the installer does the export and the import for you. For Cases B, C and D, these three steps are the same.

  1. Stop the CompleteFTP service. The running service holds the configuration in memory and writes it back on save, so a copy taken while it runs may be stale, and a file dropped in under a running service will be overwritten.
  2. Copy config.db from the configuration directory (see Where the configuration lives). This one file is the export.
  3. Copy the user home directories too if the files themselves have to move. They are not inside config.db.

Then one section only:

  • Same machine, newer release → Case A.
  • Windows target → Case B.
  • Linux target → Case C.
  • Backup and restore on the same machine → Case D.

If the move crosses machines, read Transferring the licence as well. Without it the target server accepts local connections only, however perfect the configuration is.

Where the configuration lives

Windows Linux
Configuration file C:\ProgramData\Enterprise Distributed Technologies\Complete FTP\config.db /var/lib/completeftp/config/config.db
Automatic backups …\Complete FTP\Backup /var/lib/completeftp/config/Backup
User home directories …\Complete FTP\Users /var/lib/completeftp/users
Public folder …\Complete FTP\Public not created
Share links …\Complete FTP\Share\Sites /var/lib/completeftp/share
Logs …\Complete FTP\Logs /var/log/completeftp
Program files C:\Program Files\Complete FTP /usr/lib/completeftp
Service CompleteFTP (display name Complete FTP Server) completeftp.service

The program files directory contains no configuration at all. Copying C:\Program Files\Complete FTP to another machine moves nothing you need and is the single most common wasted afternoon in this procedure.

Folders you added yourself can point anywhere, including at network shares and other drives. Those paths are recorded in config.db but their contents are not, so list them before you start.

What travels inside config.db, and what does not

Inside config.db Outside it
Users, passwords, groups, public keys The files in the users' home directories
Folders, mappings and permissions Anything stored on a network share or another drive
Sites, protocol settings, ports and interface bindings Firewall rules and DNS records
SSH host keys and TLS certificates Certificates you keep elsewhere for other purposes
Event triggers, scheduled tasks, IP filters Custom web content you placed outside the configuration directory
Administrator account and admin port The Windows service configuration
The licence activation key Nothing: the key travels but stops being valid, see below

Nothing in the file is tied to the machine except the activation key. Passwords, host keys and certificates are stored in a form that any CompleteFTP installation can read, which is why a copied configuration produces a server that clients recognise, with the same host key fingerprint they have already accepted.

Two consequences worth knowing before you plan the cutover:

  • The configuration adopts its new home on first start. The machine name recorded for the server is updated to the target machine's name, and the list of the machine's own addresses is refreshed. Per-protocol interface bindings you set by hand are not, so a site pinned to a specific IP address on the source server will still be pinned to it on the target.
  • The diagnostics zip is not a backup. The config.db produced by Save diagnostics in the Monitoring panel has the SSH host keys, the TLS certificates and every user's password removed before it is written. It is for sending to support. Restoring it would give you a server with no keys and no logins.

Case A. A newer release on the same machine

Nothing needs exporting. The installation carries the configuration forward, backing it up first, and the activation stays valid because the machine has not changed.

On Windows, run the new installer over the existing installation with CompleteFTP Manager closed. The configuration step finds the existing config.db, pre-selects Keep existing configuration, backs the file up, and upgrades it to the installed release in place. Users, folders, passwords, certificates and the activation key are all carried forward. The only decision on that page is which of the three options is selected: leave it on Keep existing configuration, because Create new configuration discards everything including the activation key, and the page says so.

On Linux, install the new package over the old one. Its install script runs completeftp config new against the existing configuration file, which backs the file up and upgrades it in place, then restarts the service. You do not run anything by hand.

If you want a copy of the configuration in hand before you start, take one as in Case D first. Both installations write their own backup as well, into the Backup directory, before they change anything.

Case B. Moving to a Windows machine

Put the configuration file in place on the target machine, then run the installer over it. The installer upgrades the configuration it finds to the release being installed, so this needs no command line and no second pass, and the source server stays untouched and serving clients until you choose to stop it.

If the source server is Linux, its configuration file is at /var/lib/completeftp/config/config.db and its home directories at /var/lib/completeftp/users, and step 2 becomes sudo systemctl stop completeftp and a copy of those two paths. Everything else below is unchanged, except that the licence must be re-issued for Windows (see Transferring the licence).

  1. On the source server, stop the CompleteFTP service and copy C:\ProgramData\Enterprise Distributed Technologies\Complete FTP\config.db somewhere you can reach from the target. Copy the Users directory too if the home-directory contents have to move, plus anything under Public and Share. Restart the service afterwards if the source server is still in production.
  2. On the target server, put config.db in place before installing. Copy it to C:\ProgramData\Enterprise Distributed Technologies\Complete FTP\config.db. If CompleteFTP is already installed on the target, stop the service first and replace the file there.
  3. Run the installer. Install the release you intend to end on, which can be newer than the source server's release. The installer finds the configuration already in place and upgrades it to the release being installed, so there is no separate import step and no second pass.
  4. On the target server, copy the user home directories into …\Complete FTP\Users, and re-create by hand any folder whose contents live on a share or another drive.
  5. On the target server, start the CompleteFTP service and connect with CompleteFTP Manager. The manager must be the same release as the server or it will refuse to connect.
  6. Transfer the licence, which touches both machines, as described in Transferring the licence. Until you do, the target server accepts connections from its own machine only.
  7. On the target server, check the settings that name the machine: per-protocol interface bindings if you pinned a site to a specific address, any trigger or scheduled task holding the old hostname, and any folder pointing at a path that does not exist on the target.

This is the same method the product guide's migration page describes, and it is the only one support recommends. A config.sdf from an early release is the one case that still needs the guide's longer route, described in If you are on an older release.

Case C. Moving to a Linux machine

The file format is the same on both platforms, so config.db copies across in both directions. What does not copy is anything that depends on Windows.

On the source server, stop the service and copy config.db and the user home directories, as in the short version. On a Windows source those are C:\ProgramData\Enterprise Distributed Technologies\Complete FTP\config.db and the Users directory beside it; on a Linux source, /var/lib/completeftp/config/config.db and /var/lib/completeftp/users.

Then, on the target server:

sudo systemctl stop completeftp
sudo cp /path/to/config.db /var/lib/completeftp/config/config.db
sudo dotnet /usr/lib/completeftp/bin/completeftp.dll config new /var/lib/completeftp/config/config.db
sudo chown completeftp:completeftp /var/lib/completeftp/config/config.db
sudo systemctl start completeftp

config new reads as though it would overwrite what is there. It does not. Given a path that already holds a configuration it backs the file up and upgrades it to the installed release, and it creates a new one only when the path is empty. This is the same command the package's own install script runs, which is how a package upgrade brings an existing configuration forward. Add -d to see the version numbers it reports while it works.

The chown matters: the service runs as the completeftp user, and a file you copied in as root stays owned by root.

What will not work after a move from Windows:

  • Windows users. Accounts that authenticate against the Windows account database do not carry over as they stand, but Linux has a direct equivalent: OS users, which authenticate against the host's own accounts through PAM. Re-point those users at the Linux equivalent, or recreate them as CompleteFTP users.
  • Windows folders and Windows file permissions. Any folder whose path is a drive letter or a UNC path has to be re-pointed at a Linux path, and per-folder Windows permissions do not apply.
  • The licence. An activation issued for Windows is rejected on Linux and the server starts in restricted mode, logging Windows license used on Linux machine. Running in restricted mode. The reverse move logs Linux license used on Windows machine. Running in restricted mode. Ask support for an activation for the platform you are moving to before you cut over.

There is no cftpconfig on Linux, and no installer wizard, so a config.sdf from an early release cannot be converted there at all. Convert it on a Windows machine first (If you are on an older release), then move the resulting config.db.

Case D. Backup and restore on the same machine

To take a backup: stop the CompleteFTP service, copy config.db somewhere off the machine, start the service. That file is a complete, restorable configuration. There is no separate backup command and none is needed.

You may not have to take one at all. CompleteFTP writes its own copies into the Backup directory beside config.db, and keeps fifteen of each kind:

Prefix Written when
update_ An installation or a cftpconfig run is about to change the configuration
daily_ The first time the configuration is saved on any given day
overwrite_ A cluster member is about to have its configuration replaced by the primary's

The file name carries the configuration's version and the date, for example daily_2611_20260803.db. That version is the one thing you must check before restoring, because the service refuses to start when the configuration's version and the software's version differ.

To restore:

  1. Stop the CompleteFTP service: net stop CompleteFTP from an elevated prompt on Windows, sudo systemctl stop completeftp on Linux.
  2. Copy the backup file over config.db, renaming it to config.db. A backup whose name ends in .sdf came from a release old enough that the file format has since changed: see If you are on an older release before you go further.
  3. If the version in the file name is older than the installed release, bring the file up to date. On Windows, run cftpconfig /v from an elevated prompt in C:\Program Files\Complete FTP\Server; this also restores the file permissions the service needs. On Linux, run sudo dotnet /usr/lib/completeftp/bin/completeftp.dll config new /var/lib/completeftp/config/config.db followed by sudo chown completeftp:completeftp /var/lib/completeftp/config/config.db, because a file you copied in as root stays owned by root and the service runs as completeftp.
  4. Start the service.

Restoring onto the same machine keeps the activation, so nothing else is needed.

Transferring the licence

A production activation is bound to the machine it was issued for. Copy the configuration to another machine and the key travels with it but stops matching, so the target server starts in restricted mode and accepts connections originating on that machine only. Everything else works, which is what makes this confusing: the users are all there, the manager connects, and no client outside the box can log in.

The order that avoids trouble:

  1. On the target server, confirm the configuration is in place and the service starts.
  2. On the source server, release the activation. The source server switches to migration mode and stays fully operational for a further 30 days.
  3. On the target server, apply the purchased licence.

CompleteFTP Manager runs on Windows only, though it can administer a server on any machine: enter the other machine's name or address in its connect dialog. From the manager, steps 2 and 3 are Licensing in the left-hand list, then Release activation and Apply purchased license; while migration mode is running that panel shows CompleteFTP Migration (N days left). From the command line on the server itself, the same two steps are:

completeftp license release online <username> <password>
completeftp license activate online <purchase-reference> <username> <password>

The user name and password are the ones for your account on the EnterpriseDT customer site, not a CompleteFTP login. completeftp license show reports the current state.

Releasing an activation cannot be undone without help from support, and the confirmation dialog says so before you commit. There is no cancel-migration-mode command. If you have to abandon the move after releasing, raise it with support; the source server keeps working in the meantime.

Two variations worth knowing before you start:

  • If you cannot reach the source server at all, ask support for an additional activation rather than releasing.
  • If the target server has no internet access, the manager's activation form offers a browser-based route that you complete on another machine and paste back. The command-line equivalents are the offlinerequest and offlineapply forms of the same two commands.

When it doesn't work

Ordered by how often each comes up, with the cases each applies to.

1. The users are all there but nothing outside the machine can connect. (B, C) The activation did not transfer. The server is in restricted mode, which permits local connections only. See Transferring the licence. On a Windows-to-Linux or Linux-to-Windows move, check the target server's Diagnostics.log for the restricted-mode line even if you did transfer the licence: the activation is platform-specific. The log directory is in Where the configuration lives.

2. The installer does not offer "keep the configuration file". (B, C) On a machine that has no configuration yet, the configuration step offers Create new configuration and Import configuration from other location only. Keep existing configuration appears once a configuration file is present in the configuration directory, which is why the guide's migration steps have you copy the file into place and then run the installer a second time. Both options do the same job; import is the one to use when the file is somewhere else.

3. Importing an old config.sdf fails. (B, D) The import file dialog offers *.sdf as a file type, but selecting one produces an error such as File opened that is not a database file, because the imported file is treated as a config.db. The conversion only happens for a config.sdf sitting in the configuration directory. Put the file at C:\ProgramData\Enterprise Distributed Technologies\Complete FTP\config.sdf and choose Keep existing configuration instead. See If you are on an older release.

4. The configuration was copied from the program files directory. (B, C, D) Nothing under C:\Program Files\Complete FTP is configuration. If the target server came up with a default set of users after you copied a directory across, this is why. The configuration directory is under ProgramData, which is hidden in Explorer by default.

5. The file was copied while the service was running. (all) The running service holds the configuration in memory and writes it out when changes are applied, so a copy taken from a live machine can be missing the last change or, worse, be a half-written file. Stop the service first. On the target the failure is louder: drop a file in under a running service and the next save overwrites it.

6. The site is still bound to the old machine's IP address. (B, C) Interface bindings that name a specific address are part of the configuration and move with it. The service starts, but the listener for that protocol has nothing to bind to. Check each site's per-protocol interfaces in the manager after the import, and set them back to all interfaces unless you have a reason not to.

7. Two configurations cannot be merged. (B, C) There is no merge tool, no user-import command, and no way to combine two config.db files. An import replaces the whole configuration. To consolidate two servers you either re-create one side's users and folders by hand on the other, or keep them apart as two sites within one configuration. Export each server's user list first, with Export users on the right-click menu of the Users panel, so you have the inventory to work from. The exported columns include the password hash, not the password, so logins have to be re-issued.

8. A configuration from a newer release will not go backwards. (B, C, D) The upgrade path is one-way. Importing a configuration that came from a later release into an earlier one re-stamps the file with the installed version, which lets the service start, but nothing converts the later release's structures back. Install the same release as the source server, or a newer one, and never an older one.

9. The home directories are empty on the target server. (B, C) config.db records where each user's home folder is, not what is in it. Copy the Users directory across as well, and handle folders that live on shares or other drives separately.

10. The service will not start after the import. (B, C, D) The usual cause is a configuration whose version does not match the installed software. Run cftpconfig /v on Windows or config new on Linux against the file, which upgrades it and, on Windows, resets the permissions the service account needs. A full walkthrough of the other startup failures is in the article on the service failing to start after an upgrade, listed under Related.

Reading the output

Both configuration tools report the two version numbers that matter. cftpconfig /v writes them to the console and to cftpconfig.log in the same directory as the executable; the installer's configuration step writes them to Bootstrapper.log beside it; config new -d on Linux writes them to the console:

Current config version: 12.1.1
Upgrading to version: 26.1.1

The first line is the version of the file you imported, read out of the file itself. If it is not what you expected, you imported the wrong file. The second is the installed release. When the run finishes without an error, those two are equal and the service will accept the configuration.

Two dialogs come from the installer's file check rather than from the import itself, and both mean the path is wrong rather than the file being bad: Configuration file does not exist at and Error opening configuration file. The second also appears when the file is open in another program, which on the source machine usually means the service is still running.

If you are on an older release

The configuration file was config.sdf up to and including release 21.1.0, and config.db from 22.0.0 onwards. A config.sdf is converted automatically, but only when it is sitting in the configuration directory: copy it to C:\ProgramData\Enterprise Distributed Technologies\Complete FTP\config.sdf on a Windows target, run the installer, and choose Keep existing configuration. Selecting the same file through Import configuration from other location fails with File opened that is not a database file. Linux has no conversion at all, so convert on Windows first.

Related

Other technical articles

Download Free Trial