Import a server from another host

The Import tab, under More on the server's page, copies a server's files from another host into your Coritan server over SFTP or FTP. Use it to bring a world, its plugins and its settings over from another hosting company. It copies files only, so the server's software stays as it is.

• Get the file access details from the other host's panel: the address, the port, the username and the password for SFTP or FTP. FTPS is not supported: use SFTP, or plain FTP if the other host offers it.
• Check that the files fit. Everything in the folder you import must fit in this server's disk space.
• The folder you import can hold at most 250,000 files and folders. For a larger tree, import one sub-folder at a time.
• The other host must be on a public address. We refuse private and local addresses. Our own servers are the one exception: you can copy from another Coritan server, but only over SFTP on port 2022.
• The server cannot be installing, moving to another machine or suspended.
• On a server someone shared with you, the owner must have given you the Files permission, which includes the permission to create files that an import needs. Without it the Import tab is hidden. The Wipe this server first option shows only if you also hold the permission to delete files. The Files permission includes it, but a grant made through the API can leave it out (Choose permissions). The owner of the server, and an owner or admin of the organization whose deployment runs it, have both.
• If anything on the server matters, take a snapshot first. A wipe cannot be undone.

1. In the dashboard, go to App Deployment and open the server, then the Import tab.
2. Under Protocol, choose SFTP or FTP.
3. In Host, enter the other host's address, for example sftp.example.com. If you paste an address that starts with sftp://, ftp:// or ssh://, we drop the prefix and anything after the address, such as a path. An address that starts with ftps:// or ftpes:// is refused, because FTPS is not supported (Troubleshooting).
4. In Port, enter the port the other host gave you. Leave it empty for the usual port: 22 for SFTP and 21 for FTP. If you type the port after the address in Host, for example sftp.example.com:2022, and leave Port empty, we use that port.
5. Enter the Username and Password from the other host.
6. In Remote folder, enter the folder whose contents should land in this server's root folder. / copies everything the account can see. If the other host keeps the server in /minecraft, enter /minecraft, and /minecraft/world becomes /world here. If you paste the whole address, such as sftp://user@sftp.example.com:2022/minecraft, we use the folder after the host, here /minecraft, and / when nothing follows the host.
7. To delete the files and folders in this server's main folder before copying, tick Wipe this server first. You see this option only if you may delete files on the server. It stays off until the server has a name, which you can set on the Settings tab. Hidden entries and the backups folder stay (What the wipe keeps). Leave it clear to keep the files that are already here.
8. To leave out the files that are already on this server, tick Skip files already on the server. A file with the same name and size is not copied again. Use it to carry on after an import that stopped. It is switched off while Wipe this server first is ticked (Skip files that are already there).
9. Select Test connection. We sign in and count what we would copy, without writing anything. Connected shows how many files and folders the remote folder holds. Over SFTP it also shows the Host key, the key the other host presented (Check the host key).
10. Select Start import. If you ticked Wipe this server first, the button reads Wipe and import…. A dialog titled Wipe <server name> before importing? asks you to type the server's name. Type it, then select Wipe and import. The wipe starts only after you confirm.

The Import in progress card shows the status, a meter with the files and bytes copied so far, and the file being copied. While the import is Queued, a line under the card says Waiting for a free slot. The import starts as soon as one opens. You can leave the page: the import carries on, and the tab shows it again when you come back.

The tab reads the import's status every second or two. If three reads in a row fail, it shows We cannot reach the server right now. Trying again. and keeps reading, with a longer pause between reads of up to 8 seconds. The line goes away when a read works. Troubleshooting covers the other two cases, a sign-in that ended and an import the tab cannot find.

