SSH Keys

For security, every server connected to FlashPanel has SSH password login turned off. To log in to your server from your own computer (Terminal, PowerShell, PuTTY, Termius, WinSCP...), you need an SSH key.

Why does the Terminal button in FlashPanel still work?

The Terminal button on the server page uses FlashPanel's own connection, so it doesn't need your SSH key. Apps on your computer do. The password in the "installed successfully" email is the sudo password: you use it to run sudo commands after logging in, not to log in over SSH.

What is an SSH key?

An SSH key is a pair of keys used instead of a password. Think of it as a lock and its key:

• The public key is the lock: it is installed on the server. It is fine if others see it. It is one line of text starting with ssh-ed25519 ... or ssh-rsa ....
• The private key is the key: it stays on your computer and must never be shared. Anyone holding this file can log in to your server.

When you log in, the server checks whether the key on your computer opens the lock it has installed.

When FlashPanel creates a key for you, you get 3 files:

File	What it is	Use it with
No extension, e.g. flash_panel_an_gmail_com	Private key in OpenSSH format	The ssh command on macOS, Linux, Windows (PowerShell), Termius, Bitvise, VS Code
.ppk extension	Private key in PuTTY format	PuTTY, WinSCP, FileZilla
.pub extension	Public key	Pasting into servers or other services. Not used to log in

Both private key files are the same key in different formats. Use whichever your app needs.

Log in to your server in 3 steps

1. Have the private key on your computer. See Where to get an SSH key
2. The public key is on the server, for the user you want to log in as. See Put your SSH key on the server
3. Log in with the app you prefer. See Log in with your SSH key

Where to get an SSH key

Option 1: Use the key FlashPanel already created for you

When you create a server and your account has no global SSH key yet (usually your first server), FlashPanel creates an SSH key for you and sends the email "Your SSH Key has been generated at FlashPanel". The email has the 3 attachments listed above.

• This key is already installed on that server and every server you create later, for both root and flashpanel. Just download the attachments and log in.
• Each server's "installed successfully" email also lists the names and fingerprints of the keys installed on it, so you can check.
• Look for the email in your inbox, including Spam/Promotions. Searching for "SSH Key" helps.
• FlashPanel does not keep private keys. If you deleted the email, create a new key with Option 2.

Option 2: Create a new key in FlashPanel

The easiest way, on any operating system:

1. Open the SSH Keys page and click Add SSH Key.
2. In the dialog, click Generate SSH Key. FlashPanel fills in the Name and Public key.
3. Click the OpenSSH Key, PuTTY Key and Public Key buttons one by one to download the 3 files.
4. Click Add SSH Key to save.
5. A new key is only added automatically to servers you create later. For existing servers, click Update to servers on the new key's row, select the servers, and click Submit. See Global SSH Keys.

WARNING

The private key is issued only once. If you close the dialog without downloading it, you need to generate a new key.

Option 3: Create one on your computer

For people comfortable with the command line, or who want the key to be created and kept only on their own computer. See Create an SSH key on your computer at the end of this page.

Put your SSH key on the server

FlashPanel has two places to add SSH keys:

	Global SSH Keys	Server SSH Keys
Where	Account menu > SSH Keys	Inside a server: Security > SSH Keys
Applies to	Every new server you create, or servers you select with Update to servers	One server
Users that get it	root, flashpanel and the system users on the server	One user you choose
Use it for	Your own key, for all your servers	Giving someone else (a developer, a partner) access as a specific user

If you are not sure, use Global SSH Keys.

Which user should I log in as?

• flashpanel: the default user, recommended for daily use. It can use sudo with the sudo password from the "installed successfully" email.
• root: full control of the server. Use it only when you really need to.
• A website's system user: can only log in when Can Access SSH/SFTP is turned on for that user (see System Users) and it has your SSH key.

Log in with your SSH key

Have these 4 things ready. They are in the "installed successfully" email or on the server's Home page:

• The server's IP address, e.g. 203.0.113.5
• The SSH port, 22 by default
• The username, e.g. flashpanel
• The private key file you downloaded

The examples below use <key-file> for the name of your OpenSSH private key file (the one with no extension) and 203.0.113.5 for the IP. Replace them with your own.

macOS and Linux (Terminal)

