SSH Key Access and Management

SSH is an easy and secure way to remotely manage your site! This article contains all the necessary information to generate an SSH key, add an SSH key to Flywheel, and connect to SSH.

What is SSH?

SSH (secure shell) is a secure login to a system with a way of encrypting your network connection so that you can work securely and remotely from any device. SSH allows you to connect directly from your laptop or computer to a site on a remote server. When connected via SSH, you are able to interact with remote sites using command line tools, this gives you more control and access to manage your sites as compared to an SFTP connection.

Flywheel’s SSH gateway uses keys to authenticate your connection to the servers and give access to users. SSH keys come in pairs – a public key and a private key. The private key is kept on the machine you are authenticating from and the public key is added to Flywheel.

SSH is typically used to securely transfer files and manage sites remotely via terminal access. With Flywheel’s SSH gateway, you can securely and efficiently manage all your WordPress® sites using command line tools.¹

Once connected to a site, many tools and utilities are available to manage the site. Here are some of the most loved terminal tools that are installed by default:

• WP-CLI
• MySQL
• rsync
• Text editors like Vim, emacs, and nano
• Utilities like curl, wget, and zip

Checking for existing SSH keys

SSH keys are typically stored in the ~./ssh folder on your machine. To check if you already have an SSH key pair, you can look in that directory and see if there are any files by opening up a terminal and typing this command:

cd ~/.ssh; ls

If you see a pair of files named something like id_ed25519 and id_ed25519.pub (or id_rsa), then you already have a key pair and can continue on to adding and deleting keys on Flywheel. If there isn’t a key pair listed, you’ll need to generate one.

Generating new SSH keys on Mac/Linux

Follow these steps to generate a new SSH key pair:

1. Open up your terminal program of choice (like Terminal or iTerm for Mac).
2. Use the ssh-keygen command to generate a new pair:

   ssh-keygen -a 100 -t ed25519

   Note

   If creating SSH keys for use with GitHub Actions you will need to substitute rsa for ed25519 in order to convert to PEM format.

3. Press enter to accept the default location and file name, or enter your preferred location and name.
4. Enter a passphrase when prompted.
5. Voila! You’re ready to copy the public key and paste it into the Flywheel dashboard.

Generating new SSH keys on Windows

Windows users can generate SSH keys using PuTTYgen.

Although modern versions of Windows (such as Windows 10) support OpenSSH, not all of them do. Don’t worry, if you’re running an older version of Windows you can still connect to Flywheel’s SSH Gateway using PuTTY!

PuTTY is a free SSH access client, and PuTTYgen is its corresponding SSH key generation tool.

Install and launch PuTTY

If you haven’t yet, you’ll want to install PuTTY and PuTTYgen.

1. Start by going to putty.org and grab yourself a copy of PuTTY. The installation package includes both the PuTTY client as well as the PuTTYgen key generator.
2. Run the installer.
3. Via the Start Menu, open both PuTTY and PuTTYgen.

Generate SSH key pair in PuTTYgen

To connect to Flywheel’s SSH Gateway, you’ll need to install a public key on Flywheel and configure a private key in PuTTY. You can generate the keys you need in PuTTYgen.

1. Make sure the key type is RSA and the number of bits is 2048.
   
2. Click Generate. Moving your mouse randomly in the blank area will generate a private key and a public key pair.
   
3. Create a Key passphrase for the key pair. Take note of this password as you’ll use it to connect to the SSH portal itself.
   
4. Click Save private key to save the key to your computer. Keep this handy as you’ll need it later.
5. Copy the public key to your clipboard to paste into Flywheel. (Don’t use the Save public key button and copy the key from that file, it won’t work.)
   

Add the public key to Flywheel

Next, you’ll take the public key you copied to your clipboard and add it to your Flywheel account.

1. On the Flywheel app, navigate to the SSH tab of your Account.
2. Click Add SSH Key.
3. Give your public key a name.
   
4. Paste the public key you copied from PuTTYgen into the field. Make sure the key is an exact duplicate with no additional spaces or returns.
5. Click Add Key.

Configure and save the PuTTY session

Next, you’ll want to configure the gateway. We recommend saving the session for future use, so you don’t have to configure PuTTY again next time.

1. In the PuTTY sidebar, navigate to Session.
   
2. Type ssh.getflywheel.com in Host Name.
3. Set Port to 22.
4. Choose SSH for Connection type.
5. In the PuTTY sidebar, navigate to Connection > SSH > Auth.
6. Under Authentication parameters, click Browse and select the private key you generated earlier.
7. In the PuTTY sidebar, go back to Session. In the Saved Sessions area, click Save and name your session.

Connect to Flywheel’s SSH Gateway

If everything was set up correctly, you will now be able to connect to Flywheel’s SSH Gateway via PuTTY!

