Configuration¶
Basics¶
The heart of Fabric’s configuration system (as with much of the rest of Fabric)
relies on Invoke functionality, namely invoke.config.Config
(technically, a
lightweight subclass, fabric.config.Config
). For practical details on
what this means re: configuring Fabric’s behavior, please see Invoke’s
configuration documentation.
The primary differences from that document are as follows:
The configuration file paths sought are all named
fabric.*
instead ofinvoke.*
- e.g./etc/fabric.yml
instead of/etc/invoke.yml
,~/.fabric.py
instead of~/.invoke.py
, etc.In addition to Invoke’s own default configuration values, Fabric merges in some of its own, such as the fact that SSH’s default port number is 22. See Default configuration values for details.
Fabric has facilities for loading SSH config files, and will automatically create (or update) a configuration subtree on a per
Connection
basis, loaded with the interpreted SSH configuration for that specific host (since an SSH config file is only ever useful via such a lens). See Loading and using ssh_config files.Fabric plans to offer a framework for managing per-host and per-host-collection configuration details and overrides, though this is not yet implemented (it will be analogous to, but improved upon, the
env.hosts
andenv.roles
structures from Fabric 1.x).- This functionality will supplement that of the SSH config loading
described earlier; we expect most users will prefer to configure as much
as possible via an SSH config file, but not all Fabric settings have
ssh_config
analogues, nor do all use cases fit neatly into such files.
- This functionality will supplement that of the SSH config loading
described earlier; we expect most users will prefer to configure as much
as possible via an SSH config file, but not all Fabric settings have
Default configuration values¶
Overrides of Invoke-level defaults¶
run.replace_env
:True
, instead ofFalse
, so that remote commands run with a ‘clean’, empty environment instead of inheriting a copy of the current process’ environment.This is for security purposes: leaking local environment data remotely by default would be unsanitary. It’s also compatible with the behavior of OpenSSH.
See also
The warning under
paramiko.channel.Channel.set_environment_variable
.
Extensions to Invoke-level defaults¶
New default values defined by Fabric¶
Note
Most of these settings are also available in the constructor of
Connection
, if they only need modification on a per-connection basis.
Warning
Many of these are also configurable via ssh_config files. Such values take precedence over those defined via the core configuration, so make sure you’re aware of whether you’re loading such files (or disable them to be sure).
connect_kwargs
: Keyword arguments (dict
) given toSSHClient.connect
whenConnection
performs that method call. This is the primary configuration vector for many SSH-related options, such as selecting private keys, toggling forwarding of SSH agents, etc. Default:{}
.forward_agent
: Whether to attempt forwarding of your local SSH authentication agent to the remote end. Default:False
(same as in OpenSSH.)gateway
: Used as the default value of thegateway
kwarg forConnection
. May be any value accepted by that argument. Default:None
.load_ssh_configs
: Whether to automatically seek out SSH config files. WhenFalse
, no automatic loading occurs. Default:True
.port
: TCP port number used byConnection
objects when not otherwise specified. Default:22
.inline_ssh_env
: Boolean serving as global default for the value ofConnection
’sinline_ssh_env
parameter; see its docs for details. Default:False
.ssh_config_path
: Runtime SSH config path; see Loading and using ssh_config files. Default:None
.timeouts
: Various timeouts, specifically:connect
: Connection timeout, in seconds; defaults toNone
, meaning no timeout / block forever.
user
: Username given to the remotesshd
when connecting. Default: your local system username.
Loading and using ssh_config
files¶
How files are loaded¶
Fabric uses Paramiko’s SSH config file machinery to load and parse
ssh_config
-format files (following OpenSSH’s behavior re: which files to
load, when possible):
An already-parsed
SSHConfig
object may be given toConfig.__init__
via itsssh_config
keyword argument; if this value is given, no files are loaded, even if they exist.A runtime file path may be specified via configuration itself, as the
ssh_config_path
key; such a path will be loaded into a newSSHConfig
object at the end ofConfig.__init__
and no other files will be sought out.- It will be filled in by the
fab
CLI tool if the--ssh-config
flag is given.
- It will be filled in by the
If no runtime config (object or path) was given to
Config.__init__
, it will automatically seek out and load~/.ssh/config
and/or/etc/ssh/ssh_config
, if they exist (and in that order.)Note
Rules present in both files will result in the user-level file ‘winning’, as the first rule found during lookup is always used.
If none of the above vectors yielded SSH config data, a blank/empty
SSHConfig
is the final result.Regardless of how the object was generated, it is exposed as
Config.base_ssh_config
.
Connection
’s use of ssh_config
values¶
Connection
objects expose a per-host ‘view’ of their config’s SSH data
(obtained via lookup
) as Connection.ssh_config
.
Connection
itself references these values as described in the following
subsections, usually as simple defaults for the appropriate config key or
parameter (port
, forward_agent
, etc.)
Unless otherwise specified, these values override regular configuration values
for the same keys, but may themselves be overridden by Connection.__init__
parameters.
Take for example a ~/.fabric.yaml
:
user: foo
Absent any other configuration, Connection('myhost')
connects as the
foo
user.
If we also have an ~/.ssh/config
:
Host *
User bar
then Connection('myhost')
connects as bar
(the SSH config wins over
the Fabric config.)
However, in both cases, Connection('myhost', user='biz')
will connect as
biz
.
Note
The below sections use capitalized versions of ssh_config
keys for
easier correlation with man ssh_config
, but the actual
SSHConfig
data structure is normalized to lowercase
keys, since SSH config files are technically case-insensitive.
Connection parameters¶
Hostname
: replaces the original value ofhost
(which is preserved as.original_host
.)Port
: supplies the default value for theport
config option / parameter.User
: supplies the default value for theuser
config option / parameter.ConnectTimeout
: sets the default value for thetimeouts.connect
config option /timeout
parameter.
Proxying¶
ProxyCommand
: supplies default (string) value forgateway
.ProxyJump
: supplies default (Connection
) value forgateway
.- Nested-style
ProxyJump
, i.e.user1@hop1.host,user2@hop2.host,...
, will result in an appropriate series of nestedgateway
values under the hood - as if the user had manually specifiedConnecton(..., gateway=Connection('user1@hop1.host', gateway=Connection('user2@hop2.host', gateway=...)))
.
- Nested-style
Note
If both are specified for a given host, ProxyJump
will override
ProxyCommand
. This is slightly different from OpenSSH, where the order
the directives are loaded determines which one wins. Doing so on our end
(where we view the config as a dictionary structure) requires additional
work.
Authentication¶
ForwardAgent
: controls default behavior offorward_agent
.IdentityFile
: appends to thekey_filename
key withinconnect_kwargs
(similar to--identity
.)
Disabling (most) ssh_config
loading¶
Users who need tighter control over how their environment gets configured may
want to disable the automatic loading of system/user level SSH config files;
this can prevent hard-to-expect errors such as a new user’s ~/.ssh/config
overriding values that are being set in the regular config hierarchy.
To do so, simply set the top level config option load_ssh_configs
to
False
.
Note
Changing this setting does not disable loading of runtime-level config
files (e.g. via -F
). If a user is explicitly telling us to load
such a file, we assume they know what they’re doing.