fab
options and arguments¶
The most common method for utilizing Fabric is via its command-line tool,
fab
, which should have been placed on your shell’s executable path when
Fabric was installed. fab
tries hard to be a good Unix citizen, using a
standard style of command-line switches, help output, and so forth.
Basic use¶
In its most simple form, fab
may be called with no options at all, and
with one or more arguments, which should be task names, e.g.:
$ fab task1 task2
As detailed in Overview and Tutorial and Execution model, this will run task1
followed by task2
, assuming that Fabric was able to find a fabfile nearby
containing Python functions with those names.
However, it’s possible to expand this simple usage into something more flexible, by using the provided options and/or passing arguments to individual tasks.
Arbitrary remote shell commands¶
New in version 0.9.2.
Fabric 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
run
call, and is not parsed for fab
options. If you’ve
defined a host list at the module level or on the command line, this usage will
act like a one-line anonymous task.
For example, let’s say you just wanted to get the kernel info for a bunch of systems; you could do this:
$ fab -H system1,system2,system3 -- uname -a
which would be literally equivalent to the following fabfile:
from fabric.api import run
def anonymous():
run("uname -a")
as if it were executed thusly:
$ fab -H system1,system2,system3 anonymous
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 quickly dash off an SSH-borne command while leveraging your fabfile’s connection settings.
Command-line options¶
A quick overview of all possible command line options can be found via fab
--help
. If you’re looking for details on a specific option, we go into detail
below.
Note
fab
uses Python’s optparse library, meaning that it honors typical
Linux or GNU style short and long options, as well as freely mixing options
and arguments. E.g. fab task1 -H hostname task2 -i path/to/keyfile
is
just as valid as the more straightforward fab -H hostname -i
path/to/keyfile task1 task2
.
-
-a
,
--no_agent
¶
Sets env.no_agent to
True
, forcing our SSH layer not to talk to the SSH agent when trying to unlock private key files.New in version 0.9.1.
-
-A
,
--forward-agent
¶
Sets env.forward_agent to
True
, enabling agent forwarding.New in version 1.4.
-
--abort-on-prompts
¶
Sets env.abort_on_prompts to
True
, forcing Fabric to abort whenever it would prompt for input.New in version 1.1.
-
-c
RCFILE
,
--config
=RCFILE
¶ Sets env.rcfile to the given file path, which Fabric will try to load on startup and use to update environment variables.
-
-d
COMMAND
,
--display
=COMMAND
¶ Prints the entire docstring for the given task, if there is one. Does not currently print out the task’s function signature, so descriptive docstrings are a good idea. (They’re always a good idea, of course – just moreso here.)
-
--connection-attempts
=M
,
-n
M
¶ Set number of times to attempt connections. Sets env.connection_attempts.
See also
New in version 1.4.
-
-D
,
--disable-known-hosts
¶
Sets env.disable_known_hosts to
True
, preventing Fabric from loading the user’s SSHknown_hosts
file.
-
-f
FABFILE
,
--fabfile
=FABFILE
¶ The fabfile name pattern to search for (defaults to
fabfile.py
), or alternately an explicit file path to load as the fabfile (e.g./path/to/my/fabfile.py
.)See also
-
-F
LIST_FORMAT
,
--list-format
=LIST_FORMAT
¶ Allows control over the output format of
--list
.short
is equivalent to--shortlist
,normal
is the same as simply omitting this option entirely (i.e. the default), andnested
prints out a nested namespace tree.New in version 1.1.
See also
-
-g
HOST
,
--gateway
=HOST
¶ Sets env.gateway to
HOST
host string.New in version 1.5.
-
--gss-auth
¶
Toggles use of GSS-API authentication.
See also
New in version 1.11.
-
--gss-deleg
¶
Toggles whether GSS-API client credentials are delegated.
See also
New in version 1.11.
-
--gss-kex
¶
Toggles whether GSS-API key exchange is used.
See also
New in version 1.11.
-
-h
,
--help
¶
Displays a standard help message, with all possible options and a brief overview of what they do, then exits.
-
--hide
=LEVELS
¶ A comma-separated list of output levels to hide by default.
-
-x
HOSTS
,
--exclude-hosts
=HOSTS
¶ Sets env.exclude_hosts to the given comma-delimited list of host strings to then keep out of the final host list.
New in version 1.1.
-
-i
KEY_FILENAME
¶ When set to a file path, will load the given file as an SSH identity file (usually a private key.) This option may be repeated multiple times. Sets (or appends to) env.key_filename.
-
-I
,
--initial-password-prompt
¶
Forces a password prompt at the start of the session (after fabfile load and option parsing, but before executing any tasks) in order to pre-fill env.password.
This is useful for fire-and-forget runs (especially parallel sessions, in which runtime input is not possible) when setting the password via
--password
or by setting env.password in your fabfile, is undesirable.Note
The value entered into this prompt will overwrite anything supplied via env.password at module level, or via
--password
.See also
-
--initial-sudo-password-prompt
¶
Like
--initial-password-prompt
, but for prefilling sudo_password instead of password.New in version 1.12.
-
-k
¶
Sets env.no_keys to
True
, forcing the SSH layer to not look for SSH private key files in one’s home directory.New in version 0.9.1.
-
--keepalive
=KEEPALIVE
¶ Sets env.keepalive to the given (integer) value, specifying an SSH keepalive interval.
New in version 1.1.
-
--linewise
¶
Forces output to be buffered line-by-line instead of byte-by-byte. Often useful or required for parallel execution.
New in version 1.3.
-
-l
,
--list
¶
Imports a fabfile as normal, but then prints a list of all discovered tasks and exits. Will also print the first line of each task’s docstring, if it has one, next to it (truncating if necessary.)
Changed in version 0.9.1: Added docstring to output.
See also
-
-p
PASSWORD
,
--password
=PASSWORD
¶ Sets env.password to the given string; it will then be used as the default password when making SSH connections or calling the
sudo
program.See also
-
-P
,
--parallel
¶
Sets env.parallel to
True
, causing tasks to run in parallel.New in version 1.3.
See also
-
--no-pty
¶
Sets env.always_use_pty to
False
, causing allrun
/sudo
calls to behave as if one had specifiedpty=False
.New in version 1.0.
-
-r
,
--reject-unknown-hosts
¶
Sets env.reject_unknown_hosts to
True
, causing Fabric to abort when connecting to hosts not found in the user’s SSHknown_hosts
file.
-
--set
KEY=VALUE,...
¶ Allows you to set default values for arbitrary Fabric env vars. Values set this way have a low precedence – they will not override more specific env vars which are also specified on the command line. E.g.:
fab --set password=foo --password=bar
will result in
env.password = 'bar'
, not'foo'
Multiple
KEY=VALUE
pairs may be comma-separated, e.g.fab --set var1=val1,var2=val2
.Other than basic string values, you may also set env vars to True by omitting the
=VALUE
(e.g.fab --set KEY
), and you may set values to the empty string (and thus a False-equivalent value) by keeping the equals sign, but omittingVALUE
(e.g.fab --set KEY=
.)New in version 1.4.
-
-s
SHELL
,
--shell
=SHELL
¶ Sets env.shell to the given string, overriding the default shell wrapper used to execute remote commands.
-
--shortlist
¶
Similar to
--list
, but without any embellishment, just task names separated by newlines with no indentation or docstrings.New in version 0.9.2.
See also
-
--show
=LEVELS
¶ A comma-separated list of output levels to be added to those that are shown by default.
-
--ssh-config-path
¶
Sets env.ssh_config_path.
New in version 1.4.
See also
-
--skip-bad-hosts
¶
Sets env.skip_bad_hosts, causing Fabric to skip unavailable hosts.
New in version 1.4.
-
--skip-unknown-tasks
¶
Sets env.skip_unknown_tasks, causing Fabric to skip unknown tasks.
See also
-
--sudo-password
¶
Sets env.sudo_password.
New in version 1.12.
-
--timeout
=N
,
-t
N
¶ Set connection timeout in seconds. Sets env.timeout.
See also
New in version 1.4.
-
--command-timeout
=N
,
-T
N
¶ Set remote command timeout in seconds. Sets env.command_timeout.
See also
New in version 1.6.
-
-u
USER
,
--user
=USER
¶ Sets env.user to the given string; it will then be used as the default username when making SSH connections.
-
-V
,
--version
¶
Displays Fabric’s version number, then exits.
-
-w
,
--warn-only
¶
Sets env.warn_only to
True
, causing Fabric to continue execution even when commands encounter error conditions.
-
-z
,
--pool-size
¶
Sets env.pool_size, which specifies how many processes to run concurrently during parallel execution.
New in version 1.3.
See also
Per-task arguments¶
The options given in Command-line options apply to the invocation of
fab
as a whole; even if the order is mixed around, options still apply to
all given tasks equally. Additionally, since tasks are just Python functions,
it’s often desirable to pass in arguments to them at runtime.
Answering both these needs is the concept of “per-task arguments”, which is a special syntax you can tack onto the end of any task name:
- Use a colon (
:
) to separate the task name from its arguments; - Use commas (
,
) to separate arguments from one another (may be escaped by using a backslash, i.e.\,
); - Use equals signs (
=
) for keyword arguments, or omit them for positional arguments. May also be escaped with backslashes.
Additionally, since this process involves string parsing, all values will end up as Python strings, so plan accordingly. (We hope to improve upon this in future versions of Fabric, provided an intuitive syntax can be found.)
For example, a “create a new user” task might be defined like so (omitting most of the actual logic for brevity):
def new_user(username, admin='no', comment="No comment provided"):
print("New User (%s): %s" % (username, comment))
pass
You can specify just the username:
$ fab new_user:myusername
Or treat it as an explicit keyword argument:
$ fab new_user:username=myusername
If both args are given, you can again give them as positional args:
$ fab new_user:myusername,yes
Or mix and match, just like in Python:
$ fab new_user:myusername,admin=yes
The print
call above is useful for illustrating escaped commas, like
so:
$ fab new_user:myusername,admin=no,comment='Gary\, new developer (starts Monday)'
Note
Quoting the backslash-escaped comma is required, as not doing so will cause shell syntax errors. Quotes are also needed whenever an argument involves other shell-related characters such as spaces.
All of the above are translated into the expected Python function calls. For example, the last call above would become:
>>> new_user('myusername', admin='yes', comment='Gary, new developer (starts Monday)')
Roles and hosts¶
As mentioned in the section on task execution,
there are a handful of per-task keyword arguments (host
, hosts
,
role
and roles
) which do not actually map to the task functions
themselves, but are used for setting per-task host and/or role lists.
These special kwargs are removed from the args/kwargs sent to the task function itself; this is so that you don’t run into TypeErrors if your task doesn’t define the kwargs in question. (It also means that if you do define arguments with these names, you won’t be able to specify them in this manner – a regrettable but necessary sacrifice.)
Note
If both the plural and singular forms of these kwargs are given, the value of the plural will win out and the singular will be discarded.
When using the plural form of these arguments, one must use semicolons (;
)
since commas are already being used to separate arguments from one another.
Furthermore, since your shell is likely to consider semicolons a special
character, you’ll want to quote the host list string to prevent shell
interpretation, e.g.:
$ fab new_user:myusername,hosts="host1;host2"
Again, since the hosts
kwarg is removed from the argument list sent to the
new_user
task function, the actual Python invocation would be
new_user('myusername')
, and the function would be executed on a host list
of ['host1', 'host2']
.
Settings files¶
Fabric currently honors a simple user settings file, or fabricrc
(think
bashrc
but for fab
) which should contain one or more key-value pairs,
one per line. These lines will be subject to string.split('=')
, and thus
can currently only be used to specify string settings. Any such key-value pairs
will be used to update env when fab
runs, and is loaded prior
to the loading of any fabfile.
By default, Fabric looks for ~/.fabricrc
, and this may be overridden by
specifying the -c
flag to fab
.
For example, if your typical SSH login username differs from your workstation
username, and you don’t want to modify env.user
in a project’s fabfile
(possibly because you expect others to use it as well) you could write a
fabricrc
file like so:
user = ssh_user_name
Then, when running fab
, your fabfile would load up with env.user
set to
'ssh_user_name'
. Other users of that fabfile could do the same, allowing
the fabfile itself to be cleanly agnostic regarding the default username.
Exit status¶
If fab
executes all commands on all hosts successfully, success (0) is returned.
Otherwise,
- If an invalid command or option is specified,
fab
aborts with an exit status of 1. - If a connection to a host fails,
fab
aborts with an exit status of 1. It will not try the next host. - If a local or remote command fails (returns non-zero status),
fab
aborts with an exit status of 1. The exit status of the original command can be found in the log. - If a Python exception is thrown,
fab
aborts with an exit status of 1.