Network

Classes and subroutines dealing with network connections and related topics.

fabric.network.disconnect_all()

Disconnect from all currently connected servers.

Used at the end of fab’s main loop, and also intended for use by library users.

class fabric.network.HostConnectionCache

Dict subclass allowing for caching of host connections/clients.

This subclass will intelligently create new client connections when keys are requested, or return previously created connections instead.

It also handles creating new socket-like objects when required to implement gateway connections and ProxyCommand, and handing them to the inner connection methods.

Key values are the same as host specifiers throughout Fabric: optional username + @, mandatory hostname, optional : + port number. Examples:

• example.com - typical Internet host address.
• firewall - atypical, but still legal, local host address.
• user@example.com - with specific username attached.
• bob@smith.org:222 - with specific nonstandard port attached.

When the username is not given, env.user is used. env.user defaults to the currently running user at startup but may be overwritten by user code or by specifying a command-line flag.

Note that differing explicit usernames for the same hostname will result in multiple client connections being made. For example, specifying user1@example.com will create a connection to example.com, logged in as user1; later specifying user2@example.com will create a new, 2nd connection as user2.

The same applies to ports: specifying two different ports will result in two different connections to the same host being made. If no port is given, 22 is assumed, so example.com is equivalent to example.com:22.

__contains__(key)

True if the dictionary has the specified key, else False.

__delitem__(key)

Delete self[key].

__getitem__(key)

Autoconnect + return connection object

__setitem__(key, value)

Set self[key] to value.

__weakref__

list of weak references to the object (if defined)

connect(key)

Force a new connection to key host string.

fabric.network.connect(user, host, port, cache, seek_gateway=True)

Create and return a new SSHClient instance connected to given host.

Parameters:

• user – Username to connect as.
• host – Network hostname.
• port – SSH daemon port.
• cache – A HostConnectionCache instance used to cache/store gateway hosts when gatewaying is enabled.
• seek_gateway – Whether to try setting up a gateway socket for this connection. Used so the actual gateway connection can prevent recursion.

fabric.network.denormalize(host_string)

Strips out default values for the given host string.

If the user part is the default user, it is removed; if the port is port 22, it also is removed.

fabric.network.disconnect_all()

Disconnect from all currently connected servers.

Used at the end of fab’s main loop, and also intended for use by library users.

fabric.network.get_gateway(host, port, cache, replace=False)

Create and return a gateway socket, if one is needed.

This function checks env for gateway or proxy-command settings and returns the necessary socket-like object for use by a final host connection.

Parameters:

• host – Hostname of target server.
• port – Port to connect to on target server.
• cache – A HostConnectionCache object, in which gateway SSHClient objects are to be retrieved/cached.
• replace – Whether to forcibly replace a cached gateway client object.

Returns:

A socket.socket-like object, or None if none was created.

fabric.network.join_host_strings(user, host, port=None)

Turns user/host/port strings into user@host:port combined string.

This function is not responsible for handling missing user/port strings; for that, see the normalize function.

If host looks like IPv6 address, it will be enclosed in square brackets

If port is omitted, the returned string will be of the form user@host.

fabric.network.key_filenames()

Returns list of SSH key filenames for the current env.host_string.

Takes into account ssh_config and env.key_filename, including normalization to a list. Also performs os.path.expanduser expansion on any key filenames.

fabric.network.key_from_env(passphrase=None)

Returns a paramiko-ready key from a text string of a private key

fabric.network.needs_host(func)

Prompt user for value of env.host_string when env.host_string is empty.

This decorator is basically a safety net for silly users who forgot to specify the host/host list in one way or another. It should be used to wrap operations which require a network connection.

Due to how we execute commands per-host in main(), it’s not possible to specify multiple hosts at this point in time, so only a single host will be prompted for.

Because this decorator sets env.host_string, it will prompt once (and only once) per command. As main() clears env.host_string between commands, this decorator will also end up prompting the user once per command (in the case where multiple commands have no hosts set, of course.)

fabric.network.normalize(host_string, omit_port=False)

Normalizes a given host string, returning explicit host, user, port.

If omit_port is given and is True, only the host and user are returned.

This function will process SSH config files if Fabric is configured to do so, and will use them to fill in some default values or swap in hostname aliases.

Regarding SSH port used:

• Ports explicitly given within host strings always win, no matter what.
• When the host string lacks a port, SSH-config driven port configurations are used next.
• When the SSH config doesn’t specify a port (at all - including a default Host * block), Fabric’s internal setting env.port is consulted.
• If env.port is empty, env.default_port is checked (which should always be, as one would expect, port 22).

fabric.network.normalize_to_string(host_string)

normalize() returns a tuple; this returns another valid host string.

fabric.network.prompt_for_password(prompt=None, no_colon=False, stream=None)

Prompts for and returns a new password if required; otherwise, returns None.

A trailing colon is appended unless no_colon is True.

If the user supplies an empty password, the user will be re-prompted until they enter a non-empty password.

prompt_for_password autogenerates the user prompt based on the current host being connected to. To override this, specify a string value for prompt.

stream is the stream the prompt will be printed to; if not given, defaults to sys.stderr.

fabric.network.ssh_config(host_string=None)

Return ssh configuration dict for current env.host_string host value.

Memoizes the loaded SSH config file, but not the specific per-host results.

This function performs the necessary “is SSH config enabled?” checks and will simply return an empty dict if not. If SSH config is enabled and the value of env.ssh_config_path is not a valid file, it will abort.

May give an explicit host string as host_string.