Provided by: fabric_2.6.0-1_all bug

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.

AUTHOR

       Fabric was written by Christian Vest Hansen <karmazilla@gmail.com>.

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

SEE ALSO

              ssh(1)

                                        September 15, 2015                                 FAB(1)