Skip to main content

Transferring Users Between FASTPANEL

Introduction​

This article describes the process of transferring user accounts and their associated data (websites, databases, email, etc.) from one FASTPANEL server to another using the built-in migration utility.

Key Terms​

  • Source server - The server from which data is being transferred.
  • Destination server - The server to which data is being transferred.

Important Notes​

  • By default, migration works correctly only for sites with a standard FASTPANEL configuration.

  • Sites with manual configuration changes can only be transferred if the -m flag is used for IP address mapping.

  • If an encrypted password for a database owner is not available, the database will not be transferred.

  • If a website is not transferred, its associated databases will not be transferred either.

  • Only local databases can be transferred.

Migration Process​

Connection​

The destination server connects to the source server via SSH. During the first connection, the destination server installs an SSH key on the source server (either pre-provided or generated from a password).

Migration Steps​

  • Module installation
  • Gathering information about transferable objects
  • Creating users
  • Transferring SSL certificates
  • Creating websites, FTP accounts, email domains, and email accounts
  • Creating databases and database users
  • Transferring website and email mailbox files
  • Transferring cron jobs

File transfer is executed using rsync. Databases are transferred by creating a dump through an SSH tunnel.

Command to Start Migration​

The command is run on the destination server as a user with root privileges:

/usr/local/fastpanel2/fastpanel transfer run [SSH_PARAMETERS] [IP_PARAMETERS] [ADDITIONAL_OPTIONS]

Command-line Flags​

SSH Connection​

  • --remote_host="SOURCE_IP" - IP address of the source server.
  • --remote_port="SSH_PORT" - SSH port.
  • --remote_username="SSH_USER" - User (must be root).
  • --remote_password="USER_PASSWORD" - Password for the specified SSH user.
  • --ssh_key_path="PATH_TO_KEY" - Path to the private SSH key on the destination server for connecting to the source server. If a key is used, the password (--remote_password) is not needed.

IP Addresses​

You must use only one of the following flags to manage site IP addresses during transfer. The -m flag has priority.

  • -i "IP_ADDRESS_ON_DESTINATION" - Assigns the specified IP address to all transferred sites on the destination server. To specify multiple IPs (e.g., if there were several on the source), repeat the flag for each source IP that needs to be transferred.

  • -m "SOURCE_IP,DESTINATION_IP" - Recommended method. Establishes a direct mapping: all sites using SOURCE_IP on the source server will use DESTINATION_IP on the destination server. This flag can be specified multiple times for different IP pairs. Mandatory for transferring sites with manual configuration edits, as it allows correct replacement of IP addresses in listen directives.

Additional Settings​

  • --users="USER_LIST" - Transfers only the specified users (comma-separated). If not specified, all users are transferred.
  • --disable_disk_quota - Disables the transfer of user disk quotas.
  • --with_user_data - Includes copying the entire contents of user home directories (except the logs/ subdirectory). Use with caution, as this can significantly increase transfer time and the amount of data transferred.
  • --only_data - Transfers only data (website files, mail files, database dumps). Useful if the initial structure migration (users, sites, DBs, etc.) was successful, but errors occurred during the file or dump copying stage. Allows rerunning only the data copying part.
  • --transfer_timeout - Set operation timeout (default is 60 minutes).

Example Command​

Transfer all users from server 11.22.33.44 to the current server. On the old server, sites used IPs 11.22.33.44 and 11.22.33.55; on the new server, they should use 99.88.77.66 and 99.88.77.67 respectively. Connection via SSH with a password.

/usr/local/fastpanel2/fastpanel transfer run \
--remote_host=11.22.33.44 \
--remote_username=root \
--remote_password=YourSourceRootPassword \
-m 11.22.33.44,99.88.77.66 \
-m 11.22.33.55,99.88.77.67

Possible Problems and Error Types​

An error in the migration log does not always indicate a critical problem but might point to the reason why a specific object was not transferred.

  • Conflicts: Occur when transferring an object is impossible due to the current configuration of the destination server (e.g., a user or site with the same name already exists) or if the site's configuration on the source server is unknown to the panel (e.g., due to extensive manual edits).

  • Missing Saved Password: As mentioned earlier, MySQL database users without a saved password in FASTPANEL on the source server cannot be transferred.

  • Manual Settings and IP Addresses: If a site on the source server has manual web server configuration edits and the -m flag is not used during migration to map its IP address, such a site will not be transferred because the panel does not know which IP to specify in the configuration on the destination server.