Configuration¶
Paramiko does not itself leverage OpenSSH-style config file directives, but it does implement a parser for the format, which users can honor themselves (and is used by higher-level libraries, such as Fabric).
The API for this is SSHConfig
, which loads SSH config files from disk,
file-like object, or string and exposes a “look up a hostname, get a dict of
applicable keywords/values back” functionality.
As with OpenSSH’s own support, this dict will contain values from across the
parsed file, depending on the order in which keywords were encountered and how
specific or generic the Host
or Match
directives were.
Keywords currently supported¶
The following is an alphabetical list of which ssh_config directives Paramiko interprets during the parse/lookup process (as above, actual SSH connections do not reference parsed configs). Departures from OpenSSH’s implementation (e.g. to support backwards compat with older Paramiko releases) are included. A keyword by itself means no known departures.
AddressFamily
: used when looking up the local hostname for purposes of expanding the%l
/%L
tokens (this is actually a minor value-add on top of OpenSSH, which doesn’t actually honor this setting when expanding%l
).CanonicalDomains
New in version 2.7.
CanonicalizeFallbackLocal
: whenno
, triggers raising ofCouldNotCanonicalize
for target hostnames which do not successfully canonicalize.New in version 2.7.
CanonicalizeHostname
: along with the otherCanonicaliz*
settings (sansCanonicalizePermittedCNAMEs
, which is not yet implemented), enables hostname canonicalization, insofar as callingSSHConfig.lookup
with a given hostname will return a canonicalized copy of the config data, including an updatedHostName
value.New in version 2.7.
CanonicalizeMaxDots
New in version 2.7.
Host
HostName
: used in%h
token expansionMatch
: fully supported, with the following caveats:You must have the optional dependency Invoke installed; see the installation docs (in brief: install
paramiko[invoke]
orparamiko[all]
).As usual, connection-time information is not present during config lookup, and thus cannot be used to determine matching. This primarily impacts
Match user
, which can match against loadedUser
values but has no knowledge about connection-time usernames.
New in version 2.7.
Port
: supplies potential values for%p
token expansion.ProxyCommand
: see ourProxyCommand
class for an easy way to honor this keyword from a config you’ve parsed.Honors token expansion.
When a lookup would result in an effective
ProxyCommand none
, Paramiko (as of 1.x-2.x) strips it from the resulting dict entirely. A later major version may retain the"none"
marker for clarity’s sake.
User
: supplies potential values for%u
token expansion.
Expansion tokens¶
We support most SSH config expansion tokens where possible, so when they are
present in a config file source, the result of a SSHConfig.lookup
will
contain the expansions/substitutions (based on the rest of the config or
properties of the local system).
Specifically, we are known to support the below, where applicable (e.g. as in
OpenSSH, %L
works in ControlPath
but not elsewhere):
%C
%d
%h
%l
%L
%n
%p
%r
%u
: substitutes the configuredUser
value, or the local user (as seen bygetpass.getuser
) if not specified.
In addition, we extend OpenSSH’s tokens as follows:
~
is treated like%d
(expands to the local user’s home directory path) when expandingProxyCommand
values, sinceProxyCommand
does not natively support%d
for some reason.
config
module API documentation¶
Mostly of interest to contributors; see previous section for behavioral details.
Configuration file (aka ssh_config
) support.