环境字典 env

Fabric 中有一个简单但是必不可少的部分叫做“环境”:它是 Python 字典的子类,既用作设置,也用于任务间数据空间共享。

目前,环境字典 fabric.state.env 是作为全局的单例实现的,为方便使用也包含在 fabric.api 中。 env 中的键通常也被称为“环境变量”。

运行环境即设置

Fabric 的大部分行为可以通过修改 env 变量,例如 env.hosts ,来控制(已经在 入门导览 中见过)。其他经常需要修改的环境变量包括:

  • user :Fabric 在建立 SSH 连接时默认使用本地用户名,必要情况下可以通过修改 env.user 来设置。 Execution model 文档中还介绍了如何为每个主机单独设置用户名。

  • password :用来显式设置默认连接或者在需要的时候提供 sudo 密码。如果没有设置密码或密码错误,Fabric 将会提示你输入。

  • warn_only:布尔值,用来设置 Fabric 是否在检测到远程错误时退出。访问 Execution model 以了解更多关于此行为的信息。

除了这些以外还有很多其它环境变量, 环境变量完整列表 文档的底部提供了完整的列表。

settings 会话管理器

很多时候,只需要临时修改 env 变量来修改指定设置很有必要。Fabric 提供了会话管理器 settings 上下文管理器,接受一个或多个键/值对参数,用于修改其代码块内部的 env

在下面的几种情况下 warn_only 设置非常有必要。需要设置环境变量应用的范围,你可以参照下面 contrib exists 函数的简化版,使用 settings(warn_only=True)

from fabric.api import settings, run

def exists(path):
    with settings(warn_only=True):
        return run('test -e %s' % path)

查看 上下文管理器 API 文档以了解关于 settings 和其它类似工具的细节。

环境即状态共享

如前面所提,env 对象是字典的子类,所以你也可以在 fabfile 代码中将信息保存在这里。有些时候,比如对于一次运行的多个任务间保存状态,会很有用。

注解

env 的这种用法很有历史渊源,在早期版本中 fabfile 不是纯 Python,因此环境是任务间通信的唯一方式。而现在,你可以直接调用其他任务或子功能,并维护模块级别的状态共享。

在未来的版本,Fabric 将变得线程安全,env 将可能成为保持全局状态的唯一简单/安全的方式。

其他考虑

env 虽然是 dict 的子类,但它也做了些修改,以支持属性访问的方式进行读/写,这在前面也有所体现。换句话说, .host_stringenv['host_string'] 的作用是完全一样的。我们感觉属性访问通常可以少打一些打字,同时能增强代码的可读性,所以这也是推荐的与 env 交互的方式。

作为字典在其他方面也很有用,例如,需要往字符串中插入多个环境变量时,通过 Python 基于 dict 的字符串格式化显得尤其方便。“普通”的字符串格式化是这样的:

print("Executing on %s as %s" % (env.host, env.user))

使用字典格式化字符串更加简短,可读性也更好:

print("Executing on %(host)s as %(user)s" % env)

环境变量完整列表

以下是所有预定义(或在 Fabric 运行时定义)的环境变量的完整列表。它们中的大部分都可以直接操作,但最好还是使用 context_managers ,可以通过 settings 或特定的上下文管理器,如 cd

需注意的是它们中的大部分可以通过 fab 的命令行参数来设置,详细文档参见 fab 选项和参数 。合适的时候也可以使用交叉引用。

参见

--set

abort_exception

Default: None

通常情况下,Fabric 处理错误的方式是先打印错误信息至 stderr,然后调用 sys.exit(1)。这项设置提供覆盖这个默认行为(即设置 env.abort_exceptionNone )。

它接受一个接受单个字符串变量(需要打印的错误信息)的可调用对象,并返回一个异常实例。这样 Fabric 就会抛出该异常,而非 退出系统 (如 sys.exit 所做)

大部分情况下,你可以简单地将它设置为一个异常类,因为它完美地符合了上面的要求(可调用、接受一个字符串、返回一个异常实例)。例如: env.abort_exception = MyExceptionClass

abort_on_prompts

Default: False

当这个值为 True 时,Fabric 将以非交互模式运行。此模式下,任何需要提示用户输入(如提示输入密码、询问连接到哪个主机、fabfile 中触发的 prompt 等等)时,都会调用 abort 。这就保证 Fabric 会话总是明确地中止,而不是在某些意外的情况下傻傻地等待用户输入。

1.1 新版功能.

all_hosts

Default: []

由 fab 设置的当前正在执行命令的主机列表。仅用于显示信息。

always_use_pty

Default: True

