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 of invoke.* - 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 and env.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.

Default configuration values

Overrides of Invoke-level defaults

  • run.replace_env: 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.

Extensions to Invoke-level defaults

  • runners.remote: In Invoke, the runners tree has a single subkey, local (mapping to Local). Fabric adds this new subkey, remote, which is mapped to Remote.

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 to SSHClient.connect when Connection 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 the gateway kwarg for Connection. May be any value accepted by that argument. Default: None.

  • load_openssh_configs: Whether to automatically seek out SSH config files. When False, no automatic loading occurs. Default: True.

  • port: TCP port number used by Connection objects when not otherwise specified. Default: 22.

  • 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 to None, meaning no timeout / block forever.
  • user: Username given to the remote sshd 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 to Config.__init__ via its ssh_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 new SSHConfig object at the end of Config.__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.
  • 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 of host (which is preserved as .original_host.)
  • Port: supplies the default value for the port config option / parameter.
  • User: supplies the default value for the user config option / parameter.
  • ConnectTimeout: sets the default value for the timeouts.connect config option / timeout parameter.

Proxying

  • ProxyCommand: supplies default (string) value for gateway.
  • ProxyJump: supplies default (Connection) value for gateway.
    • Nested-style ProxyJump, i.e. user1@hop1.host,user2@hop2.host,..., will result in an appropriate series of nested gateway values under the hood - as if the user had manually specified Connecton(..., gateway=Connection('user1@hop1.host', gateway=Connection('user2@hop2.host', gateway=...))).

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 of forward_agent.
  • IdentityFile: appends to the key_filename key within connect_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.