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 toexample.com
, logged in asuser1
; later specifyinguser2@example.com
will create a new, 2nd connection asuser2
.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 toexample.com:22
.-
__getitem__
(key)¶ Autoconnect + return connection object
-
__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 gatewaySSHClient
objects are to be retrieved/cached. - replace – Whether to forcibly replace a cached gateway client object.
Returns: A
socket.socket
-like object, orNone
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 bracketsIf
port
is omitted, the returned string will be of the formuser@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
whenenv.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. Asmain()
clearsenv.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 settingenv.port
is consulted. - If
env.port
is empty,env.default_port
is checked (which should always be, as one would expect, port22
).
-
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 forprompt
.stream
is the stream the prompt will be printed to; if not given, defaults tosys.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
.