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 id_rsa.pub
If you gave a passphrase, you'll need to use it every time you log in using the public key authentication.
NEVER SHARE YOUR PRIVATE KEY WITH ANYONE ANYWHERE. ALWAYS SHARE THE PUBLIC KEY.
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.
Copy the entire contents of your own id_rsa.pub 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.
(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.
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.
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.