• If the server is running, we stop it before copying and leave it stopped.
• While an import is queued, copying or stopping, we refuse Start, Restart and every wake of the server, so it cannot boot on files that are half copied. Stop and Kill still work. Troubleshooting has the message. A start that a free server already has in the wake queue waits there and keeps its place.
• With Wipe this server first, we delete the files and folders in the server's main folder first. What the wipe keeps lists what stays.
• We copy every file and folder under the remote folder, empty folders included. A file with the same path as one on the server replaces it, and files that exist only on this server stay.
• With Skip files already on the server, a file that is already on the server with the same size is not copied again (Skip files that are already there).
• We skip any single file that is larger than the server's whole disk space, and list it as a file we could not copy.
• We leave out symbolic links, and special files such as devices, sockets and pipes. A link could point outside the folder you chose, and a pipe or a device can block a read for ever. These are not failures: they never count towards the 200 files that stop an import. The import status lists each one under skipped (With the API).
• On FTP, a file whose size the other host does not report is copied like any other. Some FTP hosts answer a listing of an empty folder with an error such as 550 No files found. We treat that as an empty folder and copy it as one.
• If the connection drops, we reconnect and carry on where the copy stopped.
• If the platform restarts the import's run, for example after one of our machines restarts, the import resumes. The file and byte counts, and the list of files that could not be copied, do not go down while the resumed copy works through files it already handled. A file that failed before and copies this time leaves the list.
• If many imports are running on Coritan, yours waits and shows Queued until a place is free, then starts by itself. There is a limit on how many imports run at once.
• We look at the server while the import runs. If it is suspended, starts installing or moves to another machine, the import stops (Troubleshooting).

The import fails if it runs for more than 6 hours, or once 200 files could not be copied.

Over SFTP, every host has a key that identifies it, and the Host key line under Connected shows the one the other host presented: its type, such as ssh-ed25519, and its fingerprint, which starts with SHA256:. The check protects your password. Someone who sits between us and the other host could pose as it and read the password we send.

1. Find the host's key fingerprint in the other host's panel, or ask its support. You can also list the keys it offers from your own computer: ssh-keyscan -p 22 sftp.example.com | ssh-keygen -lf -. Use the port you entered.
2. Compare it with the Host key line. Compare the line of the same type as ours.
3. If they match, select Start import. We send the fingerprint with the start, and every connection of the import must show that key. That includes each reconnect. We check the key before we send the username or password.

If you start without testing first, you have confirmed no key. We then save the key the start sees and require it for the rest of the run, so it cannot change while the import works. The test result goes away when you change the protocol, host, port, username, password or remote folder, and after you start an import. Test again to see the key of the new host. FTP has no host key, so FTP shows none.

If the key does not match, we refuse before sending your password: the start answers The other host's key does not match the one you confirmed. Check that you are connecting to the right host. (Troubleshooting).

Tick Skip files already on the server to leave out a file when the server already holds a file at the same path with the same size. The file counts as copied in the totals. Use it to run an import again after it stopped, so we do not copy everything twice.

• We compare sizes only. A file that changed but kept its size stays as it is on the server.
• A file whose size the other host does not report is always copied.
• The option is off while Wipe this server first is ticked, because the wipe leaves nothing to compare.

The wipe deletes the files and folders in the server's main folder, with everything inside the folders. It leaves these alone:

• Every entry whose name starts with a dot, such as .ssh and .sftp.
• Every entry whose name starts with backups, such as the backups folder.
• On a free server, the server executable the panel installed, for example server.jar. We do not copy a file with that name from the other host, in any folder. This is not a failure: the import status lists the file under skipped, with the reason free servers keep the server executable the panel installed. How free servers work explains the rule.

We wipe after we sign in to the other host and count the files, so a wrong password never reaches the wipe. If the wipe fails, the import stops with We could not delete the server's existing files, so the import stopped before copying.

1. On the Import in progress card, select Stop import….
2. Select Stop import to confirm.

The status reads Stopping until the copy halts, then Cancelled. While we list the other host's folder, we look for your request about every 2 seconds. While we copy a large file, we look about every second, and we delete the file that was half copied. Files the import copied completely stay on the server. A server runs one import at a time, so stop the running one before you start another.

When many requests change the same records at once, we repeat your stop a few times on our side. If the database is still busy, the answer is Please try again in a moment. and nothing changed, so select Stop import again.

The status moves from Queued to Copying, then to Completed, Failed or Cancelled. The card is titled Import in progress while the import runs and Last import after it ends. When it completes, the card says Import finished. Check the Files tab, then start the server.

• A failed import shows an alert titled The import failed with the reason the whole import stopped, for example The import ran longer than 6 hours, so we stopped it. Troubleshooting explains each reason.
• Files that could not be copied are in a list titled Could not copy N files, with every file and its reason. Select the title to open it. When a completed import has such files, the card says Import finished with N files that could not be copied. Check the list above, then start the server.
• Entries we left out on purpose are in a second list titled Skipped N entries (Skipped 1 entry for one). It names each symbolic link, device, socket, pipe and, on a free server, the server executable, with the reason. These do not make an import fail. A completed import that only has skipped entries ends with the plain Import finished. sentence.

