.TH FAB 1 "September 15, 2015"
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH NAME
fab - Simple Pythonic remote deployment tool
.SH SYNOPSIS
.PP
\fB \fr\fIfab\fR \fR\fI[commands ...]\fR
.SH DESCRIPTION
.PP
The most common method for utilizing Fabric is via its command\-line tool,
\fBfab\fP, which should have been placed on your shell\(aqs executable path when
Fabric was installed. \fBfab\fP tries hard to be a good Unix citizen, using a
standard style of command\-line switches, help output, and so forth.
.SH USAGE
.PP
.SS Basic use
.sp
In its most simple form, \fBfab\fP may be called with no options at all, and
with one or more arguments, which should be task names, e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab task1 task2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will run \fBtask1\fP followed by \fBtask2\fP, assuming that Fabric was able
to find a fabfile nearby containing Python functions with those names.
.sp
However, it\(aqs possible to expand this simple usage into something more
flexible, by using the provided options and/or passing arguments to individual
tasks.
.SS Arbitrary remote shell commands
.sp
New in version 0.9.2.

.sp
Fabric leverages a lesser\-known command line convention and may be called in
the following manner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab [options] \-\- [shell command]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where everything after the \fB\-\-\fP is turned into a temporary
\fBrun\fP call, and is not parsed for \fBfab\fP options. If you\(aqve
defined a host list at the module level or on the command line, this usage will
act like a one\-line anonymous task.
.sp
For example, let\(aqs say you just wanted to get the kernel info for a bunch of
systems; you could do this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab \-H system1,system2,system3 \-\- uname \-a
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which would be literally equivalent to the following fabfile:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from fabric.api import run

def anonymous():
    run("uname \-a")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
as if it were executed thusly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab \-H system1,system2,system3 anonymous
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Most of the time you will want to just write out the task in your fabfile
(anything you use once, you\(aqre likely to use again) but this feature provides a
handy, fast way to quickly dash off an SSH\-borne command while leveraging your
fabfile\(aqs connection settings.
.SS Command\-line options
.sp
A quick overview of all possible command line options can be found via \fBfab
\-\-help\fP\&. If you\(aqre looking for details on a specific option, we go into detail
below.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBfab\fP uses Python\(aqs \fI\%optparse\fP library, meaning that it honors typical
Linux or GNU style short and long options, as well as freely mixing options
and arguments. E.g. \fBfab task1 \-H hostname task2 \-i path/to/keyfile\fP is
just as valid as the more straightforward \fBfab \-H hostname \-i
path/to/keyfile task1 task2\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-a, \-\-no_agent
Sets \fIenv.no_agent\fP to \fBTrue\fP, forcing our SSH layer not
to talk to the SSH agent when trying to unlock private key files.
.sp
New in version 0.9.1.

.UNINDENT
.INDENT 0.0
.TP
.B \-A, \-\-forward\-agent
Sets \fIenv.forward_agent\fP to \fBTrue\fP, enabling agent
forwarding.
.sp
New in version 1.4.

.UNINDENT
.INDENT 0.0
.TP
.B \-\-abort\-on\-prompts
Sets \fIenv.abort_on_prompts\fP to \fBTrue\fP, forcing
Fabric to abort whenever it would prompt for input.
.sp
New in version 1.1.

.UNINDENT
.INDENT 0.0
.TP
.B \-c RCFILE, \-\-config=RCFILE
Sets \fIenv.rcfile\fP to the given file path, which Fabric will
try to load on startup and use to update environment variables.
.UNINDENT
.INDENT 0.0
.TP
.B \-d COMMAND, \-\-display=COMMAND
Prints the entire docstring for the given task, if there is one. Does not
currently print out the task\(aqs function signature, so descriptive
docstrings are a good idea. (They\(aqre \fIalways\fP a good idea, of course \-\-
just moreso here.)
.UNINDENT
.INDENT 0.0
.TP
.B \-\-connection\-attempts=M, \-n M
Set number of times to attempt connections. Sets
\fIenv.connection_attempts\fP\&.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fIenv.connection_attempts\fP,
\fIenv.timeout\fP
.UNINDENT
.UNINDENT
.sp
New in version 1.4.

.UNINDENT
.INDENT 0.0
.TP
.B \-D, \-\-disable\-known\-hosts
Sets \fIenv.disable_known_hosts\fP to \fBTrue\fP,
preventing Fabric from loading the user\(aqs SSH \fBknown_hosts\fP file.
.UNINDENT
.INDENT 0.0
.TP
.B \-f FABFILE, \-\-fabfile=FABFILE
The fabfile name pattern to search for (defaults to \fBfabfile.py\fP), or
alternately an explicit file path to load as the fabfile (e.g.
\fB/path/to/my/fabfile.py\fP\&.)
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fBfabfiles\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-F LIST_FORMAT, \-\-list\-format=LIST_FORMAT
Allows control over the output format of \fI\-\-list\fP\&. \fBshort\fP is
equivalent to \fI\-\-shortlist\fP, \fBnormal\fP is the same as simply
omitting this option entirely (i.e. the default), and \fBnested\fP prints out
a nested namespace tree.
.sp
New in version 1.1.

.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\-\-shortlist\fP, \fI\-\-list\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-g HOST, \-\-gateway=HOST
Sets \fIenv.gateway\fP to \fBHOST\fP host string.
.sp
New in version 1.5.

.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Displays a standard help message, with all possible options and a brief
overview of what they do, then exits.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-hide=LEVELS
A comma\-separated list of \fBoutput levels\fP to hide by
default.
.UNINDENT
.INDENT 0.0
.TP
.B \-H HOSTS, \-\-hosts=HOSTS
Sets \fIenv.hosts\fP to the given comma\-delimited list of host
strings.
.UNINDENT
.INDENT 0.0
.TP
.B \-x HOSTS, \-\-exclude\-hosts=HOSTS
Sets \fIenv.exclude_hosts\fP to the given comma\-delimited
list of host strings to then keep out of the final host list.
.sp
New in version 1.1.

.UNINDENT
.INDENT 0.0
.TP
.B \-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) \fIenv.key_filename\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-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
\fIenv.password\fP\&.
.sp
This is useful for fire\-and\-forget runs (especially parallel sessions, in
which runtime input is not possible) when setting the password via
\fI\-\-password\fP or by setting \fIenv.password\fP in
your fabfile, is undesirable.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The value entered into this prompt will \fIoverwrite\fP anything
supplied via \fIenv.password\fP at module level, or via
\fI\-\-password\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fIpassword\-management\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-k
Sets \fIenv.no_keys\fP to \fBTrue\fP, forcing the SSH layer to not
look for SSH private key files in one\(aqs home directory.
.sp
New in version 0.9.1.

.UNINDENT
.INDENT 0.0
.TP
.B \-\-keepalive=KEEPALIVE
Sets \fIenv.keepalive\fP to the given (integer) value, specifying an SSH keepalive interval.
.sp
New in version 1.1.

.UNINDENT
.INDENT 0.0
.TP
.B \-\-linewise
Forces output to be buffered line\-by\-line instead of byte\-by\-byte. Often useful or required for \fIparallel execution\fP\&.
.sp
New in version 1.3.

.UNINDENT
.INDENT 0.0
.TP
.B \-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\(aqs docstring, if it
has one, next to it (truncating if necessary.)
.sp
Changed in version 0.9.1: Added docstring to output.

.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\-\-shortlist\fP, \fI\-\-list\-format\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-p PASSWORD, \-\-password=PASSWORD
Sets \fIenv.password\fP to the given string; it will then be
used as the default password when making SSH connections or calling the
\fBsudo\fP program.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\-\-initial\-password\-prompt\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-P, \-\-parallel
Sets \fIenv.parallel\fP to \fBTrue\fP, causing
tasks to run in parallel.
.sp
New in version 1.3.

.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fB/usage/parallel\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-pty
Sets \fIenv.always_use_pty\fP to \fBFalse\fP, causing all
\fBrun\fP/\fBsudo\fP calls to behave as if
one had specified \fBpty=False\fP\&.
.sp
New in version 1.0.

.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-reject\-unknown\-hosts
Sets \fIenv.reject_unknown_hosts\fP to \fBTrue\fP,
causing Fabric to abort when connecting to hosts not found in the user\(aqs SSH
\fBknown_hosts\fP file.
.UNINDENT
.INDENT 0.0
.TP
.B \-R ROLES, \-\-roles=ROLES
Sets \fIenv.roles\fP to the given comma\-separated list of role
names.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
fab \-\-set password=foo \-\-password=bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will result in \fBenv.password = \(aqbar\(aq\fP, not \fB\(aqfoo\(aq\fP
.sp
Multiple \fBKEY=VALUE\fP pairs may be comma\-separated, e.g. \fBfab \-\-set
var1=val1,var2=val2\fP\&.
.sp
Other than basic string values, you may also set env vars to True by
omitting the \fB=VALUE\fP (e.g. \fBfab \-\-set KEY\fP), and you may set values to
the empty string (and thus a False\-equivalent value) by keeping the equals
sign, but omitting \fBVALUE\fP (e.g. \fBfab \-\-set KEY=\fP\&.)
.sp
New in version 1.4.

.UNINDENT
.INDENT 0.0
.TP
.B \-s SHELL, \-\-shell=SHELL
Sets \fIenv.shell\fP to the given string, overriding the default
shell wrapper used to execute remote commands.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-shortlist
Similar to \fI\-\-list\fP, but without any embellishment, just task
names separated by newlines with no indentation or docstrings.
.sp
New in version 0.9.2.

.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\-\-list\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-show=LEVELS
A comma\-separated list of \fBoutput levels\fP to
be added to those that are shown by
default.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fBrun\fP, \fBsudo\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ssh\-config\-path
Sets \fIenv.ssh_config_path\fP\&.
.sp
New in version 1.4.

.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fIssh\-config\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-skip\-bad\-hosts
Sets \fIenv.skip_bad_hosts\fP, causing Fabric to skip
unavailable hosts.
.sp
New in version 1.4.

.UNINDENT
.INDENT 0.0
.TP
.B \-\-skip\-unknown\-tasks
Sets \fIenv.skip_unknown_tasks\fP, causing Fabric to skip
unknown tasks.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fIenv.skip_unknown_tasks\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-timeout=N, \-t N
Set connection timeout in seconds. Sets \fIenv.timeout\fP\&.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fIenv.timeout\fP,
\fIenv.connection_attempts\fP
.UNINDENT
.UNINDENT
.sp
New in version 1.4.

.UNINDENT
.INDENT 0.0
.TP
.B \-\-command\-timeout=N, \-T N
Set remote command timeout in seconds. Sets
\fIenv.command_timeout\fP\&.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fIenv.command_timeout\fP,
.UNINDENT
.UNINDENT
.sp
New in version 1.6.

.UNINDENT
.INDENT 0.0
.TP
.B \-u USER, \-\-user=USER
Sets \fIenv.user\fP to the given string; it will then be used as the
default username when making SSH connections.
.UNINDENT
.INDENT 0.0
.TP
.B \-V, \-\-version
Displays Fabric\(aqs version number, then exits.
.UNINDENT
.INDENT 0.0
.TP
.B \-w, \-\-warn\-only
Sets \fIenv.warn_only\fP to \fBTrue\fP, causing Fabric to
continue execution even when commands encounter error conditions.
.UNINDENT
.INDENT 0.0
.TP
.B \-z, \-\-pool\-size
Sets \fIenv.pool_size\fP, which specifies how many processes
to run concurrently during parallel execution.
.sp
New in version 1.3.

.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fB/usage/parallel\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Per\-task arguments
.sp
The options given in \fIcommand\-line\-options\fP apply to the invocation of
\fBfab\fP 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\(aqs often desirable to pass in arguments to them at runtime.
.sp
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:
.INDENT 0.0
.IP \(bu 2
Use a colon (\fB:\fP) to separate the task name from its arguments;
.IP \(bu 2
Use commas (\fB,\fP) to separate arguments from one another (may be escaped
by using a backslash, i.e. \fB\e,\fP);
.IP \(bu 2
Use equals signs (\fB=\fP) for keyword arguments, or omit them for positional
arguments. May also be escaped with backslashes.
.UNINDENT
.sp
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.)
.sp
For example, a "create a new user" task might be defined like so (omitting most
of the actual logic for brevity):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def new_user(username, admin=\(aqno\(aq, comment="No comment provided"):
    print("New User (%s): %s" % (username, comment))
    pass
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can specify just the username:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab new_user:myusername
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or treat it as an explicit keyword argument:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab new_user:username=myusername
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If both args are given, you can again give them as positional args:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab new_user:myusername,yes
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or mix and match, just like in Python:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab new_user:myusername,admin=yes
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBprint\fP call above is useful for illustrating escaped commas, like
so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab new_user:myusername,admin=no,comment=\(aqGary\e, new developer (starts Monday)\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
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.
.UNINDENT
.UNINDENT
.sp
All of the above are translated into the expected Python function calls. For
example, the last call above would become:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> new_user(\(aqmyusername\(aq, admin=\(aqyes\(aq, comment=\(aqGary, new developer (starts Monday)\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Roles and hosts
.sp
As mentioned in \fIthe section on task execution\fP,
there are a handful of per\-task keyword arguments (\fBhost\fP, \fBhosts\fP,
\fBrole\fP and \fBroles\fP) which do not actually map to the task functions
themselves, but are used for setting per\-task host and/or role lists.
.sp
These special kwargs are \fBremoved\fP from the args/kwargs sent to the task
function itself; this is so that you don\(aqt run into TypeErrors if your task
doesn\(aqt define the kwargs in question. (It also means that if you \fBdo\fP define
arguments with these names, you won\(aqt be able to specify them in this manner \-\-
a regrettable but necessary sacrifice.)
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
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.
.UNINDENT
.UNINDENT
.sp
When using the plural form of these arguments, one must use semicolons (\fB;\fP)
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\(aqll want to quote the host list string to prevent shell
interpretation, e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ fab new_user:myusername,hosts="host1;host2"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Again, since the \fBhosts\fP kwarg is removed from the argument list sent to the
\fBnew_user\fP task function, the actual Python invocation would be
\fBnew_user(\(aqmyusername\(aq)\fP, and the function would be executed on a host list
of \fB[\(aqhost1\(aq, \(aqhost2\(aq]\fP\&.
.SS Settings files
.sp
Fabric currently honors a simple user settings file, or \fBfabricrc\fP (think
\fBbashrc\fP but for \fBfab\fP) which should contain one or more key\-value pairs,
one per line. These lines will be subject to \fBstring.split(\(aq=\(aq)\fP, and thus
can currently only be used to specify string settings. Any such key\-value pairs
will be used to update \fBenv\fP when \fBfab\fP runs, and is loaded prior
to the loading of any fabfile.
.sp
By default, Fabric looks for \fB~/.fabricrc\fP, and this may be overridden by
specifying the \fI\-c\fP flag to \fBfab\fP\&.
.sp
For example, if your typical SSH login username differs from your workstation
username, and you don\(aqt want to modify \fBenv.user\fP in a project\(aqs fabfile
(possibly because you expect others to use it as well) you could write a
\fBfabricrc\fP file like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
user = ssh_user_name
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then, when running \fBfab\fP, your fabfile would load up with \fBenv.user\fP set to
\fB\(aqssh_user_name\(aq\fP\&. Other users of that fabfile could do the same, allowing
the fabfile itself to be cleanly agnostic regarding the default username.
.SH "AUTHOR"
.PP
Fabric was written by Christian Vest Hansen <karmazilla@gmail.com>.
.PP
This manual was generated based on Fabric's documentation by Andrew Starr-Bochicchio
<asb@debian.org> for the Debian project (but may be used by others).
.SH "SEE ALSO"
.IP
\fBssh\fP\fB(1)\fP