Set up FTP and SFTP access

Hyperion offers two ways to upload files to a hosting: FTP, with a password, and SFTP, with SSH keys only. Both are managed on the site’s FTP & SFTP tab. For quick edits the Files button in the site’s top bar opens a file browser instead.

Before you start

• Your account has the Edit hosting config permission for the site. Adding extra logins needs File manager.
• The site is active. A suspended site locks its FTP and SFTP logins.
• For FTP, vsftpd is installed on the node. Hyperion starts and configures it when you set a password.
• For clients over the internet, plan to use SFTP, or turn on FTPS (see below). Plain FTP sends the password unencrypted, and that password is the site’s real Linux password.

Steps

Set the FTP password

1. Open the site, then the FTP & SFTP tab.
2. In FTP access, enter a password in Set a password (at least 12 characters), or leave the field empty to generate a 20-character one. Click Set password. The label changes to Change the password once one exists.
3. Copy the Host, Username, Password and Port from the green box. The password is shown once.

The username is the site’s system user. The client lands directly in /home/<system-user>/<domain>/htdocs, the writable web root. The control port is 21 unless the node’s vsftpd is set otherwise; the self-check shows the real port. Passive data connections use ports 40000 to 50000, which vsftpd is pinned to. Keep them open in every firewall in front of the node; with FTPS on the kernel can no longer open them on demand.

To switch FTP off for the site, click Disable FTP for this site and confirm. The password is cleared and files are untouched.

Add separate logins

Use these for each person or deploy script, so one can be revoked without touching the others.

1. Open Extra FTP logins.
2. Enter Name (up to 16 characters: lowercase letters, digits, _ and -), optionally Lands in (a folder relative to the web root, blank for the web root) and Note.
3. Click Add login. A live preview shows the real login, which is <name>.<domain>, for example deploy.example.com. When the domain does not fit Linux’s 32-character login limit, the domain part is shortened and a 4-character tag is added to keep it unique.
4. Copy the generated password from the green box. It is shown once.

Each row has New password (the old one stops working at once) and Delete (removes the login; site files are untouched). These are separate logins, not separate permissions: each can read and write every file the site owns. Lands in only decides where the client starts.

Enable key-only SFTP

1. Open SFTP (SSH keys).
2. Tick Enable key-only SFTP for <system-user>.
3. Paste public keys into Authorized public keys, one per line (ssh-ed25519, ssh-rsa or ecdsa-…; contents of a .pub file). An invalid line rejects the whole save with an error.
4. Click Save changes.

Connect with sftp <system-user>@<domain> on port 22. SFTP has no password and no shell, and the session is chrooted to the site’s home. The session starts at the root of the chroot, which is the home directory. Run cd <domain>/htdocs (for example cd example.com/htdocs) to reach the web files. Enabling SFTP makes that home directory owned by root:root with mode 0755, which the chroot requires. Unticking the box leaves it that way. Hyperion adds the user to the hyperion-sftp group and uses an sshd drop-in at /etc/ssh/sshd_config.d/hyperion-sftp.conf, validated with sshd -t before each reload. Unticking the box removes the keys and the group membership.

Require FTPS (Owner or Administrator)

Before you require FTPS

Enable FTPS (required) encrypts every FTP session on the whole node and refuses plaintext logins. vsftpd restarts, so transfers in progress drop, and any client that cannot do FTPS, including your customers’, stops working. Passive ports 40000 to 50000 must be open in the firewall, or directory listings hang after login. If vsftpd fails to start, Hyperion restores the previous configuration.

No backup is involved; the change is the vsftpd configuration. To undo, click Disable FTPS (or run sudo hctl ftp ftps --off).

1. Open FTP self-check and click Enable FTPS (required).
2. Confirm Turn on and require TLS.

The certificate is the panel’s own when it has one; otherwise a self-signed one is made.

Run the self-check

FTP self-check reads the node’s state without changing anything. Rows cover vsftpd installed and running, its configuration, the control port, passive ports, FTPS, the site’s password state, where the login lands, the shell, ownership of the web root, parent directories and each extra login. The header reads all good, warnings or needs attention. Click Re-check after a fix.

• Fix this site points vsftpd at the real web root, gives the site user ownership of it and makes the parent directories traversable. No service restarts.
• Fix this node’s vsftpd (Owner or Administrator) rewrites /etc/vsftpd.conf, keeps a timestamped backup and your custom port, and restarts vsftpd for every site on the node.

A background check also repairs a stale landing directory, ownership and extra logins about every five minutes.

Check that it worked

The FTP access card shows the pill password set. The self-check shows all good. From your machine:

sftp <system-user>@example.com

Expected: an sftp> prompt after the key is accepted, and cd <domain>/htdocs followed by ls lists the web files. For FTP, log in with a client using the shown host, user and password; the first listing shows the contents of htdocs.

If it fails

• FTP: followed by a message, or FTP password must be at least 12 characters. Use a longer password.
• Login accepted but listings hang: passive ports 40000 to 50000 are blocked. Open them. The Passive data ports row says so.
• Uploads fail with 550: ownership. Click Fix this site, or Repair now under PHP settings & file repair on Settings & limits.
• The FTP password row says locked or empty: set the password again.
• invalid SSH key: … The pasted line is not a valid public key. Paste the .pub contents.
• Logins fail on a suspended site: resume the site.
• An extra login row shows “runs as uid … while the site is uid …”: the automatic repair fixes it within five minutes.

Related

• Manage a node’s firewall
• CLI reference