Check the files on the Files tab, then start the server from the console. If the other host ran different software or a different version, change the server software to match before you start it. Select Dismiss to hide the card of a finished import.

Could not connect

The test failed, and the message under it gives the reason. Check the host, port, username and password against the other host's panel. Many game hosts use a port other than 22 for SFTP. Starting an import signs in the same way, and shows the reason after Could not connect to and the host and port.

The other host refused the username or password.

The other host answered and rejected the login. Check the Username and Password in the other host's panel. Some hosts use a separate login for SFTP or FTP, and some add a suffix to the username.

The other host refused the username or password. Check them and start the import again.

The other host rejected the login after the import had started, for example because the login changed. The import ends at once as Failed, and we do not try again. Check the Username and Password in the other host's panel, then start a new import. Files already copied stay on the server.

The other host refused the connection. Check the host and port.

Nothing accepts connections on that Host and Port. Check the port, and that SFTP or FTP is switched on at the other host.

The other host did not answer in time. Check the host and port.

The other host did not reply. Check the host and port, and that its firewall allows connections from outside. A server that is switched off at the other host also gives this message.

We could not reach the other host. Check the host name.

The host name does not exist, or we could not find a route to it. Check its spelling, or enter the host's IP address instead.

That port does not answer like an SFTP server. Check the protocol and port.

Something answers on that port, but it is not an SFTP server. Check that Protocol matches the port. The same message for FTP names an FTP server. SFTP usually uses port 22 and FTP port 21, and many game hosts use other ports.

The other host closed the connection.

The other host ended the session while we signed in. Try again. If it repeats, check the other host's limits on logins from outside.

We could not connect to the other host.

The connection failed for a reason we cannot name. Check every field against the other host's panel and try again.

That host is part of this platform. The importer connects to it only on port 2022, the SFTP port of a server.

The Host is one of our own addresses. To copy from another Coritan server, choose SFTP, set Port to 2022, and enter the host and username from that server's SFTP connection card on its Files tab (Connect to a server with SFTP). We refuse every other port on our own addresses.

That host resolves to a private or reserved network address.

The host name points at a private or local network, which we cannot reach. Use the other host's public address.

Remote listing timed out

The test lists the remote folder for up to 60 seconds, and a large folder can take longer. Start the import anyway: the import itself allows 10 minutes to list the folder.

FTPS is not supported; use SFTP, or plain FTP if the other host offers it

The Host starts with ftps:// or ftpes://. We keep the prefix on purpose, because dropping it would send your password over plain FTP. Look in the other host's panel for its SFTP details, set Protocol to SFTP and enter the SFTP host and port. If the host offers only FTPS, ask it to switch on SFTP or plain FTP. If it does offer plain FTP, set Protocol to FTP and remove the ftps:// prefix from Host.

We could not check the import

The tab got a 401 or 403 while it read the import's status, because your sign-in ended or you lost access to the server. It stops reading and shows the reason with a Try again button. Sign in again if you need to, then select Try again. The import itself keeps running on our side.

We lost contact with the import.

The tab could not find the import's status 15 times in a row, so it shows the card as Failed with this sentence and stops reading. The import may still be running or may have ended. Reload the page: the tab shows the running import again, or the last one if it ended in the past 24 hours. Check the Files tab before you start another import.

You cannot import files here

Your account does not hold the Files permission on this server. Ask the owner to add it on the Users tab (Choose permissions).

The other host's key does not match the one you confirmed. Check that you are connecting to the right host.

The other host showed a key other than the one you checked, or other than the one the import saved at its start. We refuse before we send your password. At Start import the import does not begin. During a run it ends as Failed at once and does not try again. Files already copied stay on the server. Check the Host and Port. Then find out why the key changed. The other host may have moved to new hardware or made a new key, which its panel or support can confirm. Or someone may be in the way. Start a new import only after you checked: run Test connection, compare the new Host key with the one the other host lists, then start.

host_key_fingerprint is not a SHA256 fingerprint

A start through the API sent a host_key_fingerprint that is not SHA256: followed by 43 letters, digits, + or /. Send the fingerprint from the test answer as it is, or leave the field out. The dashboard does this for you.

Could not reach sftp.example.com:22: connection timed out

We could not open a connection. Check the address and port, and that the other host allows connections from outside.

The other host has no folder /minecraft. Check the remote folder.

