SFTP and the file manager: moving files to your server

Every server here has a full file manager in the browser and SFTP credentials for the tools you already use. They are two doors onto the same filesystem, and choosing between them is about the size of the edit rather than preference: one value in a config file is a file manager job, a plugin folder with four hundred files is an SFTP job, and doing it the other way round is how people lose an afternoon.

What actually causes trouble is not the choice. It is the handful of things that behave differently on a server than on your own machine: files the running process is holding open, the executable bit that a browser upload cannot set, Windows line endings in a shell script, and a thousand small files crawling over a protocol that opens a new request for each one. This post covers both tools properly, then those traps in the order you will meet them.

Two doors onto one filesystem#

There is no separate "upload area". The file manager and SFTP write to the same directory that your server process reads from, at the same moment. A file that appears in one appears in the other on the next refresh, permissions and all.

That has a consequence worth stating plainly before anything else: there is no staging step and no undo. Deleting a world folder in the file manager deletes it. Overwriting server.properties over SFTP overwrites it. The only thing standing between a slip and a rebuild is a backup you took first, which is why the sequence for anything structural is always backup, stop, change, start - in that order, every time. Backups that actually restore is the argument for why the first step is not optional.

The file manager, for edits you can see#

The browser file manager is a real editor, not a viewer. It has syntax highlighting for the formats you will meet on a server, it saves in place, and it previews PDFs and images so you can confirm a map render or a server icon actually arrived rather than guessing from a file size.

What it is genuinely better at:

• Single-value edits. Changing view-distance or a port number. There is no download step, no re-upload step, and no chance of uploading yesterday's copy of the file over today's.
• Looking at something. Opening latest.log to check a stack trace, confirming a config file is valid after an install, seeing whether the plugins folder contains what you think it contains.
• Dropping files in. Drag-and-drop works for files and for whole folders, which covers the "one jar" case perfectly well.
• Archives. Upload a .zip or a .tar.gz and unpack it in place. This is the single most useful feature it has, and the reason is in the section on slow transfers below.

Where it stops being the right tool is anything with structure. A browser uploading four hundred small files is doing four hundred separate things, and the progress bar will tell you that in its own time. There is also no shell behind it, so you cannot run unzip, chmod or find - the unpack-in-place button exists precisely because the shell does not.

SFTP, for anything structural#

SFTP is the same filesystem over a protocol your existing tools speak. Reach for it when:

• You are uploading a plugin folder, a mod pack, a world, or anything else counted in hundreds of files.
• You want a copy of the whole server on your own disk, which is the only kind of copy you control completely.
• You are working from an editor that is already open. Most editors have a remote-filesystem extension, and editing a file on the server directly beats the download-edit-upload loop.
• You want the transfer scripted, because you are going to do it again next week.

Credentials are issued per server rather than per account. That is the point rather than an inconvenience: handing someone SFTP access to a shared server gives them that server and nothing else, and it can be taken away without touching anything you own elsewhere.

The connection details are shown on the server's settings in the panel: a host, a port that is not 22, and a username. The port is worth noticing because a great many firewall rules and corporate networks allow 22 and nothing else, and the first symptom is a client that hangs rather than one that refuses.

Connecting, and scripting it#

Any SFTP client works. FileZilla, WinSCP and Cyberduck cover the graphical case; sftp on the command line is installed on every Linux and macOS machine and on Windows with OpenSSH.

# Interactive, with the port from the panel$ sftp -P 2022 username@node.example.comsftp> cd pluginssftp> put -r ./build/EssentialsX.jarsftp> get latest.logsftp> bye

For anything repeated, drive it from a script. sftp -b reads a batch file, and lftp can mirror a whole directory in parallel, which is the closest thing to rsync that works here:

# Push a local plugins folder up, four transfers at a time$ lftp -u "$SFTP_USER,$SFTP_PASS" sftp://node.example.com:2022 \    -e "mirror -R --parallel=4 --delete ./plugins /plugins; quit"

Two important limits on what the command line can do:

`rsync` does not work. It needs to run a copy of itself on the far end over an SSH shell, and a panel's SFTP is a file-transfer service with no shell attached. There is nothing to fix; use lftp mirror instead, which does the same directory-comparison job over SFTP.

`scp` is version-dependent. Recent OpenSSH releases transfer with scp over the SFTP protocol rather than the old remote-exec path, so it may work; older ones will fail the same way rsync does. sftp and lftp always work, so use them in scripts and save yourself the debugging.

Files the server is holding open#

This is the one that costs people worlds and databases.

A running server does not read its data files continuously from disk. It loads what it needs, holds the current state in memory, and writes it back on a save interval or at shutdown. If you upload a new world while the server is running, you have replaced a file whose contents the server is no longer reading - and at the next save it will write its in-memory version straight over the top of what you just uploaded. The upload succeeded, the file was correct for four minutes, and then it was gone.

The rule: stop the server before touching anything it owns. That means worlds and saves, SQLite or level databases, player data, and in most games the config files as well, because they are read once at start. Then:

1. Take a backup. It is one button and it is the only version of the previous state you will have.
2. Stop the server and wait for the console to confirm it has actually stopped, not just that you pressed the button. A clean stop is what triggers the final save.
3. Upload or edit.
4. Start, and watch the console for the load line that names what it loaded.

Reading is safe while the server runs. Opening latest.log in the file manager, downloading a copy of a config to look at, checking that a mod jar is the right size - none of that interferes. Reading the console covers what to look for in the start-up output when a file you changed did not take effect, and the world-move procedure in the Valheim dedicated server guide is the same dance in a specific game.

