The environment dictionary, env
¶
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”.
Environment as configuration¶
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:
user
: Fabric defaults to your local username when making SSH connections, but you can useenv.user
to override this if necessary. The Execution model documentation also has info on how to specify usernames on a per-host basis.password
: Used to explicitly set your default connection or sudo password if desired. Fabric will prompt you when necessary if this isn’t set or doesn’t appear to be valid.warn_only
: a Boolean setting determining whether Fabric exits when detecting errors on the remote end. See Execution model for more on this behavior.
There are a number of other env variables; for the full list, see Full list of env vars at the bottom of this document.
The settings
context manager¶
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 number 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.
Other considerations¶
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)
Full list of env vars¶
Below is a list of all predefined (or defined by Fabric itself during
execution) environment variables. While many 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-references are provided where appropriate.
参见
abort_exception
¶
Default: None
Fabric normally handles aborting by printing an error message to stderr and
calling sys.exit(1)
. This setting allows you to override that behavior
(which is what happens when env.abort_exception
is None
.)
Give it a callable which takes a string (the error message that would have been
printed) and returns an exception instance. That exception object is then
raised instead of SystemExit
(which is what sys.exit
does.)
Much of the time you’ll want to simply set this to an exception class, as those
fit the above description perfectly (callable, take a string, return an
exception instance.) E.g. env.abort_exception = MyExceptionClass
.
abort_on_prompts
¶
Default: False
When True
, Fabric will run in a non-interactive mode, calling
abort
anytime it would normally prompt the user for input (such
as password prompts, “What host to connect to?” prompts, fabfile invocation of
prompt
, and so forth.) This allows users to ensure a Fabric
session will always terminate cleanly instead of blocking on user input forever
when unforeseen circumstances arise.
1.1 新版功能.
all_hosts
¶
Default: []
Set by fab
to the full host list for the currently executing command. For
informational purposes only.
always_use_pty
¶
Default: True
When set to False
, causes run
/sudo
to act as if they have been called with pty=False
.
参见
1.0 新版功能.
colorize_errors
¶
Default False
When set to True
, error output to the terminal is colored red and warnings
are colored magenta to make them easier to see.
1.7 新版功能.
combine_stderr
¶
Default: True
Causes the SSH layer to merge a remote program’s stdout and stderr streams to avoid becoming meshed together when printed. See Combining stdout and stderr for details on why this is needed and what its effects are.
1.0 新版功能.
command
¶
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.
command_prefixes
¶
Default: []
Modified by prefix
, and prepended to commands
executed by run
/sudo
.
1.0 新版功能.
connection_attempts
¶
Default: 1
Number of times Fabric will attempt to connect when connecting to a new server. For backwards compatibility reasons, it defaults to only one connection attempt.
1.4 新版功能.
dedupe_hosts
¶
Default: True
Deduplicate merged host lists so any given host string is only represented once
(e.g. when using combinations of @hosts
+ @roles
, or -H
and
-R
.)
When set to False
, this option relaxes the deduplication, allowing users
who explicitly want to run a task multiple times on the same host (say, in
parallel, though it works fine serially too) to do so.
1.5 新版功能.
disable_known_hosts
¶
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.)
eagerly_disconnect
¶
Default: False
If True
, causes fab
to close connections after each individual task
execution, instead of at the end of the run. This helps prevent a lot of
typically-unused network sessions from piling up and causing problems with
limits on per-process open files, or network hardware.
注解
When active, this setting will result in the disconnect messages appearing throughout your output, instead of at the end. This may be improved in future releases.
effective_roles
¶
Default: []
Set by fab
to the roles list of the currently executing command. For
informational purposes only.
exclude_hosts
¶
Default: []
Specifies a list of host strings to be skipped over
during fab
execution. Typically set via --exclude-hosts/-x
.
1.1 新版功能.
fabfile
¶
Default: fabfile.py
Filename pattern which fab
searches for when loading fabfiles.
To indicate a specific file, use the full path to the file. 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.
gateway
¶
Default: None
Enables SSH-driven gatewaying through the indicated host. The value should be a normal Fabric host string as used in e.g. env.host_string. When this is set, newly created connections will be set to route their SSH traffic through the remote SSH daemon to the final destination.
1.5 新版功能.
参见
host_string
¶
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.
forward_agent
¶
Default: False
If True
, enables forwarding of your local SSH agent to the remote end.
1.4 新版功能.
host
¶
Default: None
Set to the hostname part of env.host_string
by fab
. For informational
purposes only.
keepalive
¶
Default: 0
(i.e. no keepalive)
An integer specifying an SSH keepalive interval to use; basically maps to the
SSH config option ClientAliveInterval
. Useful if you find connections are
timing out due to meddlesome network hardware or what have you.
参见
1.1 新版功能.
key
¶
Default: None
A string, or file-like object, containing an SSH key; used during connection authentication.
注解
The most common method for using SSH keys is to set key_filename.
1.7 新版功能.
key_filename
¶
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
.
linewise
¶
Default: False
Forces buffering by line instead of by character/byte, typically when running
in parallel mode. May be activated via --linewise
. This option is
implied by env.parallel – even if linewise
is False,
if parallel
is True then linewise behavior will occur.
1.3 新版功能.
local_user
¶
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.
no_agent
¶
Default: False
If True
, will tell the SSH layer not to seek out running SSH agents when
using key-based authentication.
0.9.1 新版功能.
参见
no_keys
¶
Default: False
If True
, will tell the SSH layer 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.)
0.9.1 新版功能.
参见
parallel
¶
Default: False
When True
, forces all tasks to run in parallel. Implies env.linewise.
1.3 新版功能.
password
¶
Default: None
The default password used by the SSH layer when connecting to remote hosts,
and/or when answering sudo
prompts.
passwords
¶
Default: {}
This dictionary is largely for internal use, and is filled automatically as a per-host-string password cache. Keys are full host strings and values are passwords (strings).
1.0 新版功能.
path
¶
Default: ''
Used to set the $PATH
shell environment variable when executing commands in
run
/sudo
/local
.
It is recommended to use the path
context manager
for managing this value instead of setting it directly.
1.0 新版功能.
pool_size
¶
Default: 0
Sets the number of concurrent processes to use when executing tasks in parallel.
1.3 新版功能.
prompts
¶
Default: {}
The prompts
dictionary allows users to control interactive prompts. If a
key in the dictionary is found in a command’s standard output stream, Fabric
will automatically answer with the corresponding dictionary value.
1.9 新版功能.
port
¶
Default: None
Set to the port part of env.host_string
by fab
when iterating over a
host list. May also be used to specify a default port.
real_fabfile
¶
Default: None
Set by fab
with the path to the fabfile it has loaded up, if it got that
far. For informational purposes only.
remote_interrupt
¶
Default: None
Controls whether Ctrl-C triggers an interrupt remotely or is captured locally, as follows:
None
(the default): onlyopen_shell
will exhibit remote interrupt behavior, andrun
/sudo
will capture interrupts locally.False
: evenopen_shell
captures locally.True
: all functions will send the interrupt to the remote end.
1.6 新版功能.
reject_unknown_hosts
¶
Default: False
If True
, the SSH layer will raise an exception when connecting to hosts not
listed in the user’s known-hosts file.
system_known_hosts
¶
Default: None
If set, should be the path to a known_hosts
file. The SSH layer will
read this file before reading the user’s known-hosts file.
参见
shell
¶
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.
skip_bad_hosts
¶
Default: False
If True
, causes fab
(or non-fab
use of execute
) to skip over hosts it can’t connect to.
1.4 新版功能.
ssh_config_path
¶
Default: $HOME/.ssh/config
Allows specification of an alternate SSH configuration file path.
1.4 新版功能.
ok_ret_codes
¶
Default: [0]
Return codes in this list are used to determine whether calls to
run
/sudo
/sudo
are considered successful.
1.6 新版功能.
sudo_prefix
¶
Default: "sudo -S -p '%(sudo_prompt)s' " % env
The actual sudo
command prefixed onto sudo
calls’
command strings. Users who do not have sudo
on their default remote
$PATH
, or who need to make other changes (such as removing the -p
when
passwordless sudo is in effect) may find changing this useful.
参见
The sudo
operation; env.sudo_prompt
sudo_prompt
¶
Default: "sudo password:"
Passed to the sudo
program on remote systems so that Fabric may correctly
identify its password prompt.
参见
The sudo
operation; env.sudo_prefix
sudo_user
¶
Default: None
Used as a fallback value for sudo
‘s user
argument if
none is given. Useful in combination with settings
.
参见
tasks
¶
Default: []
Set by fab
to the full tasks list to be executed for the currently
executing command. For informational purposes only.
use_shell
¶
Default: True
Global setting which acts like the shell
argument to
run
/sudo
: if it is set to False
,
operations will not wrap executed commands in env.shell
.
use_ssh_config
¶
Default: False
Set to True
to cause Fabric to load your local SSH config file.
1.4 新版功能.
user
¶
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.
注解
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.
version
¶
Default: current Fabric version string
Mostly for informational purposes. Modification is not recommended, but probably won’t break anything either.
参见