The other host has no folder at the path in Remote folder. The import ends as Failed at once and does not try again, and Test connection shows the same sentence. Check the path in the other host's file manager, or enter / to copy everything the account can see. When the other host will not let the account list the folder, the sentence is The other host would not let us open the folder /minecraft. Check the remote folder., and when it fails the listing for another reason, We could not open the folder /minecraft on the other host. Check the remote folder.

The remote folder holds more than 250,000 files and folders; the importer copies at most that many. Import a sub-folder instead.

Import the folder in parts, one sub-folder at a time, with Remote folder set to each.

The remote folder holds … but this server has … of disk

The files do not fit. Import less, or move to a plan with more disk.

Cannot import while the server is installing

Wait until the installation finishes, then start the import. The same message names a server that is suspended or moving.

An import is already running on this server

The tab shows the running import. Wait for it to finish, or stop it first.

A file import is running on this server. Start it again when the import finishes.

You pressed Start or Restart, or asked for a wake, while an import was queued, copying or stopping. We refuse it until the import is Completed, Failed or Cancelled. To start the server sooner, stop the import (Stop an import). Stop and Kill work while an import runs.

The import stopped after 5 attempts. Last problem: …

The import could not reach the other host, or could not go on, and we tried again until we ran out of attempts. The sentence after Last problem: is the reason, such as The other host refused the connection. Check the host and port. or The other host took too long to list its files, so the import will try again. Fix what it names: the entries above cover the connection messages. For a host that takes too long to list its files, import one sub-folder at a time. Then start a new import. Files already copied stay on the server.

The server became suspended, so the import stopped.

We check the server every few seconds while the import runs. The import ends as Failed when the server is suspended, starts installing or is moved to another machine. The sentence names the state, such as The server became installing, so the import stopped., or says The server moved to another node, so the import stopped. Wait until the server is back to normal, check the Files tab, then start a new import.

Stopped after 200 files could not be copied

The other host refused to send many files. Read the reasons in the list, fix the file permissions on the other host, and import again.

The import ran longer than 6 hours, so we stopped it.

The import ran for more than 6 hours. Import the rest in parts, with Remote folder set to each sub-folder.

Type the server name to confirm a wipe and import

The start request asked for a wipe (truncate set to true) and did not carry this server's name, or carried a different one. We refuse it before anything is deleted or copied. In the dashboard, type the name in the dialog that Wipe and import… opens. Through the API, send the server's name as confirm_server_name, in any case. Clear Wipe this server first to import without a wipe.

Please try again in a moment.

The database stayed busy while we started or stopped the import, and we gave up after a few tries. Nothing changed: no import was created, and a stop was not applied. Send the same request again.

Too many requests for this action. Try again later.

You made more than 12 test or start requests for this server in 5 minutes. The limit counts per account and per server, and a test and a start share it. Wait a few minutes and try again. A start we refuse for a missing server name does not count towards it.

• Manage server files
• Connect to a server with SFTP to upload files yourself instead.
• Take a server snapshot before you import over files you want to keep.

The routes take the same body. type is sftp or ftp in any case, and any other value answers 422. remote_host is the address, remote_port defaults to 22 or 21 (a port written after the address in remote_host sets it when remote_port is empty), username and password are the other host's login, base_path is the remote folder (default /), truncate set to true wipes the server first, skip_existing set to true skips files that are already on the server, and host_key_fingerprint is the SFTP host key you confirmed. A wipe also needs confirm_server_name, up to 191 characters, on start: the server's name, compared without regard to case and with spaces at the start and end ignored. test-connection and a start without truncate ignore it, and so does a start on a server whose install never finished (status installing or install_failed). The wipe deletes what What the wipe keeps describes.

Test the connection with POST /api/v1/client/servers/{uuid}/import/test-connection:

curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/import/test-connection \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "sftp", "remote_host": "sftp.example.com", "remote_port": 2022, "username": "alex", "password": "old-host-password", "base_path": "/minecraft"}'

It answers {"success": true, "files": 1843, "directories": 212}, or success set to false with a message. Over SFTP a successful answer also holds the key the other host presented:

{
  "success": true,
  "files": 1843,
  "directories": 212,
  "host_key": {
    "algorithm": "ssh-ed25519",
    "fingerprint": "SHA256:0123456789abcdefghijklmnopqrstuvwxyzABCDEFG"
  }
}

