Navigation

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.

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:

fromfabric.apiimportrundefanonymous():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.

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. fabtask1-Hhostnametask2-ipath/to/keyfile is
just as valid as the more straightforward fab-Hhostname-ipath/to/keyfiletask1task2.

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.)

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;

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):

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'].

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.