Permissions, line endings and archives#

Three mechanical problems that look like bugs and are not.

The executable bit. A .sh script uploaded through a browser arrives without the execute permission, and the server reports permission denied when it tries to run it. Graphical SFTP clients can fix this: FileZilla has File permissions on the right-click menu, WinSCP has Properties. Set the file to 0755. If your client cannot set permissions, chmod from the sftp prompt works:

sftp> chmod 755 start.shsftp> ls -l start.sh-rwxr-xr-x    1 container container      412 Sep 21 09:14 start.sh

Windows line endings. A file edited in Notepad and uploaded keeps its carriage returns, and a shell script with them fails with a message that has confused people for thirty years:

bash: ./start.sh: /bin/bash^M: bad interpreter: No such file or directory

The ^M is the carriage return. Fix it by telling your editor to save with LF line endings - VS Code shows CRLF or LF in the status bar and switching is one click - or by editing the file in the panel's file manager, which writes LF. The same problem breaks YAML configs in subtler ways, so it is worth setting the editor default once.

Archives. Uploading one 200 MB archive and unpacking it in place is dramatically faster than uploading 4,000 files, because the slow part of a small-file transfer is the round trip per file, not the bytes. A modpack that takes forty minutes file-by-file takes two minutes as a zip. Two things to remember: you need room for both the archive and its contents, so check your plan's disk figure first, and delete the archive afterwards. Modded Minecraft without the crashes leans on this for every pack install.

Who else can reach these files#

Filesystem access is complete access. Anyone who can read the files can read your .env, your database credentials and your player data; anyone who can write them can replace the jar that runs at start-up. Treat it accordingly.

• Give file access through subusers, not by sharing credentials. Roles are granular here, so "files only, no console, no billing" is a real permission set, and it can be time-boxed. Subusers and least privilege has the model.
• There is a per-server activity log. If you are ever unsure who deleted something, look before you guess.
• SFTP credentials are per server. Handing them over is scoped to that one server, and revoking them does not disturb anything else you run.
• Put 2FA on the account that owns all of this. An authenticator code is the difference between a leaked password being an inconvenience and being an incident. See two-factor on your panel account.
• Check what you upload. A jar from a forum post has filesystem access the moment the server starts it, and that is the whole attack. Keeping a modded server clean is about exactly this habit.

When a transfer fails or crawls#

It is slow and there are thousands of files. Archive it, upload the archive, unpack in place. Or raise the client's concurrent transfers to four - FileZilla defaults to two, and most clients cap at about ten for good reason. Going higher usually gets connections refused rather than making anything faster.

The client connects and then hangs at "listing directory". Almost always passive-mode or firewall interference on a corporate or hotel network. Test from a phone hotspot; if it works there, it is the network, not the server.

Transfers stop partway through, repeatedly. Check the disk figure on the panel first. A full disk produces truncated files and confusing errors rather than a clear "out of space", and it is the most common cause of a mysterious half-uploaded world.

A file uploaded but the server ignores it. Three candidates: the server was running and overwrote it, the file is in the wrong directory (mods and plugins folders are game-specific and unforgiving), or the name is wrong. Case matters on Linux - Plugins is not plugins - and Windows hides known extensions, so config.yml.txt is a classic.

You cannot see the file you uploaded. It starts with a dot. .env, .htaccess and .git are hidden by default in most clients; FileZilla has "Force showing hidden files" under Server, and the panel's file manager lists them.

Everything broke after you edited a config. Restore the .bak copy you made, or restore the backup. Then change one thing at a time. A YAML file with one wrong indent fails as completely as one with fifty, and the error rarely names the line you touched - what to do when a mod update breaks is the general method for bisecting this kind of thing.

FAQ#

Can I use rsync with a hosting panel?

No. rsync runs a copy of itself on the remote side through an SSH shell, and a panel's SFTP service does not provide one. Use lftp mirror, which compares directories and transfers only what differs over plain SFTP, or use your graphical client's synchronise feature. sftp -b with a batch file covers scripted uploads.

What is the SFTP password?

Whatever the panel shows for that server. Credentials are issued per server rather than per account, so the details on one server do not work on another, and sharing them grants access to that server alone. If you have handed them out and want them back, change them in the panel rather than hoping.

Do I have to stop the server to upload files?

For anything the server has open - worlds, saves, databases, player data, and usually configs - yes, because the running process holds state in memory and writes it back over your upload at the next save. Reading files, downloading copies and checking logs are safe at any time. Uploading a plugin jar to a stopped server and starting it is also the only way to be sure the plugin was present at load.

Why does my shell script say "bad interpreter"?

The file has Windows line endings, so the interpreter path on the first line ends with an invisible carriage return. Save the file with LF endings from your editor, or edit it in the panel's file manager, which writes LF. The same fault can break configuration files without any error message at all.

Is the file manager as capable as SFTP?

For editing, reading and dropping a handful of files in, yes, and it is faster because there is no client to configure. For bulk transfers, for anything you want scripted, and for pulling a full copy of the server down to your own disk, SFTP is the tool. Most people end up using both daily without thinking about it.

How do I get a copy of my whole server locally?

Connect over SFTP and download the root directory, or run lftp with mirror in the download direction. On a large game server that is tens of gigabytes and will take a while, so it is worth doing once as an archive rather than nightly. For routine protection, use the backup slots that come with the plan - they are stored off the machine they protect, which a copy on the same disk is not.