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 ParamikoSSHClient
instance, performing useful high level operations with thatSSHClient
andChannel
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).An alternate constructor exists for users upgrading piecemeal from Fabric 1:
from_v1
Methods like
run
,get
etc automatically trigger a call toopen
if the connection is not active; users may of course callopen
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
tolocal
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 toadmin@myhost
, one could:Use any built-in config mechanism, such as
/etc/fabric.yml
,~/.fabric.json
, collection-driven configuration, env vars, etc, statinguser: admin
(or{"user": "admin"}
, depending on config format.) ThenConnection('myhost')
would implicitly have auser
ofadmin
.Use an SSH config file containing
User admin
within any applicableHost
header (Host myhost
,Host *
, etc.) Again,Connection('myhost')
will default to anadmin
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/orport
parameters, of the formuser@host
,host:port
, oruser@host:port
.Note
Due to ambiguity, IPv6 host addresses are incompatible with the
host:port
shorthand (thoughuser@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 explicitport
parameter instead.Note
If
host
matches aHost
clause in loaded SSH config data, and thatHost
clause contains aHostname
directive, the resultingConnection
object will behave as ifhost
is equal to thatHostname
value.In all cases, the original value of
host
is preserved as theoriginal_host
attribute.Thus, given SSH config like so:
Host myalias Hostname realhostname
a call like
Connection(host='myalias')
will result in an object whosehost
attribute isrealhostname
, and whoseoriginal_host
attribute ismyalias
.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 aninvoke.config.Config
(which will be turned into aConfig
).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 aProxyJump
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, specifygateway=False
.)See also
forward_agent (bool) –
Whether to enable SSH agent forwarding.
Default:
config.forward_agent
.connect_timeout (int) –
Connection timeout, in seconds.
Default:
config.timeouts.connect
.connect_kwargs (dict) –
Keyword arguments handed verbatim to
SSHClient.connect
(whenopen
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 aspkey
orkey_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
; this is the default behavior), or submit them through the SSH protocol itself.In Fabric 2.x this defaulted to
False
(try using the protocol behavior), but in 3.x it changed toTrue
due to the simple fact that most remote servers are deployed with a restrictedAcceptEnv
setting, making use of the protocol approach non-viable.The actual default value is the value of the
inline_ssh_env
configuration value (which, as above, currently defaults toTrue
).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 builtinsorted
function to the env dictionary’s keys, to remove what would otherwise be ambiguous/arbitrary ordering.
- 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.Changed in version 3.0:
inline_ssh_env
still defaults to the config value, but said config value has now changed and defaults toTrue
, notFalse
.
- close()¶
Terminate the network connection to the remote end, if open.
If any SFTP sessions are open, they will also be closed.
If no connection or SFTP session is open, this method does nothing.
New in version 2.0.
Changed in version 3.0: Now closes SFTP sessions too (2.x required manually doing so).
- connect_kwargs = None¶
Keyword arguments given to
paramiko.client.SSHClient.connect
whenopen
is called.
- connect_timeout = None¶
Connection timeout
- forward_agent = None¶
Whether agent forwarding is enabled.
- 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’sssh
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 thisConnection
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’sssh
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, anyfabric.utils._AttributeDict
instance should work) to pull configuration from.
New in version 2.4.
- gateway = None¶
The gateway
Connection
orProxyCommand
string to be used, if any.
- 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.
- host = None¶
The hostname of the target server.
- inline_ssh_env¶
Whether to construct remote command lines with env vars prefixed inline.
- property 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
, ifgateway
was aConnection
; or aProxyCommand
, ifgateway
was a string.
New in version 2.0.
- port = None¶
The network port to connect on.
- 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 bychdir
) will be preserved.New in version 2.0.
- shell(**kwargs)¶
Run an interactive login shell on the remote end, as with
ssh
.This method is intended strictly for use cases where you can’t know what remote shell to invoke, or are connecting to a non-POSIX-server environment such as a network appliance or other custom SSH server. Nearly every other use case, including interactively-focused ones, will be better served by using
run
plus an explicit remote shell command (egbash
).shell
has the following differences in behavior fromrun
:It still returns a
Result
instance, but the object will have a less useful set of attributes than withrun
orlocal
:command
will beNone
, as there is no such input argument.stdout
will contain a full record of the session, including all interactive input, as that is echoed back to the user. This can be useful for logging but is much less so for doing programmatic things after the method returns.stderr
will always be empty (same asrun
whenpty==True
).pty
will always be True (because one was automatically used).exited
and similar attributes will only reflect the overall session, which may vary by shell or appliance but often has no useful relationship with the internally executed commands’ exit codes.
This method behaves as if
warn
is set toTrue
: even if the remote shell exits uncleanly, no exception will be raised.A pty is always allocated remotely, as with
pty=True
underrun
.The
inline_env
setting is ignored, as there is no default shell command to add the parameters to (and no guarantee the remote end even is a shell!)
It supports only the following kwargs, which behave identically to their counterparts in
run
unless otherwise stated:encoding
env
in_stream
(useful in niche cases, but make sure regularrun
with this argument isn’t more suitable!)replace_env
watchers
(note that due to pty echoing your stdin back to stdout, a watcher will see your input as well as program stdout!)
Those keyword arguments also honor the
run.*
configuration tree, as inrun
/sudo
.- Returns
- Raises
ThreadException
(if the background I/O threads encountered exceptions other thanWatcherError
).
New in version 2.7.
- ssh_config = None¶
The per-host SSH config data, if any. (See Loading and using ssh_config files.)
- 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 – likerun
– 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.
- transport = None¶
A convenience handle onto the return value of
self.client.get_transport()
.
- user = None¶
The username this connection will use to connect to the remote end.