.. _fab-configuration: ============= 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 :ref:`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 :ref:`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 :ref:`default-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 :ref:`ssh-config`. * 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-values: 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. .. seealso:: The warning under `paramiko.channel.Channel.set_environment_variable`. Extensions to Invoke-level defaults ----------------------------------- - ``runners.remote``: In Invoke, the ``runners`` tree has a single subkey, ``local`` (mapping to `~invoke.runners.Local`). Fabric adds this new subkey, ``remote``, which is mapped to `~fabric.runners.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 :ref:`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 :ref:`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_ssh_configs``: Whether to automatically seek out :ref:`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 :ref:`ssh-config`. 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. .. _ssh-config: 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 `~paramiko.config.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 `~paramiko.config.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 :option:`--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 `~paramiko.config.SSHConfig` is the final result. - Regardless of how the object was generated, it is exposed as ``Config.base_ssh_config``. .. _connection-ssh-config: ``Connection``'s use of ``ssh_config`` values --------------------------------------------- `.Connection` objects expose a per-host 'view' of their config's SSH data (obtained via `~paramiko.config.SSHConfig.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``: .. code:: 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 `~paramiko.config.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. .. TODO: honor ProxyJump's comma-separated variant, which should translate to (reverse-ordered) nested Connection-style gateways. Authentication ~~~~~~~~~~~~~~ - ``ForwardAgent``: controls default behavior of ``forward_agent``. - ``IdentityFile``: appends to the ``key_filename`` key within ``connect_kwargs`` (similar to :option:`--identity`.) .. TODO: merge with per-host config when it's figured out .. _disabling-ssh-config: 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 :option:`-F`). If a user is explicitly telling us to load such a file, we assume they know what they're doing.