Getting Started¶
Installing sshreader¶
The easiest way to get working with sshreader is to use pip
to install the module. You can do that by running
the following in your terminal
pip install sshreader
Note
If you already have sshreader installed and would like to update to the latest release, run the following:
pip install --upgrade sshreader
Congratulations! You are now ready to begin working with sshreader!
Working With SSH Objects¶
To start working with ssh connections (without multiprocessing or threading) right away simply import the SSH class and setup a connection!
from sshreader import SSH
with SSH('myhost.example.com', username='jdoe', password='jdoe1') as s:
uname = s.ssh_command('uname -a')
print(uname) # Show the results of the command, including stdin, stdout, and stderr
Note
By using the with
statement you do not have to worry about running SSH.close()
when you are finished with
an ssh connection.
Working With ServerJob Objects¶
ServerJob objects are a way to run multiple commands via ssh and return/tabulate the results. ServerJobs can be placed
into a list and then processed using multiprocessing and multithreading via the sshread
method.
To create a ServerJob object and run it is nearly as simple as working with SSH objects:
from sshreader import ServerJob, sshread
job = ServerJob('myhost.example.com',['uname -a', 'hostname', 'whoami'] username='jdoe', password='jdoe1')
r = sshread(job, tcount=0)
print(r.status, r.results)
What happens here is that you create a ServerJob object that will run three commands in succession and record the results
in itself. When you call sshread
you actually connect to the server and run the commands.
Working With multiple ServerJobs¶
To sshread multiple ServerJob objects at the same time simply create a list of them and feed that list to the sshread
method. The sshread
method will return a list of the completed ServerJob objects for you to then parse
as needed.
from sshreader import ServerJob, sshread
jobs = list()
for host in ['myhost1.example.com', 'myhost2.example.com', 'myhost3.example.com']:
job = ServerJob(host,['uname -a', 'hostname', 'whoami'] username='jdoe', password='jdoe1')
jobs.append(job)
finished = sshread(jobs, tcount=0)
for job in finished:
print(job.status, job.results)
Now you are ready to sshread all your servers as fast as possible!
Working With Hooks¶
Sometimes you want to run bits of code before or after a ServerJob executes as part of the sshread
method.
Sshreader provides a way to do this through Hook
objects. Hook objects are simply a wrapper for a function you
have defined that will run before or after a ServerJob executes. They will contain the ServerJob object itself as one of
the arguments so it is easy to write a Hook that can look at or react to the status of the ServerJob.
Creating a Hook is as is as simple as:
from sshreader import ServerJob, sshread, Hook
def print_name(job):
# You will need to ensure you accept at least one arg since
# the ServerJob will be passed to your hook
print('Entering hook')
print(job.name)
print('Leaving hook')
# Create the function as a hook object
myhook = Hook(target=print_name)
# Create a ServerJob with a prehook
job = ServerJob('myhost.example.com',['uname -a', 'hostname', 'whoami'], username='jdoe', password='jdoe1',
prehook=myhook)
# Now, run the job
sshread(job, tcount=1)
Note
By default the pre/post Hooks run before the ssh connection is established and after it is closed. If you would like
the hook to run after the ssh connection is established or before it closes set the ssh_established
flag to
True
when creating the Hook. This gives you ability to use the existing SSH connection within a job instead
of creating a new one within the Hook itself.
Running Shell Commands¶
Sometimes you don’t want to run commands via ssh but want to run them in the shell on the localhost. Sshreader provides
a method for doing that as well via the shell_command
method.
from sshreader import shell_command
r = shell_command('uname -a')
print(r)
Discovering Environment Variables¶
Sshreader includes a method that attempts to determine the currently logged in username and any ssh keys located in
~/.ssh/
, including rsa and dsa keys. You can see what sshreader can discover by calling the envvars
method from the ssh module.
from sshreader.ssh import envvars
print(envvars()) # Returns a NamedTuple of info sshreader was able to gather from the OS
Copying Files¶
Version 3.4 of sshreader introduced the sftp_put()
and sfpt_get()
methods into SSH objects. These
methods attempt to make it easier to use OpenSSH’s SFTP protocol to copy files to and from a remote server. The cool thing
about having them inside the SSH class is that you can use one object to both SFTP files and run SSH commands on a remote server.
from sshreader.ssh import SSH
with SSH('myhost.example.com', username='jdoe', password='jdoe1') as s:
# Copy a script file from our host to the remote host and run it.
s.sftp_put('~/secret_script.sh', '/tmp/secret_script.sh')
s.ssh_command('/tmp/secret_script.sh')
# Now, get the output of the script and remove all traces of it
s.sftp_get('/tmp/secret_output.txt', '~/secret_output.txt')
s.ssh_command('rm /tmp/secret_output.txt', 'rm /tmp/secret_output.sh')
Warning
SFTP methods are new to sshreader and isn’t a primary feature. Support for this feature will be limited.