1. In the PuTTY sidebar, navigate to Session. Select your saved session and click Load.
2. Click Open. This will launch a terminal window.
3. At the login as: prompt, enter your Flywheel username.
4. Enter the password for your key pair. Remember, this is not your Flywheel user password, this is the password you created earlier in PuTTYgen.
5. You will now be connected to the Flywheel SSH gateway and presented with a list of sites!

Adding SSH keys to Flywheel

Once a key pair has been generated, it’s time to add the public key to the Flywheel dashboard!

1. First, you’ll need to copy the public key to your clipboard. We have used “id_ed25519” for the example here, please adjust it for your setup.
   On macOS:

   pbcopy ~/.ssh/id_ed25519.pub

   On Windows and Linux:

   cat ~/.ssh/id_ed25519.pub

   Copy the terminal output

2. Next, head over to the SSH page in the Flywheel dashboard and click the blue “plus” button on the top right of the SSH Keys card.
3. Enter a name for your key. A common convention is to use the name of the machine that the key exists on (for example, Trevan’s MacBook Pro)
4. Paste the key you copied in step 1 into the text field.
5. Click the green “Add Key” button.

You’re now ready to connect to your sites via SSH!

Connecting to the SSH gateway

Once your public key has been added, you can now connect to your sites via SSH!

1. Initiate the connection. Open up a terminal program of choice (like Terminal or iTerm for Mac, or PuTTY for Windows) and run the following command:

   ssh ssh.getflywheel.com

2. Confirm the fingerprint. If you’re connecting for the first time, you’ll likely see a message similar to this, asking you to verify the fingerprint:

   The authenticity of host 'ssh.getflywheel.com (11.111.111.11)' can't be established.
   RSA key fingerprint is SHA256:gGoHM/YYEKoCOrbrO/o0ZU1fndq8wz+KkkR8ePc8t5g.
   Are you sure you want to continue connecting (yes/no/[fingerprint])?

   Type yes to continue connecting.

3. Select a site to connect to. You should now see a welcome message and a list of all the sites you have access to:

   Welcome To The Flywheel SSH Service
   Select your destination...
   
    1 : Super Fly (flytrevan/super-fly)
    2 : High Flyers (jhobbs/high-flyers)
    3 : Rad Enough (flytrevan/rad-enough)
    4 : Bozingo's Gadgets (flytrevan/bozingos-gadgets)
    5 : Flyer's Club (atrabold/flyers-club)
    6 : Awesome Opposums (trevannonadmin/awesome-opposums)
    7 : Flippy's Martial Arts (trevsclient/flippys-martial-arts)
    8 : Trusty Robots (trevsclient/trusty-robots)
    9 : Full Plastic Jacket (flytrevan/full-plastic-jacket)
    10 : Tank's Mobile Service (trevsclient/tanks-mobile-service)
   
   flytrevan@flywheel

   Type the number next to the site you wish to view.

   You should now be connected to the site you selected!

Connecting directly to a site

The instructions above outline connecting to the SSH gateway and viewing a list of all sites that you can then connect to. You can also connect directly to a site using the following syntax:

ssh [email protected]

For example:

ssh [email protected]

Your username can be found on your profile page, and the site-slug can be found at the end of the URL (after the site owner’s username) when viewing a site in the Flywheel dashboard.

Connecting directly to a staging site

To connect to a staging site, the syntax is:

ssh [email protected]

For example:

ssh [email protected]

Connecting directly to an Organization owned site

To connect to a site owned by an Organization, the syntax is:

ssh [email protected]

For example:

ssh [email protected]

The Organization’s username can be found before the site slug in the URL when viewing the site in the Flywheel dashboard.

Connecting directly to a staging site of an Organization owned site

To connect to a staging site of an Organization owned site, the syntax is:

ssh [email protected]

For example:

ssh [email protected]

Trouble getting connected?

If you’re unable to connect, try specifying your identity file:

ssh -i /path/key-filename ssh.getflywheel.com

For example:

ssh -i ~/.ssh/id_ed25519 ssh.getflywheel.com

SSH restrictions

Here are a few notable items that aren’t currently available with Flywheel’s SSH gateway:

Viewing site logs

Viewing a history or real-time stream of site logs is not currently possible with Flywheel’s SSH gateway. Site logs can still be downloaded from a site’s Advanced page in the Flywheel dashboard though!

Persisting user-installed packages between sessions

Our SSH gateway utilizes temporary servers that are spun up when you connect to SSH and spun down when you disconnect. Due to this, if you install a terminal package it will only be persisted the next time you connect to SSH if it’s been less than 5 hours since the last time you disconnected. You can always reinstall the package though!

A subset of WP-CLI commands

There are a few WP-CLI commands that aren’t supported on Flywheel. More detailed information can be found in this article.

Editing wp-config.php and core files

Similar to our SFTP offering, core WordPress files (including wp-config.php) are not editable.

Need help?

If you have any questions about accessing your sites via SSH, please reach out to our friendly Happiness Engineers!