1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
==============
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
<paramiko.client.SSHClient.connect>`", which in turn means to set values
inside either the ``connect_kwargs`` :doc:`config
</concepts/configuration>` 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 </concepts/configuration>`) 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 <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
</concepts/configuration>` 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 <paramiko.pkey.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 <paramiko.client.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.
|