1. Open Terminal. On macOS: press Cmd + Space, type Terminal, press Enter.

2. Create the .ssh folder (it does nothing if the folder already exists):

   mkdir -p ~/.ssh && chmod 700 ~/.ssh

3. Move the private key file from your Downloads folder into ~/.ssh:

   mv ~/Downloads/<key-file> ~/.ssh/

4. Make the file readable only by you. This is required: without it, ssh refuses to use the key:

   chmod 600 ~/.ssh/<key-file>

5. Log in:

   ssh -i ~/.ssh/<key-file> -p 22 [email protected]

6. The first time, you are asked Are you sure you want to continue connecting (yes/no/[fingerprint])?. Type yes and press Enter.

Steps 1 to 4 are one-time setup. Next time, just run the command in step 5.

Shorter commands: give your server a nickname

Open (or create) the file ~/.ssh/config and add:

Host my-server
    HostName 203.0.113.5
    User flashpanel
    Port 22
    IdentityFile ~/.ssh/<key-file>

From now on, just type ssh my-server.

Windows (PowerShell)

Windows 10 (version 1809 or later) and Windows 11 include the ssh command.

1. Press the Windows key, type PowerShell, press Enter.

2. Create the .ssh folder in your user folder:

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.ssh"

3. Move the private key file from Downloads into .ssh:

   Move-Item "$env:USERPROFILE\Downloads\<key-file>" "$env:USERPROFILE\.ssh\"

4. Log in:

   ssh -i "$env:USERPROFILE\.ssh\<key-file>" -p 22 [email protected]

5. The first time, type yes and press Enter.

Windows hides file extensions

The OpenSSH private key file has no extension, so Windows shows its type as File. If your browser saved it as <key-file>.txt, use that exact name in the command or rename it to remove .txt. Don't open and re-save the file in Notepad, as that can break its format.

PuTTY (Windows)

PuTTY uses the .ppk file.

1. Open PuTTY. Under Session, enter the server IP in Host Name and the SSH port in Port.
2. In the left menu, open Connection > Data and enter flashpanel in Auto-login username.
3. Open Connection > SSH > Auth > Credentials. Next to Private key file for authentication, click Browse and pick the .ppk file.
4. Go back to Session, type a name in Saved Sessions and click Save so you don't have to fill this in again.
5. Click Open. The first time, choose Accept.

Other apps

• Termius, Bitvise, MobaXterm, VS Code Remote-SSH: choose private key login (Key, Public key, Identity file) and pick the OpenSSH file (no extension). Some older Bitvise and MobaXterm versions need the .ppk file.
• WinSCP, FileZilla (file transfer over SFTP): use the .ppk file. See SFTP.

Common errors

Permission denied (publickey)

The server did not accept the key you offered. Check, in order:

1. Are you using the right private key file? It must be the file with no extension (ssh command) or the .ppk file (PuTTY), not the .pub file. With the ssh command you need -i <path-to-file>; without it, ssh only tries default files such as ~/.ssh/id_ed25519.
2. Is the key on the server? Open the server > Security > SSH Keys and look for your key under the right user. If it is missing, add it as described in Put your SSH key on the server.
3. Is the username right? Log in as the user the key was added for.
4. Does the user have SSH access? For a website's system user, check that Can Access SSH/SFTP is on in System Users.
5. Are you logging in with a password? Passwords don't work because SSH password login is turned off. If you really need it, you can turn it back on in SSH configuration, but this is not recommended.

WARNING: UNPROTECTED PRIVATE KEY FILE! or bad permissions

The private key file is readable by too many users, so ssh refuses to use it.

• macOS, Linux: run chmod 600 ~/.ssh/<key-file>.

• Windows (PowerShell): limit read access to your own account:

  icacls "$env:USERPROFILE\.ssh\<key-file>" /inheritance:r /grant:r "$($env:USERNAME):R"

Load key ...: invalid format

The file is not a valid OpenSSH private key. Usually you picked the .pub or .ppk file by mistake, or the file was changed by opening it in Notepad. Download the original file from the email again.

PuTTY says Unable to use key file or OpenSSH SSH-2 private key

You picked the OpenSSH file in PuTTY. Pick the .ppk file instead. If you only have the OpenSSH file, open PuTTYgen, click Load to pick the file, then click Save private key to save it as .ppk.

