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
fabric.config.Config). For practical details on
what this means re: configuring Fabric’s behavior, please see Invoke’s
The primary differences from that document are as follows:
The configuration file paths sought are all named
Fabric has facilities for loading SSH config files, and will automatically create (or update) a configuration subtree on a per
Connectionbasis, 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.rolesstructures 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_configanalogues, nor do all use cases fit neatly into such files.
Default configuration values¶
Overrides of Invoke-level defaults¶
run.replace_env: defaults to
True, instead of
False, 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.
The warning under
This is currently accomplished with a keyword argument override, as the config setting itself was applying to both
local. Future updates will ensure the two methods use separate config values.
Extensions to Invoke-level defaults¶
New default values defined by Fabric¶
Most of these settings are also available in the constructor of
Connection, if they only need modification on a per-connection basis.
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 to
Connectionperforms 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 the
Connection. May be any value accepted by that argument. Default:
load_ssh_configs: Whether to automatically seek out SSH config files. When
False, no automatic loading occurs. Default:
port: TCP port number used by
Connectionobjects when not otherwise specified. Default:
inline_ssh_env: Boolean serving as global default for the value of
inline_ssh_envparameter; see its docs for details. Default:
ssh_config_path: Runtime SSH config path; see Loading and using ssh_config files. Default:
timeouts: Various timeouts, specifically:
connect: Connection timeout, in seconds; defaults to
None, meaning no timeout / block forever.
user: Username given to the remote
sshdwhen connecting. Default: your local system username.
Loading and using
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):
A runtime file path may be specified via configuration itself, as the
ssh_config_pathkey; such a path will be loaded into a new
SSHConfigobject at the end of
Config.__init__and no other files will be sought out.
It will be filled in by the
fabCLI tool if the
--ssh-configflag is given.
If no runtime config (object or path) was given to
Config.__init__, it will automatically seek out and load
/etc/ssh/ssh_config, if they exist (and in that order.)
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
SSHConfigis the final result.
Regardless of how the object was generated, it is exposed as
Connection’s use of
Connection objects expose a per-host ‘view’ of their config’s SSH data
Connection itself references these values as described in the following
subsections, usually as simple defaults for the appropriate config key or
Unless otherwise specified, these values override regular configuration values
for the same keys, but may themselves be overridden by
Take for example a
Absent any other configuration,
Connection('myhost') connects as the
If we also have an
Host * User bar
Connection('myhost') connects as
bar (the SSH config wins over
the Fabric config.)
However, in both cases,
Connection('myhost', user='biz') will connect as
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.
Hostname: replaces the original value of
host(which is preserved as
Port: supplies the default value for the
portconfig option / parameter.
User: supplies the default value for the
userconfig option / parameter.
ConnectTimeout: sets the default value for the
timeouts.connectconfig option /
ProxyCommand: supplies default (string) value for
ProxyJump: supplies default (
Connection) value for
firstname.lastname@example.org,email@example.com,..., will result in an appropriate series of nested
gatewayvalues under the hood - as if the user had manually specified
Connecton(..., gateway=Connection('firstname.lastname@example.org', gateway=Connection('email@example.com', gateway=...))).
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
ForwardAgent: controls default behavior of
IdentityFile: appends to the
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
overriding values that are being set in the regular config hierarchy.
To do so, simply set the top level config option
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.