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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
======================
Command-line interface
======================
This page documents the details of Fabric's command-line interface, ``fab``.
Options & arguments
===================
.. note::
By default, ``fab`` honors all of the same CLI options as :ref:`Invoke's
'inv' program <inv>`; only additions and overrides are listed here!
For example, Fabric implements :option:`--prompt-for-passphrase` and
:option:`--prompt-for-login-password` because they are SSH specific, but
it inherits a related option -- :ref:`--prompt-for-sudo-password
<prompt-for-sudo-password>` -- from Invoke, which handles sudo autoresponse
concerns.
.. option:: -H, --hosts
Takes a comma-separated string listing hostnames against which tasks
should be executed, in serial. See :ref:`runtime-hosts`.
.. option:: -i, --identity
Overrides the ``key_filename`` value in the ``connect_kwargs`` config
setting (which is read by `.Connection`, and eventually makes its way into
Paramiko; see the docstring for `.Connection` for details.)
Typically this can be thought of as identical to ``ssh -i <path>``, i.e.
supplying a specific, runtime private key file. Like ``ssh -i``, it builds
an iterable of strings and may be given multiple times.
New in version 3.1: this also ends up in the ``authentication.identities``
:doc:`configuration value </concepts/configuration>` and will be referenced
by `fabric.auth.OpenSSHAuthStrategy`, if in use.
Default: ``[]``.
.. option:: --prompt-for-login-password
Causes Fabric to prompt 'up front' for a value to store as the
``connect_kwargs.password`` config setting (used by Paramiko when
authenticating via passwords and, in some versions, also used for key
passphrases.) Useful if you do not want to configure such values in on-disk
conf files or via shell environment variables.
.. option:: --prompt-for-passphrase
Causes Fabric to prompt 'up front' for a value to store as the
``connect_kwargs.passphrase`` config setting (used by Paramiko to decrypt
private key files.) Useful if you do not want to configure such values in
on-disk conf files or via shell environment variables.
.. option:: -S, --ssh-config
Takes a path to load as a runtime SSH config file. See :ref:`ssh-config`.
.. option:: -t, --connect-timeout
Takes an integer of seconds after which connection should time out.
Supplies the default value for the ``timeouts.connect`` config setting.
Seeking & loading tasks
=======================
``fab`` follows all the same rules as Invoke's :ref:`collection loading
<collection-discovery>`, with the sole exception that the default collection
name sought is ``fabfile`` instead of ``tasks``. Thus, whenever Invoke's
documentation mentions ``tasks`` or ``tasks.py``, Fabric substitutes
``fabfile`` / ``fabfile.py``.
For example, if your current working directory is
``/home/myuser/projects/mywebapp``, running ``fab --list`` will cause Fabric to
look for ``/home/myuser/projects/mywebapp/fabfile.py`` (or
``/home/myuser/projects/mywebapp/fabfile/__init__.py`` - Python's import system
treats both the same). If it's not found there,
``/home/myuser/projects/fabfile.py`` is sought next; and so forth.
.. _runtime-hosts:
Runtime specification of host lists
===================================
While advanced use cases may need to take matters into their own hands, you can
go reasonably far with the core :option:`--hosts` flag, which specifies one or
more hosts the given task(s) should execute against.
By default, execution is a serial process: for each task on the command line,
run it once for each host given to :option:`--hosts`. Imagine tasks that simply
print ``Running <task name> on <host>!``::
$ fab --hosts host1,host2,host3 taskA taskB
Running taskA on host1!
Running taskA on host2!
Running taskA on host3!
Running taskB on host1!
Running taskB on host2!
Running taskB on host3!
.. note::
When :option:`--hosts` is not given, ``fab`` behaves similarly to Invoke's
:ref:`command-line interface <inv>`, generating regular instances of
`~invoke.context.Context` instead of `Connections <.Connection>`.
Executing arbitrary/ad-hoc commands
===================================
``fab`` leverages a lesser-known command line convention and may be called in
the following manner::
$ fab [options] -- [shell command]
where everything after the ``--`` is turned into a temporary `.Connection.run`
call, and is not parsed for ``fab`` options. If you've specified a host list
via an earlier task or the core CLI flags, this usage will act like a one-line
anonymous task.
For example, let's say you wanted kernel info for a bunch of systems::
$ fab -H host1,host2,host3 -- uname -a
Such a command is equivalent to the following Fabric library code::
from fabric import Group
Group('host1', 'host2', 'host3').run("uname -a")
Most of the time you will want to just write out the task in your fabfile
(anything you use once, you're likely to use again) but this feature provides a
handy, fast way to dash off an SSH-borne command while leveraging predefined
connection settings.
|
