connection

class fabric.connection.Connection(host, user=None, port=None, config=None, gateway=None, forward_agent=None, connect_timeout=None, connect_kwargs=None, inline_ssh_env=None)

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.

Note

Many SSH specific options – such as specifying private keys and passphrases, timeouts, disabling SSH agents, etc – are handled directly by Paramiko and should be specified via the connect_kwargs argument of the constructor.

Lifecycle

Connection has a basic “create, connect/open, do work, disconnect/close” lifecycle:

  • 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.

  • It’s best to explicitly close your connections when done using them. This can be accomplished by manually calling close, or by using the object as a contextmanager:

    with Connection('host') as c:
   c.run('command')
   c.put('file')

    Warning

    While Fabric (and Paramiko) attempt to register connections for automatic garbage collection, it’s not currently safe to rely on that feature, as it can lead to end-of-process hangs and similar behavior.

Note

This class rebinds invoke.context.Context.run to local so both remote and local command execution can coexist.

Configuration

Most Connection parameters honor Invoke-style configuration as well as any applicable SSH config file directives. For example, to end up with a connection to admin@myhost, one could:

  • 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 User admin within any applicable Host header (Host myhost, Host *, etc.) Again, Connection('myhost') will default to an admin user.
  • Leverage host-parameter shorthand (described in Config.__init__), i.e. Connection('admin@myhost').
  • Give the parameter directly: Connection('myhost', user='admin').

The same applies to agent forwarding, gateways, and so forth.

New in version 2.0.

__init__(host, user=None, port=None, config=None, gateway=None, forward_agent=None, connect_timeout=None, connect_kwargs=None, inline_ssh_env=None)

Set up a new object representing a server connection.

Parameters:
  • host (str) –

    the hostname (or IP address) of this connection.

    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:

    Host myalias
    Hostname realhostname

    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.
  • port (int) – the remote port. Defaults to config.port.
  • config –

    configuration settings to use when executing methods on this Connection (e.g. default SSH port and so forth).

    Should be a Config or an invoke.config.Config (which will be turned into a Config).

    Default is an anonymous Config object.

  • gateway –

    An object to use as a proxy or gateway for this connection.

    This parameter accepts one of the following:

    • another Connection (for a ProxyJump style gateway);
    • a shell command string (for a ProxyCommand style style gateway).

    Default: None, meaning no gatewaying will occur (unless otherwise configured; if one wants to override a configured gateway at runtime, specify gateway=False.)

    See also

    SSH connection gateways

  • forward_agent (bool) –

    Whether to enable SSH agent forwarding.

    Default: config.forward_agent.

  • connect_timeout (int) –

    Connection timeout, in seconds.

    Default: config.timeouts.connect.
Parameters:
  • connect_kwargs (dict) –

    Keyword arguments handed verbatim to SSHClient.connect (when open is called).

    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 paramiko connection parameters such as pkey or key_filename. For example:

    c = Connection(
    host="hostname",
    user="admin",
    connect_kwargs={
        "key_filename": "/home/myuser/.ssh/private.key",
    },
)

    Default: config.connect_kwargs.

  • inline_ssh_env (bool) –

    Whether to send environment variables “inline” as prefixes in front of command strings (export VARNAME=value && mycommand here), instead of trying to submit them through the SSH protocol itself (which is the default behavior). This is necessary if the remote server has a restricted AcceptEnv setting (which is the common default).

    The default value is the value of the inline_ssh_env configuration value (which itself defaults to False).

    Warning

    This functionality does not currently perform any shell escaping on your behalf! Be careful when using nontrivial values, and note that you can put in your own quoting, backslashing etc if desired.

    Consider using a different approach (such as actual remote shell scripts) if you run into too many issues here.

    Note

    When serializing into prefixed FOO=bar format, we apply the builtin sorted function to the env dictionary’s keys, to remove what would otherwise be ambiguous/arbitrary ordering.

    Note

    This setting has no bearing on local shell commands; it only affects remote commands, and thus, methods like run and sudo.