host_key is not in the answer for FTP, or when the test fails. The test ignores truncate, skip_existing and host_key_fingerprint.

Send the same body to POST /api/v1/client/servers/{uuid}/import/start to start the import. It signs in to the other host first and answers 400 if that fails, so a wrong password never becomes a queued import.

To wipe the server first, send truncate and the server's name:

curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/import/start \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "sftp", "remote_host": "sftp.example.com", "remote_port": 2022, "username": "alex", "password": "old-host-password", "base_path": "/minecraft", "truncate": true, "confirm_server_name": "Survival SMP"}'

A missing or wrong name answers 400 with {"detail": "Type the server name to confirm a wipe and import"}. We check the name before the rate limit, so a refused request does not use up the limit below.

Compare host_key.fingerprint with the key the other host lists, then send it as host_key_fingerprint with start. The value is SHA256: followed by 43 base64 characters, as ssh-keygen -l prints it. Spaces around it are ignored, and letter case counts.

curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/import/start \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "sftp", "remote_host": "sftp.example.com", "remote_port": 2022, "username": "alex", "password": "old-host-password", "base_path": "/minecraft", "host_key_fingerprint": "SHA256:0123456789abcdefghijklmnopqrstuvwxyzABCDEFG"}'

• The start probe, and every connection the import opens after it, including each reconnect, must show exactly that key. We read the key on a connection that sends no username or password, so a host with another key never receives them.
• When the key differs, start answers 400 with {"detail": "The other host's key does not match the one you confirmed. Check that you are connecting to the right host."}. If the key changes during a run, the import ends at once as failed with the same sentence as the reason, and we do not try again.
• When start carries no host_key_fingerprint, we save the key the start probe saw and require it for the whole run, so it cannot change midway. You have then confirmed no key yourself.
• FTP has no host key, so a well formed fingerprint has no effect with ftp.
• A value that is not a SHA256: fingerprint answers 400 with {"detail": "host_key_fingerprint is not a SHA256 fingerprint"}. A value of more than 128 characters answers 422.

Send skip_existing set to true with start to leave out a file that is already on the server with the same size. The file counts as transferred in files_transferred and bytes_transferred. The comparison uses the size only, and a file whose size the other host does not report is always copied. skip_existing is ignored when truncate is true. It defaults to false.

The start route and the status routes return the import:

{
  "import_id": "0b7f9c1e-5d2a-4f61-9a43-2c8e7d10b6a5",
  "status": "in_progress",
  "files_transferred": 412,
  "total_files": 1843,
  "bytes_transferred": 734003200,
  "total_bytes": 2147483648,
  "current_file": "/minecraft/world/region/r.0.0.mca",
  "errors": [],
  "skipped": [{"file": "/minecraft/latest", "reason": "symbolic links are not copied"}],
  "cancel_requested": false,
  "truncate": false,
  "stopped_server": true
}

status is pending, in_progress, cancelling, completed, failed or cancelled. An import stays pending while it waits for a place, because many imports run on Coritan. errors lists the files that could not be copied, each as file and error, and a failed import adds one last entry with the reason, whose file is empty (or / when the wipe failed). skipped lists the entries we left out on purpose, each as file and reason: symbolic links (symbolic links are not copied), devices, sockets and pipes (devices, sockets and pipes are not copied) and, on a free server, a file named like the executable the panel installed (free servers keep the server executable the panel installed). They are not failures and never count towards the 200 failed files. skipped lists at most 200 entries, then one more with an empty file and the reason and N more entries. stopped_server is true when we stopped the server for the import.

Starting an import while one runs answers 409 with message, import_id and status of the running one. A start or a stop that meets a busy database after a few tries on our side answers 409 with message set to Please try again in a moment. and changes nothing, so send it again. Testing and starting share a limit of 12 requests in 5 minutes for each account and server (the container.import action), and a request over it answers 429 with Too many requests for this action. Try again later. in detail.message. Testing and reading need file.read, starting and stopping need file.create, and a start with truncate also needs file.delete.

While an import is pending, in_progress or cancelling, POST /api/v1/client/servers/{uuid}/power with start or restart, and POST /api/v1/client/servers/{uuid}/wake, answer 409 with {"detail": "A file import is running on this server. Start it again when the import finishes."}. stop and kill still work. The same holds for the organization portal's and the staff console's power and wake routes, and for a start from a schedule or a rule. A Discord command answers with the same sentence.