设置为 False 时, ~fabric.operations.run`/`~fabric.operations.sudo` 的行为会和使用 ``pty=False 参数调用一样。

参见

--no-pty

1.0 新版功能.

colorize_errors

Default False

设置为 True 时,终端输出的错误信息会显示为红色,警告信息则是洋红色,以突出它们的显示。

1.7 新版功能.

combine_stderr

Default: True

使 SSH 层合并远程程序的 stdout 和 stderr 流输出,以避免它们在打印时混在一起。查看 合并 stdout 和 stderr 来了解为什么需要这个功能,以及它的实际效果。

1.0 新版功能.

command

Default: None

fab 设置的正在执行的命令名称(例如,执行 $ fab task1 task2 命令,当执行 task1 时, env.command 会被设置为 “task1” ,然后设置为 “task2” )。仅供显示。

command_prefixes

Default: []

通过 prefix 来修改,并会附加在由 run/sudo 执行的命令前面。

1.0 新版功能.

command_timeout

Default: None

远程命令的超时时间,单位为秒。

1.6 新版功能.

connection_attempts

Default: 1

Fabric 连接一台新服务器的重试次数。出于向后兼容的目的,它默认只尝试连接一次。

1.4 新版功能.

cwd

Default: ''

当前工作目录,用于 cd 上下文管理器保持状态。

dedupe_hosts

Default: True

去除合并后的主机列表中的重复项,以保证一个主机只会出现一次。(例如,在同时使用 @hosts@roles ,或 -H 和 -R 的时候。)

设置为 False 时不会去除重复项,这将允许用户显式地在同一台主机上将一个任务(并行地,当然也支持串行)运行多次。

1.5 新版功能.

disable_known_hosts

Default: False

如果为 True ,SSH 层将不会加载用户的 know-hosts 文件。这样可以有效地避免当一个“已知主机”改变了 key、但仍然有效时(比如 EC2 这样的云服务器中)的异常。

eagerly_disconnect

Default: False

设置为 True 时, fab 会在每个独立任务完成后关闭连接,而不是在整个运行结束后。这有助于避免大量无用的网络会话堆积,或因每个进程可打开的文件限制,或网络硬件的限制而引发问题。

注解

激活时,断开连接地信息会贯穿你的输出信息始终,而非最后。这一点可能会在以后的版本中得到改进。

effective_roles

Default: []

fab 设置的当前正在执行命令的角色列表。仅供显示。

1.9 新版功能.

exclude_hosts

Default: []

指定一个主机串列表, fab 执行期间会跳过列表中的主机。通常通过 --exclude-hosts/-x 来设置。

1.1 新版功能.

fabfile

Default: fabfile.py

fab 在加载 fabfile 时查找的文件名。要指定特定的 fabfile 文件,需要使用该文件的完整路径。显然,这个参数不可能在 fabfile 中设置,但可以将它设置在 .fabricrc 文件中,或者通过命令行参数来设置。

gateway

Default: None

允许通过指定主机创建 SSH 驱动的网关。它的值应该是一个普通的 Fabric 主机串,和 env.host_string 中使用的一样。当它被设置时,新创建的连接将会通过这个远程 SSH 连接到最终的目的地。

1.5 新版功能.

参见

--gateway

host_string

Default: None

指定 Fabric 在执行 runput 等命令时使用的用户/主机/端口。 fab 在与已设置的主机列表交互时设置这个值,将 Fabric 作为库使用时也可以手动设置它。

forward_agent

Default: False

值为 True 时允许本地 SSH 代理连接远程终端时跳转(forwarding)。

1.4 新版功能.

host

Default: None

设置使用 fabenv.host_string 的主机名部分,仅用于传递信息目的。

hosts

Default: []

组合任务对应主机列表时会包含的全局主机列表。

keepalive

默认值: 0 (不保持连接)

用于指定 SSH keepalive 间隔的数字,基本上对应 SSH 设置参数 ServerAliveInterval。如果有多事的网络硬件或者其它因素导致连接超时时会很有帮助。

参见

--keepalive

1.1 新版功能.

key

Default: None

一个字符串或者类似文件的对象,包含了 SSH 密钥。用于连接的身份认证。

注解

最常见的 SSH 密钥用法是设置 key_filename

1.7 新版功能.

key_filename

Default: None

字符串类型或者字符串列表,指向用于连接的 SSH 密钥文件。它将被肢解传给 SSH 层,可以使用 -i 选项添加/新增。

linewise

Default: False

强制以行为缓冲区单位,以替换字符/比特,通常用在并行模式下。可以使用 --linewise 参数来激活。env.parallel 模式隐含了这项设置——即使 linewise 为 False,parallel 如果为 True 就会引发行级输出。

1.3 新版功能.

local_user

一个包含本地系统用户名的只读值。该值即 user 的初始值,不过 user 可以通过 CLI 参数、Python 代码或者指定 host 字符串的方式覆盖,local_user 则会一直保持不变。

no_agent

Default: False

如为 True 则告诉 SSH 层使用密钥进行身份验证时不使用代理。

0.9.1 新版功能.

参见

--no_agent

no_keys

Default: False

如为 True 则告诉 SSH 层不从 $HOME/.ssh/ 目录加载密钥。(当然,你可以显示地使用 fab -i 来指定密钥。)

0.9.1 新版功能.

参见

-k

parallel

Default: False

如为 True,强制所有任务并行执行。隐式指定 env.linewise

1.3 新版功能.

password

Default: None

SSH 层连接原程主机 以及/或者 sudo 时使用的默认密码。

passwords

Default: {}

这个字典主要用于内部使用,and is filled automatically as a per-host-string password cache。键是 host strings 全称,值为密码(字符串格式)。

警告

如果你手动生成该字典,就必须使用完整的主机登录字符,包括用户和登录信息。查看上面的链接以获取主机字符串 API 的详细信息。

1.0 新版功能.

path

Default: ''

用于执行 run/sudo/local 等命令时设置 shell 环境变量 $PATH。推荐使用上下文管理器 path 来管理该值,不建议手动设置。

1.0 新版功能.

pool_size

Default: 0

设置并行执行任务时并发的进程数。

1.3 新版功能.

prompts

Default: {}

prompts 字典允许用户控制交互行为。如果命令标准输出流中出现了字典中的减,Fabric 会立刻以对应的值作为回答。

1.9 新版功能.

port

Default: None

fab 在迭代主机列表时设置的 env.host_string 的端口部分。也可以用于设置默认端口。

real_fabfile

Default: None

fab 所设置的已加载的 fabfile 的真正位置,仅用于获取信息目的。

remote_interrupt

Default: None

用于设置 Ctrl-C 是用于终止远程命令还是在本地捕获。使用如下:

  • None (默认值):只有 open_shell 会向远程发送终止命令,run/sudo 会在本地捕获。

  • False:即使 open_shell 也只在本地捕获。

  • True:所有函数都可以向远程发送终止命令。

1.6 新版功能.

rcfile

Default: $HOME/.fabricrc

加载用户本地 Fabric 配置文件的位置。

reject_unknown_hosts

Default: False

设置为 True 时,SSH 层在连接到用户 know-hosts 列表之外的的主机时会抛出异常。

system_known_hosts

Default: None

只能设置为 known_hosts 文件路径。SSH 层在读取用户 known-hosts文件前会先读取该文件。

参见

SSH 行为

roledefs

Default: {}

定义角色名和主机列表的映射字典。

roles

Default: []

按任务足额和主机列表时使用的全局任务列表。

shell

Default: /bin/bash -l -c

在使用 run 等命令时会使用到,作为 shell 包裹在程序外。该值会像这样使用 <env.shell> "<command goes here>"——比如默认的 Bash -c 选项可以接受命令字符串作为其参数。

skip_bad_hosts

Default: False

如果为 Truefab``(或者其它非 ``fab 命令引起的 execute 调用)会跳过不存在的主机。

1.4 新版功能.

skip_unknown_tasks

Default: False

如果为 Truefab``(或者其它非 ``fab 命令引起的 execute 调用)会跳过不存在的任务而不会报错跳出。

ssh_config_path

Default: $HOME/.ssh/config

用于设置备用 SSH 配置文件路径。

1.4 新版功能.

ok_ret_codes

Default: [0]

列表中的代码用于标记 run/sudo/sudo 命令是否成功调用了。

1.6 新版功能.

sudo_prefix

Default: "sudo -S -p '%(sudo_prompt)s' " % env

sudo 命令调用时的 sudo 命令前缀。如果用户在远程主机默认 $PATH``上没有 ``sudo,或者需要一些其它设置时(比如应用无密码的 sudo 时删除 -p 参数),会需要它。

参见

sudo 操作、env.sudo_prompt

sudo_prompt

Default: "sudo password:"

传递给远程系统的 sudo 程序,Fabric 可以通过它正确识别密码输入请求。

sudo_user

Default: None

sudouser 参数为 None 时使用的回调值。和 settings 一起使用时能起到很大作用。

参见

sudo

tasks

Default: []

fab 设置,应用于当前执行的所有任务列表。仅用于信息目的。

timeout

Default: 10

网络连接超时时间,单位为秒。

1.4 新版功能.

use_shell

Default: True

全局设置参数,作用类似于 run/sudoshell 参数:如果设置为 False,操作命令将不会包裹在 env.shell 中。

use_ssh_config

Default: False

设置为 True Fabric 将会导入本地 SSH 配置文件。

1.4 新版功能.

user

Default: 用户的默认用户名

SSH 层连接远程服务器时用到的用户名,可以设置为全局,在不显式指定的情况下都会被应用于主机连接字符串。不过,如果显式指定了,它将被临时覆盖为该值——例如,它可以永远是连接时使用的用户。

下面我们使用一个 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)

用于:

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

如你所见,在 host2 上运行时 env.user 被设置为了 "explicit_user",但是之后又重新设置为原来的值("implicit_user")。

注解

``env.user``的使用有点让人困惑(它同时用于设置 信息展示目的),因此未来可能会对其进行修改——信息展示可能会另外采取一个新的 env 变量。

version

Default: 字符串格式的当前 Fabric 版本号

为了获取有用信息,通常不建议修改,不过修改了也不会导致程序错误。

参见

--version

warn_only

Default: False

指定在 run / sudo / local 遇到错误时究竟是警告还是退出。