Connection timed out or Connection refused

Your computer cannot reach the SSH port. This happens before the key is even checked.

• Check the IP and SSH port (if you changed the port in SSH configuration, use the new port with -p).
• Check that the VPS provider's firewall and the server firewall allow the SSH port.
• Too many failed logins can get your IP temporarily blocked by Fail2Ban. Open the sshd jail on the Fail2Ban page to unban your IP.

WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!

This usually happens when the server's operating system was reinstalled but kept the same IP. If you are sure you just reinstalled the server, remove the old entry and connect again:

ssh-keygen -R 203.0.113.5

Create an SSH key on your computer

The commands below create a key and save it straight into ~/.ssh. After creating it, copy the public key and add it to FlashPanel as described in Put your SSH key on the server.

Windows

Using PowerShell (OpenSSH format)

If ssh-keygen is not found, open Settings > System > Optional features (Windows 10: Settings > Apps > Optional features), click Add a feature (or View features), find OpenSSH Client, and click Install.

1. Open PowerShell and run:

   ssh-keygen -t ed25519

   Press Enter to save in the default location. You can enter a passphrase to protect the private key, or press Enter to skip.

2. The command creates the private key id_ed25519 and the public key id_ed25519.pub in C:\Users\<your-name>\.ssh\. Show the public key to copy it:

   Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub"

Using PuTTYgen (PuTTY .ppk format)

1. Install PuTTY and open PuTTYgen.
2. Under Type of key to generate, choose EdDSA (Ed25519) or RSA (2048 bits or more).
3. Click Generate and move the mouse randomly over the blank area of the window until it finishes.
4. (Optional) Enter a password for the private key in Key passphrase and Confirm passphrase.
5. Click Save private key to save the .ppk file.
6. Copy the entire content of the Public key for pasting into OpenSSH authorized_keys file box (starting with ssh-ed25519 or ssh-rsa). This is the public key to add to FlashPanel.

If you also need the private key in OpenSSH format, choose Conversions > Export OpenSSH key.

macOS

1. Open Terminal and run:

   ssh-keygen -t ed25519

   Press Enter to save in the default location (~/.ssh/id_ed25519), then enter a passphrase or press Enter to skip.

2. Copy the public key to the clipboard:

   pbcopy < ~/.ssh/id_ed25519.pub

If you need the private key in PuTTY (.ppk) format, install puttygen with Homebrew and convert it:

brew install putty
puttygen ~/.ssh/id_ed25519 -o ~/.ssh/id_ed25519.ppk

Linux

1. Open a terminal and run (if ssh-keygen is missing, install it with sudo apt install openssh-client):

   ssh-keygen -t ed25519

   Press Enter to save in the default location (~/.ssh/id_ed25519), then enter a passphrase or press Enter to skip.

2. Show the public key to copy it:

   cat ~/.ssh/id_ed25519.pub

If you need the private key in PuTTY (.ppk) format:

sudo apt install putty-tools
puttygen ~/.ssh/id_ed25519 -o ~/.ssh/id_ed25519.ppk

A key created with ssh-keygen is already at ~/.ssh/id_ed25519, so you can leave out -i when logging in: ssh [email protected].

About key types

• Ed25519 is short, fast, and secure, and is recommended in most cases.

• If your software does not support Ed25519, generate an RSA key:

  ssh-keygen -t rsa -b 4096 -m PEM

• If older software (old PuTTY or WinSCP versions) cannot open the .ppk file, convert with PPK version 2: add --ppk-param version=2 to the puttygen command, or in PuTTYgen choose Key > Parameters for saving key files... > PPK file version = 2 before saving.

Server SSH Key

Unlike your own SSH key, each server also has its own SSH key pair, created by FlashPanel during setup. This key is not for you to log in to the server. The server uses it to pull code from private Git repositories (GitHub, GitLab, Bitbucket...), for example when deploying a website.

To add the server's public key to your Git account:

1. Open the server's Home page and, in the Utilities group, click Add Server SSH Key.
2. Select the connected Git accounts and click Submit.
3. For providers that don't support adding keys automatically, click the copy button for Server Global SSH Key and add it yourself on the provider's SSH key page shown in the hint.