fabric.connection.Connection

Undocumented

Undocumented

Undocumented

Undocumented

Set up a new object representing a server connection. :param str host: 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``. :param str user: the login user for the remote connection. Defaults to ``config.user``. :param int port: the remote port. Defaults to ``config.port``. :param 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. :param 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``.) .. seealso:: :ref:`ssh-gateways` :param bool forward_agent: Whether to enable SSH agent forwarding. Default: ``config.forward_agent``. :param int connect_timeout: Connection timeout, in seconds. Default: ``config.timeouts.connect``. :param dict connect_kwargs: .. _connect_kwargs-arg: Keyword arguments handed verbatim to `SSHClient.connect <paramiko.client.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``. :param bool inline_ssh_env: 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 to ``True`` due to the simple fact that most remote servers are deployed with a restricted ``AcceptEnv`` setting, making use of the protocol approach non-viable. The actual default value is the value of the ``inline_ssh_env`` :ref:`configuration value <default-values>` (which, as above, currently defaults to ``True``). .. 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`_). .. _refuse the temptation to guess: http://zen-of-python.info/ in-the-face-of-ambiguity-refuse-the-temptation-to-guess.html#12 .. versionchanged:: 2.3 Added the ``inline_ssh_env`` parameter. .. versionchanged:: 3.0 ``inline_ssh_env`` still defaults to the config value, but said config value has now changed and defaults to ``True``, not ``False``.

Undocumented

Undocumented

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. .. versionadded:: 2.0 .. versionchanged:: 3.0 Now closes SFTP sessions too (2.x required manually doing so).

Undocumented

Undocumented

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. :param int local_port: The local port number on which to listen. :param int remote_port: The remote port number. Defaults to the same value as ``local_port``. :param str local_host: The local hostname/interface on which to listen. Default: ``localhost``. :param str remote_host: 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. .. versionadded:: 2.0

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. :param int remote_port: The remote port number on which to listen. :param int local_port: The local port number. Defaults to the same value as ``remote_port``. :param str local_host: The local hostname/interface the forwarded connection talks to. Default: ``localhost``. :param str remote_host: 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. .. versionadded:: 2.0

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. .. versionadded:: 2.0

Undocumented

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. .. versionadded:: 2.0

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 :ref:`SSH config options <ssh-config>`) are utilized here in the call to `SSHClient.connect <paramiko.client.SSHClient.connect>`. (For details, see :doc:`the configuration docs </concepts/configuration>`.) .. versionadded:: 2.0

Obtain a socket-like object from `gateway`. :returns: A ``direct-tcpip`` `paramiko.channel.Channel`, if `gateway` was a `.Connection`; or a `~paramiko.proxy.ProxyCommand`, if `gateway` was a string. .. versionadded:: 2.0

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. .. versionadded:: 2.0

Undocumented

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`. .. versionadded:: 2.0

Return a `~paramiko.sftp_client.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 `~paramiko.sftp_client.SFTPClient.chdir`) will be preserved. .. versionadded:: 2.0

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 (eg ``bash``). `shell` has the following differences in behavior from `run`: - It still returns a `~invoke.runners.Result` instance, but the object will have a less useful set of attributes than with `run` or `local`: - ``command`` will be ``None``, 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 as `run` when ``pty==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 to ``True``: even if the remote shell exits uncleanly, no exception will be raised. - A pty is always allocated remotely, as with ``pty=True`` under `run`. - 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 regular `run` 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 in `run`/`sudo`. :returns: `~invoke.runners.Result` :raises: `~invoke.exceptions.ThreadException` (if the background I/O threads encountered exceptions other than `~invoke.exceptions.WatcherError`). .. versionadded:: 2.7

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. .. versionadded:: 2.0