Raises:

ValueError – if user or port values are given via both host shorthand and their own arguments. (We refuse the temptation to guess).

Changed in version 2.3: Added the inline_ssh_env parameter.

close()

Terminate the network connection to the remote end, if open.

If no connection is open, this method does nothing.

New in version 2.0.

forward_local(local_port, remote_port=None, remote_host='localhost', local_host='localhost')

Open a tunnel connecting local_port to the server’s environment.

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:

import psycopg2
from fabric import Connection

with Connection('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.

Parameters:
  • local_port (int) – The local port number on which to listen.
  • remote_port (int) – The remote port number. Defaults to the same value as local_port.
  • local_host (str) – The local hostname/interface on which to listen. Default: localhost.
  • remote_host (str) – The remote hostname serving the forwarded remote port. Default: localhost (i.e., the host this Connection is connected to.)
Returns:

Nothing; this method is only useful as a context manager affecting local operating system state.

New in version 2.0.

forward_remote(remote_port, local_port=None, remote_host='127.0.0.1', local_host='localhost')

Open a tunnel connecting remote_port to the local environment.

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:

from fabric import Connection

c = Connection('my-remote-server')
with c.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.

Parameters:
  • remote_port (int) – The remote port number on which to listen.
  • local_port (int) – The local port number. Defaults to the same value as remote_port.
  • local_host (str) – The local hostname/interface the forwarded connection talks to. Default: localhost.
  • remote_host (str) – The remote interface address to listen on when forwarding connections. Default: 127.0.0.1 (i.e. only listen on the remote localhost).
Returns:

Nothing; this method is only useful as a context manager affecting local operating system state.

New in version 2.0.

classmethod from_v1(env, **kwargs)

Alternate constructor which uses Fabric 1’s env dict for settings.

All keyword arguments besides env are passed unmolested into the primary constructor.

Warning

Because your own config overrides will win over data from env, make sure you only set values you intend to change from your v1 environment!

For details on exactly which env vars are imported and what they become in the new API, please see Mapping of v1 env vars to modern API members.

Parameters:env – An explicit Fabric 1 env dict (technically, any fabric.utils._AttributeDict instance should work) to pull configuration from.

New in version 2.4.

get(*args, **kwargs)

Get a remote file to the local filesystem or file-like object.

Simply a wrapper for Transfer.get. Please see its documentation for all details.

New in version 2.0.

is_connected

Whether or not this connection is actually open.

New in version 2.0.

local(*args, **kwargs)

Execute a shell command on the local system.

This method is effectively a wrapper of invoke.run; see its docs for details and call signature.

New in version 2.0.

open()

Initiate an SSH connection to the host/port this object is bound to.

This may include activating the configured gateway connection, if one is set.

Also saves a handle to the now-set Transport object for easier access.

Various connect-time settings (and/or their corresponding SSH config options) are utilized here in the call to SSHClient.connect. (For details, see the configuration docs.)

New in version 2.0.

open_gateway()

Obtain a socket-like object from gateway.

Returns:A direct-tcpip paramiko.channel.Channel, if gateway was a Connection; or a ProxyCommand, if gateway was a string.

New in version 2.0.

put(*args, **kwargs)

Put a local file (or file-like object) to the remote filesystem.

Simply a wrapper for Transfer.put. Please see its documentation for all details.

New in version 2.0.

run(command, **kwargs)

Execute a shell command on the remote end of this connection.

This method wraps an SSH-capable implementation of invoke.runners.Runner.run; see its documentation for details.

Warning

There are a few spots where Fabric departs from Invoke’s default settings/behaviors; they are documented under Config.global_defaults.

New in version 2.0.

sftp()

Return a SFTPClient object.

If called more than one time, memoizes the first result; thus, any given Connection instance will only ever have a single SFTP client, and state (such as that managed by chdir) will be preserved.

New in version 2.0.

sudo(command, **kwargs)

Execute a shell command, via sudo, on the remote end.

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.

New in version 2.0.