Please note
This version of Fabric is outdated. If you're looking for the latest stable release, please click here.
A simple but integral aspect of Fabric is what is known as the “environment”: a Python dictionary subclass which is used as a combination settings registry and shared inter-task data namespace.
The environment dict is currently implemented as a global singleton, fabric.state.env, and is included in fabric.api for convenience. Keys in env are sometimes referred to as “env variables”.
Most of Fabric’s behavior is controllable by modifying env variables, such as env.hosts (as seen in the tutorial). Other commonly-modified env vars include:
There are a number of other env variables; for the full list, see Full list of env vars at the bottom of this document.
In many situations, it’s useful to only temporarily modify env vars so that a given settings change only applies to a block of code. Fabric provides a settings context manager, which takes any numbr of key/value pairs and will use them to modify env within its wrapped block.
For example, there are many situations where setting warn_only (see below) is useful. To apply it to a few lines of code, use settings(warn_only=True), as seen in this simplified version of the contrib exists function:
from fabric.api import settings, run
def exists(path):
with settings(warn_only=True):
return run('test -e %s' % path)
See the Context Managers API documentation for details on settings and other, similar tools.
While it subclasses dict, Fabric’s env has been modified so that its values may be read/written by way of attribute access, as seen in some of the above material. In other words, env.host_string and env['host_string'] are functionally identical. We feel that attribute access can often save a bit of typing and makes the code more readable, so it’s the recommended way to interact with env.
The fact that it’s a dictionary can be useful in other ways, such as with Python’s dict-based string interpolation, which is especially handy if you need to insert multiple env vars into a single string. Using “normal” string interpolation might look like this:
print("Executing on %s as %s" % (env.host, env.user))
Using dict-style interpolation is more readable and slightly shorter:
print("Executing on %(host)s as %(user)s" % env)
Below is a list of all predefined (or defined by Fabric itself during execution) environment variables. While any of them may be manipulated directly, it’s often best to use context_managers, either generally via settings or via specific context managers such as cd.
Note that many of these may be set via fab‘s command-line switches – see fab options and arguments for details. Cross-links will be provided where appropriate.
Default: None
Set by fab to the full host list for the currently executing command. For informational purposes only.
See also
Default: None
Set by fab to the currently executing command name (e.g. when executed as $ fab task1 task2, env.command will be set to "task1" while task1 is executing, and then to "task2".) For informational purposes only.
See also
Default: False
If True, the SSH layer will skip loading the user’s known-hosts file. Useful for avoiding exceptions in situations where a “known host” changing its host key is actually valid (e.g. cloud servers such as EC2.)
See also
Default: fabfile.py
Filename which fab searches for when loading fabfiles. Obviously, it doesn’t make sense to set this in a fabfile, but it may be specified in a .fabricrc file or on the command line.
See also
Default: None
Defines the current user/host/port which Fabric will connect to when executing run, put and so forth. This is set by fab when iterating over a previously set host list, and may also be manually set when using Fabric as a library.
See also
Default: None
Set to the hostname part of env.host_string by fab. For informational purposes only.
Default: None
May be a string or list of strings, referencing file paths to SSH key files to try when connecting. Passed through directly to the SSH layer. May be set/appended to with -i.
A read-only value containing the local system username. This is the same value as user‘s initial value, but whereas user may be altered by CLI arguments, Python code or specific host strings, local_user will always contain the same value.
Default: False
If True, will tell Paramiko not to seek out running SSH agents when using key-based authentication.
New in version 0.9.1.
Default: False
If True, will tell Paramiko not to load any private key files from one’s $HOME/.ssh/ folder. (Key files explicitly loaded via fab -i will still be used, of course.)
New in version 0.9.1.
Default: None
The password used by the SSH layer when connecting to remote hosts, and/or when answering sudo prompts.
When empty, the user will be prompted, with the result stored in this env variable and used for connecting/sudoing. (In other words, setting this prior to runtime is not required, though it may be convenient in some cases.)
Given a session where multiple different passwords are used, only the first one will be stored into env.password. Put another way, the only time env.password is written to by Fabric itself is when it is empty. This may change in the future.
See also
Default: None
Set to the port part of env.host_string by fab when iterating over a host list. For informational purposes only.
Default: None
Set by fab with the path to the fabfile it has loaded up, if it got that far. For informational purposes only.
See also
Default: False
If True, the SSH layer will raise an exception when connecting to hosts not listed in the user’s known-hosts file.
See also
Default: /bin/bash -l -c
Value used as shell wrapper when executing commands with e.g. run. Must be able to exist in the form <env.shell> "<command goes here>" – e.g. the default uses Bash’s -c option which takes a command string as its value.
See also
Default: sudo password:
Passed to the sudo program on remote systems so that Fabric may correctly identify its password prompt. This may be modified by fabfiles but there’s no real reason to.
See also
The sudo operation
Default: True
Global setting which acts like the use_shell argument to run/sudo: if it is set to False, operations will not wrap executed commands in env.shell.
Default: User’s local username
The username used by the SSH layer when connecting to remote hosts. May be set globally, and will be used when not otherwise explicitly set in host strings. However, when explicitly given in such a manner, this variable will be temporarily overwritten with the current value – i.e. it will always display the user currently being connected as.
To illustrate this, a fabfile:
from fabric.api import env, run
env.user = 'implicit_user'
env.hosts = ['host1', 'explicit_user@host2', 'host3']
def print_user():
with hide('running'):
run('echo "%(user)s"' % env)
and its use:
$ fab print_user
[host1] out: implicit_user
[explicit_user@host2] out: explicit_user
[host3] out: implicit_user
Done.
Disconnecting from host1... done.
Disconnecting from host2... done.
Disconnecting from host3... done.
As you can see, during execution on host2, env.user was set to "explicit_user", but was restored to its previous value ("implicit_user") afterwards.
Note
env.user is currently somewhat confusing (it’s used for configuration and informational purposes) so expect this to change in the future – the informational aspect will likely be broken out into a separate env variable.
See also
Default: current Fabric version string
Mostly for informational purposes. Modification is not recommended, but probably won’t break anything either.