A connection to an SSH daemon, with methods for commands and file transfer.

Basics

This class inherits from Invoke’s Context, as it is a
context within which commands, tasks etc can operate. It also encapsulates
a Paramiko SSHClient instance, performing useful high
level operations with that SSHClient and
Channel instances generated from it.

Instantiation imprints the object with its connection
parameters (but does not actually initiate the network connection).

Methods like run, get etc automatically trigger a call to
open if the connection is not active; users may of course call open
manually if desired.

Connections do not always need to be explicitly closed; much of the
time, Paramiko’s garbage collection hooks or Python’s own shutdown
sequence will take care of things. However, should you encounter edge
cases (for example, sessions hanging on exit) it’s helpful to explicitly
close connections when you’re done with them.

This can be accomplished by manually calling close, or by using the
object as a contextmanager:

Use any built-in config mechanism, such as /etc/fabric.yml,
~/.fabric.json, collection-driven configuration, env vars, etc,
stating user:admin (or {"user":"admin"}, depending on config
format.) Then Connection('myhost') would implicitly have a user
of admin.

Use an SSH config file containing Useradmin within any applicable
Host header (Hostmyhost, Host*, etc.) Again,
Connection('myhost') will default to an admin user.

May include shorthand for the user and/or port parameters,
of the form user@host, host:port, or user@host:port.

Note

Due to ambiguity, IPv6 host addresses are incompatible with the
host:port shorthand (though user@host will still work
OK). In other words, the presence of >1 : character will
prevent any attempt to derive a shorthand port number; use the
explicit port parameter instead.

Note

If host matches a Host clause in loaded SSH config
data, and that Host clause contains a Hostname
directive, the resulting Connection object will behave as if
host is equal to that Hostname value.

In all cases, the original value of host is preserved as
the original_host attribute.

Thus, given SSH config like so:

HostmyaliasHostnamerealhostname

a call like Connection(host='myalias') will result in an
object whose host attribute is realhostname, and whose
original_host attribute is myalias.

user (str) – the login user for the remote connection. Defaults to
config.user.

Connection tries not to grow additional settings/kwargs of its
own unless it is adding value of some kind; thus,
connect_kwargs is currently the right place to hand in
parameters such as pkey or key_filename.

For example, say you want to connect to a remote PostgreSQL database
which is locked down and only accessible via the system it’s running
on. You have SSH access to this server, so you can temporarily make
port 5432 on your local system act like port 5432 on the server:

importpsycopg2fromfabricimportConnectionwithConnection('my-db-server').forward_local(5432):db=psycopg2.connect(host='localhost',port=5432,database='mydb')# Do things with 'db' here

This method is analogous to using the -L option of OpenSSH’s
ssh program.

For example, say you’re running a daemon in development mode on your
workstation at port 8080, and want to funnel traffic to it from a
production or staging environment.

In most situations this isn’t possible as your office/home network
probably blocks inbound traffic. But you have SSH access to this
server, so you can temporarily make port 8080 on that server act like
port 8080 on your workstation:

fromfabricimportConnectionc=Connection('my-remote-server')withc.forward_remote(8080):c.run("remote-data-writer --port 8080")# Assuming remote-data-writer runs until interrupted, this will# stay open until you Ctrl-C...

This method is analogous to using the -R option of OpenSSH’s
ssh program.

This method is identical to invoke.context.Context.sudo in every way,
except in that – like run – it honors per-host/per-connection
configuration overrides in addition to the generic/global ones. Thus,
for example, per-host sudo passwords may be configured.