============== Authentication ============== Even in the 'vanilla' OpenSSH client, authenticating to remote servers involves multiple potential sources for secrets and configuration; Fabric not only supports most of those, but has more of its own. This document outlines the available methods for setting authentication secrets. .. note:: Since Fabric itself tries not to reinvent too much Paramiko functionality, most of the time configuring authentication values boils down to "how to set keyword argument values for `SSHClient.connect `", which in turn means to set values inside either the ``connect_kwargs`` :doc:`config ` subtree, or the ``connect_kwargs`` keyword argument of `.Connection`. Private key files ================= Private keys stored on-disk are probably the most common auth mechanism for SSH. Fabric offers multiple methods of configuring which paths to use, most of which end up merged into one list of paths handed to ``SSHClient.connect(key_filename=[...])``, in the following order: - If a ``key_filename`` key exists in the ``connect_kwargs`` argument to `.Connection`, they come first in the list. (This is basically the "runtime" option for non-CLI users.) - The config setting ``connect_kwargs.key_filename`` can be set in a number of ways (as per the :doc:`config docs `) including via the :option:`--identity` CLI flag (which sets the ``overrides`` level of the config; so when this flag is used, key filename values from other config sources will be overridden.) This value comes next in the overall list. - Using an :ref:`ssh_config ` file with ``IdentityFile`` directives lets you share configuration with other SSH clients; such values come last. Encryption passphrases ---------------------- If your private key file is protected via a passphrase, it can be supplied in a handful of ways: - The ``connect_kwargs.passphrase`` config option is the most direct way to supply a passphrase to be used automatically. .. note:: Using actual on-disk config files for this type of material isn't always wise, but recall that the :doc:`configuration system ` is capable of loading data from other sources, such as your shell environment or even arbitrary remote databases. - If you prefer to enter the passphrase manually at runtime, you may use the command-line option :option:`--prompt-for-passphrase`, which will cause Fabric to interactively prompt the user at the start of the process, and store the entered value in ``connect_kwargs.passphrase`` (at the 'overrides' level.) Private key objects =================== Instantiate your own `PKey ` object (see its subclasses' API docs for details) and place it into ``connect_kwargs.pkey``. That's it! You'll be responsible for any handling of passphrases, if the key material you're loading (these classes can load from file paths or strings) is encrypted. SSH agents ========== By default (similar to how OpenSSH behaves) Paramiko will attempt to connect to a running SSH agent (Unix style, e.g. a live ``SSH_AUTH_SOCK``, or Pageant if one is on Windows). This can be disabled by setting ``connect_kwargs.allow_agent`` to ``False``. Passwords ========= Password authentication is relatively straightforward: - You can configure it via ``connect_kwargs.password`` directly. - If you want to be prompted for it at the start of a session, specify :option:`--prompt-for-login-password`. .. TODO: host-configuration hooks are very important here, when implemented GSSAPI ====== Fabric doesn't provide any extra GSSAPI support on top of Paramiko's existing connect-time parameters (see e.g. ``gss_kex``/``gss_auth``/``gss_host``/etc in `SSHClient.connect `) and the modules implementing the functionality itself (such as `paramiko.ssh_gss`.) Thus, as usual, you should be looking to modify the ``connect_kwargs`` configuration tree.