Development Environment

Using Public Key Authentication for SSH and SFTP

light fare


I'll be describing how to set up public key authentication for SSH and SFTP for remotes sites on the MODX Cloud, but the same things apply to any remote server.

First, you need to generate your public/private key pairs. The private key stays ...well, private... on your computer. Never share your private key anywhere or with anyone. The public key is what goes to the remote server. On login, that public key is compared to your private key, and some exotic mathematical computations decide if that really is the correct private key, and the remote server allows the login.

Generate Your Public/Private Key Pairs

Create your own public/private key pair on your computer according to your platform.

On OSX or Linux

  • Open a Terminal (I use the iTerm app for my Mac)
  • Type
    ssh-keygen -t rsa -C "your@email.addr"
    and hit 'enter'.
  • Hit 'enter' to use the default location (~.ssh/)
  • Type a passphrase when asked, or leave empty and just hit 'enter'.

This will create two keys in your ~.ssh directory, the private key id_rsa and the public key

Private/Public Keys

If you gave a passphrase, you'll need to use it every time you log in using the public key authentication.


On Windows

Windows does not come with a key generator utility. Use the PuTTY SSH client or install git or openSSH for Windows or some other program that includes a key generator utility.

Using Your Public Key

To use the public key, on the remote host look for the .ssh folder and in that folder look for the authorized_keys file.

Find the .ssh/authorized_keys File

Copy the entire contents of your own file and paste it into the remote server's authorized_keys file. If you need to add more authorized keys, for example if different people will be logging in from different computers, make sure to leave an empty line between them.

Example Public Key

(yes, it is perfectly safe to display my public key; since nobody else has my private key, nobody can do anything with it)

Configuring An SFTP Client

Fill out the fields for a new connection, being sure to specify port 22, the well-known SFTP port. Some remote servers may be configured to use other ports, you'll have to find out what they use.

Here's an example of using the Cyberduck client. There are versions for both Mac and Windows. Basically, all you need is the remote server and port, your username, then the location of your private key.

 Cyberduck SFTP Setup

SSH On the Command Line

SSH login is used to log in to the remote server as if you were actually sitting in front of it. Since SFTP is a feature of SSH, logging in uses the same information. This example is logging in to a MODX Cloud instance, you can get the server and other login information from the instance's Dashboard.

  ssh username@servername-or-IP-address -p port-number

You need to feed the ssh command with your username, the @ symbol, then the server name or its IP address. If the server is not using the well-known port 22, you need to add the -p portnumber parameter. If it is using port 22, you don't need the -p parameter.

SSH Command-line Login

One excellent reason for using an SSH login is to fetch large files, including entire site backups, directly from a third server to your remote server without having to go through your local computer. The speed is awesome!

You can create a public/private key pair for your remote server from its command line, then use that to log in to a third sever to use the scp (secure copy) command to upload and download directly between the servers.