fab - Online in the Cloud

PROGRAM:

NAME

fab - Simple Pythonic remote deployment tool

SYNOPSIS

fab [commands ...]

DESCRIPTION

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.

USAGE

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

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:
env.connection_attempts, env.timeout

New in version 1.4.

-D, --disable-known-hosts
Sets env.disable_known_hosts to True, preventing Fabric from loading the user's SSH
known_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:
fabfiles

-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), and nested prints out a nested namespace tree.

New in version 1.1.

SEE ALSO:
--shortlist, --list

-g HOST, --gateway=HOST
Sets env.gateway to HOST host string.

New in version 1.5.

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

-H HOSTS, --hosts=HOSTS
Sets env.hosts to the given comma-delimited list of host strings.

-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:
password-management

-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:
--shortlist, --list-format

-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:
--initial-password-prompt

-P, --parallel
Sets env.parallel to True, causing tasks to run in parallel.

New in version 1.3.

SEE ALSO:
/usage/parallel

--no-pty
Sets env.always_use_pty to False, causing all run/sudo calls to behave as if one
had specified pty=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 SSH known_hosts file.

-R ROLES, --roles=ROLES
Sets env.roles to the given comma-separated list of role names.

--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 omitting VALUE (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:
--list

--show=LEVELS
A comma-separated list of output levels to be added to those that are shown by
default.

SEE ALSO:
run, sudo

--ssh-config-path
Sets env.ssh_config_path.

New in version 1.4.

SEE ALSO:
ssh-config

--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:
env.skip_unknown_tasks

--timeout=N, -t N
Set connection timeout in seconds. Sets env.timeout.

SEE ALSO:
env.timeout, env.connection_attempts

New in version 1.4.

--command-timeout=N, -T N
Set remote command timeout in seconds. Sets env.command_timeout.

SEE ALSO:
env.command_timeout,

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:
/usage/parallel

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.

Use fab online using onworks.net services