Cloud providers have made a killing from neatly-packaged managed services for years. Whether it be databases or message brokers, developers like ourselves don’t seem to have a problem paying a bit extra to have things taken care of. But wait, aren’t we typically the last people to opt for less optimization and less control? Why is this the time we decide otherwise? If I had to make a guess, I’d wager it’s partly because server-side DevOps kind of sucks.
As a developer, configuring or debugging a VPS is usually work which is unaccounted for, and it isn’t particularly rewarding. At best, your application will probably end up running the same as your local environment. How could we make this inevitable part of our jobs better? Well, we could automate it.
Paramiko and SCP are two Python libraries we can use together to automate tasks we’d want to run on a remote host such as restarting services, making updates, or grabbing log files. We’re going to take a look at what scripting with these libraries looks like. Fair warning: there’s a sizable amount of code in this tutorial, which tends to make me excited enough to coerce others into my manic code-tutorial episodes. If you start to feel lost, the full repo can be found here:
Source code for the accompanying tutorial found here: https://hackersandslackers.com/ssh-scp-in-python-with-paramiko/
Getting Started
Installation
$ git clone https://github.com/hackersandslackers/paramiko-tutorial.git
$ cd paramiko-tutorial
$ make install
$ make run
Configuration
Replace the values in .env.example with your values and rename this file to .env:
ENVIRONMENT
: Contextual environment the script is being on.SSH_REMOTE_HOST
: IP address (or URL) of remote host to SSH into.SSH_USERNAME
: Username for connecting to remote host.SSH_PASSWORD
(optional): Password of user SSHing into remote host via basic auth.SSH_KEY_FILEPATH
: /path/to/local/sshkeySCP_DESTINATION_FOLDER
(optional): Remote directory to serve as destination for file uploads.
Remember to never commit secrets saved in .env files to Github.
Hackers and Slackers tutorials are free of charge. If you found this tutorial helpful, a small donation would be greatly appreciated to keep us in business. All proceeds go towards coffee, and all coffee goes towards…
Paramiko leans heavily on the “in-the-weeds” side of Python libraries. If you’re looking for something easy that can just get the job done, pyinfra is supposedly a great (and easy) alternative.
Setting up SSH Keys
To authenticate an SSH connection, we need to set up a private RSA SSH key. We can generate a key using the following command:
This will prompt us to provide a name for our key. Name it whatever you like:
Next, you’ll be prompted to provide a password (recommended, but up to you). This will result in the creation of two keys: a private key (which I’ll refer to as sshkey
) and a public key which takes the naming scheme of sshkey.pub
:
>> Enter passphrase (empty for no passphrase):
>> Enter same passphrase again:
>> Your identification has been saved in /Users/username/.ssh/sshkey
>> Your public key has been saved in /Users/username/.ssh/sshkey.pub
>> The key fingerprint is:
SHA256:UFYfdydftf6764576787648574 user@My-MacBook-Pro.local
>> The key's randomart image is:
+---[RSA 3072]----+
|o*-HHFTEf. |
|++o=++.+E. |
|OoO + .. |
|.= + o |
|+ . o . S |
|.. o o . |
|o .+ O . |
|.+ |
|..o. |
+----[SHA256]-----+
Consider the private key to be sacred; this key and everything about it should remain on your machine (the example I posted above is fake). The corresponding public key is what we put on remote hosts in our possession to authenticate a connection.
The easiest way to do this is by using ssh-copy-id
, which is a command that exists for this exact purpose:
In the above example, ~/.ssh/mykey
is the file path of the public key we created. user@example.com
should of course be replaced with the address of your remote host, where user
is the username of the preferred user to connect with.
Verifying our SSH Key
It’s always best to check our work. Go ahead and SSH into your remote host; if you didn’t set a password when creating your key, you may be surprised to find that you’re no longer prompted for a password. That’s a good sign.
Check your host’s .ssh
directory for the public key we created:
We’re looking for keys that begin with the following header:
Feel free to do the same on your VPS.
Starting our Script
Let’s install our libraries. Fire up whichever virtual environment you prefer and let em rip:
Just one more thing before we write some meaningful Python code! Create a config file to hold the variables we’ll need to connect to our host. Here are the barebones of what we need to get into our server:
- Host: The IP address or URL of the remote host we’re trying to access.
- Username: This is the username you use to SSH into your server.
- Passphrase (optional): If you specified a passphrase when you created your ssh key, specify that here. Remember that your SSH key passphrase is not the same as your user’s password.
- SSH Key: The file path of the key we created earlier. On OSX, these live in your system’s ~/.ssh folder. SSH key we’re targeting must have an accompanying key with a .pub file extension. This is our public key; if you were following along earlier, this should have already been generated for you.
If you’re trying to upload or download files from your remote host, you’ll need to include two more variables:
- Remote Path: The path to the remote directory we’re looking to target for file transfers. We can either upload things to this folder or download the contents of it.
- Local Path: Same idea as above, but the reverse. For our convenience, the local path we’ll be using is simply /data, and contains pictures of cute fox gifs.
Now we have everything we need to make a respectable config.py file:
Creating an SSH Client
We’re going to create a class called RemoteClient
to handle the interactions we’ll be having with our remote host. Before we get too fancy, let’s just start things off by instantiating the RemoteClient
class with the variables we created in config.py :
You’ll notice I added a few things to our constructor, besides the config values we pass in:
self.client
: self.client will ultimately serve as the connection objection in our class, similar to how you have dealt with terminology likeconn
in database libraries. Our connection will beNone
until we explicitly connect to our remote host.self._upload_ssh_key()
isn’t a variable, but rather a function to be run automatically whenever our client is instantiated. Calling_upload_ssh_key()
is telling ourRemoteClient
object to check for local ssh keys immediately upon creation so that we can try to pass them to our remote host. Otherwise, we wouldn’t be able to establish a connection at all.
Uploading SSH Keys to a Remote Host
We’ve reached the section of this exercise where we need to knock out some devastatingly inglorious boilerplate code. This is typically where emotionally inferior individuals succumb to the sheer dull obscurity of understanding SSH keys and maintaining connections. Make no mistake: authenticating and managing connections to anything programmatically is overwhelmingly dull… unless your tour guide happens to be an enchanting wordsmith, serving as your loving protector through perilous obscurity. Some people call this post a tutorial. I intend to call it art.
RemoteClient
will start with two private methods: _get_ssh_key()
and _upload_ssh_key()
. The former will fetch a locally stored public key, and if successful, the latter will deliver this public key to our remote host as an olive branch of access. Once a locally created public key exists on a remote machine, that machine will then forever trust us with our requests to connect to it: no passwords required. We’ll be including proper logging along the way, just in case we run into any trouble:
_get_ssh_key()
is quite simple: it verifies that an SSH key exists at the path we specified in our config to be used for connecting to our host. If the file does in fact exist, we happily set our self.ssh_key
variable, so this key can be uploaded and used by our client from here forward. Paramiko provides us with a submodule called RSAKey
to easily handle all things RSA key related, like parsing a private key file into a usable connection authentication. That’s what we get here:
If our RSA key were incomprehensible nonsense instead of a real key, Paramiko’s SSHException
would have caught this and raised an exception early on explaining just that. Properly utilizing a library’s error handling takes a lot of the guesswork out of “what went wrong,” especially in cases like where there’s potential for numerous unknowns in a niche space neither of us mess with often.
_upload_ssh_key()
is where we get to jam our SSH key down the throat of our remote server while shouting, “LOOK! YOU CAN TRUST ME FOREVER NOW!” To accomplish this, I go a bit “old school” by passing bash commands via Python’s os.system
. Unless somebody makes me aware of a cleaner approach in the comments, I’ll assume this is the most badass way to handle passing keys to a remote server.
The standard non-Python way of passing keys to a host looks like this:
This is precisely what we accomplish in our function in Python, which looks like this:
system(
f"ssh-copy-id -i {self.ssh_key_filepath} \
{self.user}@{self.host}>/dev/null 2>&1"
)
I suppose you won’t let me slip that /dev/null 2>&1
bit by you? Fine. If you must know, here’s some guy on StackOverflow explaining it better than I can:
>
is for redirect/dev/null
is a black hole where any data sent, will be discarded.2
is the file descriptor for Standard Error.>
is for redirect.&
is the symbol for file descriptor (without it, the following1
would be considered a filename).1
is the file descriptor for Standard O.
So we’re basically telling our remote server we’re giving it something, and it’s all like “where do I put this thing,” to which we reply “nowhere in physical in space, as this is not an object, but rather an eternal symbol of our friendship. Our remote host is then flooded with gratitude and emotion, because yes, computers do have emotions, but we can’t be bothered by that right now.
Connecting to our Client
We’ll add a method to our client called connect()
to handle connecting to our host:
Let’s break this down:
client = SSHClient()
sets the stage for creating an object representing our SSH client. The following lines will configure this object to make it more useful.load_system_host_keys()
instructs our client to look for all the hosts we’ve connected to in the past by looking at our system’s known_hostsfile and finding the SSH keys our host is expecting. We’ve never connected to our host in the past, so we need to specify our SSH key explicitly.set_missing_host_key_policy()
tells Paramiko what to do in the event of an unknown key pair. This is expecting a “policy” built-in to Paramiko, to which we’re going to specificAutoAddPolicy()
. Setting our policy to “auto-add” means that if we attempt to connect to an unrecognized host, Paramiko will automatically add the missing key locally.connect()
is SSHClient‘s most important method (as you might imagine). We’re finally able to pass our host , user , and SSH key to achieve what we’ve all been waiting for: a glorious SSH connection into our server! Theconnect()
method allows for a ton of flexibility via a vast array of optional keyword arguments too. I happen to pass a few here: setting look_for_keys toTrue
gives Paramiko permission to look around in our ~/.ssh folder to discover SSH keys on its own, and setting timeout will automatically close connections we’ll probably forget to close. We could even pass variables for things like port and password , if we had elected to connect to our host this way.
Disconnecting
We should close connections to our remote host whenever we’re done using them. Failing to do so might not necessarily be disastrous, but I’ve had a few instances where enough hanging connections would eventually max out inbound traffic on port 22. Regardless of whether your use case might consider a reboot to be a disaster or mild inconvenience, let’s just close our damn connections like adults as though we were wiping our butts after pooping. No matter your connection hygiene, I advocate for setting a timeoutvariable (as we saw earlier). Anyway. voila:
Fun fact: setting self.client.close()
actually sets self.client
to equal None
, which is useful in cases where you might want to check if a connection is already open.
Executing Unix Commands
We now have a wonderful Python class that can find RSA keys, connect, and disconnect. It does lack the ability to do, well, anything useful.
We can fix this and finally begin doing “stuff” with a brand new method to execute commands, which I’ll aptly dub execute_commands()
(that’s correct, “commands” as in potentially-more-than-one, we’ll touch on that in a moment). The legwork of all this is done by the Paramiko client’s built-in exec_command()
method, which accepts a single string as a command and executes it:
The function we just created execute_commands()
expects a list of strings to execute as commands. That’s partially for convenience, but it’s also because Paramiko won’t run any “state” changes (like changing directories) between commands, so each command we pass to Paramiko should assume we’re working out of our server’s root. I took the liberty of passing three such commands like so:
I can view the contents of a directory by chaining cd path/to/dir && ls
, but running cd path/to/dir
followed by ls
would result in nothingness because ls
the second time returns the list of files in our server’s root.
You’ll notice client.exec_command(cmd)
returns three values as opposed to one: this can be useful to see which input produced which output. For example, here are the full logs for the example I provided where I passed three commands to remote.execute_commands()
:
Some beautiful stuff here. Now you can see which sites are on my server, which bots are spamming me, and how many node processes I’m running.
I don’t want to waste much more time on the art of executing commands, but it’s worth mentioning the presence of why we call stdout.channel.recv_exit_status()
after each command. Waiting for recv_exit_status()
to come back after running client.exec_command()
forces our commands to be run synchronously, otherwise there’s a likely chance our remote machine won’t be about to decipher commands as fast as we pass them along.
Uploading (and Downloading) Files via SCP
SCP refers to both the protocol for copying files to remote machines (secure copy protocol) as well as the Python library, which utilizes this. We’ve already installed the SCP library, so import that shit.
The SCP and Paramiko libraries complement one another to make uploading via SCP super easy. SCPClient()
creates an object which expects “transport” from Paramiko, which we provide with self.conn.get_transport()
. Creating an SCP connection piggybacks off of our SSH client in terms of syntax, but these connections are separate. It’s possible to close an SSH connection and leave an SCP connection open, so don’t do that. Open an SCP connection like this:
Uploading a single file is boring, so let’s upload an entire directory of files instead. bulk_upload()
accepts a list of file paths:
Our method is expecting to receive a list of strings, each representing the local path to a file, we’d like to upload.
SCP’s put()
method will upload any number of files to a remote host. This will replace existing files with the same name if they happen to exist at the destination we specify. That’s all it takes!
Downloading Files
The counterpart to SCP’s put()
is the get()
method:
Our Big Beautiful Script
We now have a sick Python class to handle SSH and SCP with a remote host… let’s put it to work! The following snippet is a quick way to test what we’ve built so far. In short, this script looks for a local folder filled with files (in my case, I filled the folder with fox gifs 🦊).
Check out how easy it is to create a main.py that handles complex tasks on remote machines thanks to our RemoteClient
class:
Here’s the output of the our upload function:
It worked! Don’t believe me? Why don’t we check for ourselves by running remote.execute_commands(['cd /var/www/ && ls'])
?
There you have it. Straight from the fox’s mouth.
Take It And Run With It
This is where I’d like to take a moment to thank all of you, and apologize that you’re still here. I swore an oath to myself to stop posting tutorials over two thousand words long, and this one is looking to push five thousand words of nonsense. I’ll work on that. New year, new me.
For your convenience, I’ve uploaded the source for this tutorial to Github. Feel free to take this and run with it! To close things out, I’ll leave you with the meat and potatoes of the RemoteClient
class we put together:
The full source code for this tutorial can be found here:
Source code for the accompanying tutorial found here: https://hackersandslackers.com/ssh-scp-in-python-with-paramiko/
Getting Started
Installation
$ git clone https://github.com/hackersandslackers/paramiko-tutorial.git
$ cd paramiko-tutorial
$ make install
$ make run
Configuration
Replace the values in .env.example with your values and rename this file to .env:
ENVIRONMENT
: Contextual environment the script is being on.SSH_REMOTE_HOST
: IP address (or URL) of remote host to SSH into.SSH_USERNAME
: Username for connecting to remote host.SSH_PASSWORD
(optional): Password of user SSHing into remote host via basic auth.SSH_KEY_FILEPATH
: /path/to/local/sshkeySCP_DESTINATION_FOLDER
(optional): Remote directory to serve as destination for file uploads.
Remember to never commit secrets saved in .env files to Github.
Hackers and Slackers tutorials are free of charge. If you found this tutorial helpful, a small donation would be greatly appreciated to keep us in business. All proceeds go towards coffee, and all coffee goes towards…