Skip to main content

环境字典,env

Fabric的一个简单但完整的方面是所谓的“环境”:一个Python字典子类,用作组合设置注册表和共享的任务间数据命名空间。

环境dict目前被实现为全局单例 fabric.state.env,为了方便起见,它被包括在 fabric.api 中。 env 中的键有时称为“env变量”。

环境配置

Fabric的大多数行为可以通过修改 env 变量来控制,例如 env.hosts (如在 教程 中看到的)。其他常用修改的env变量包括:

  • user:在进行SSH连接时,结构默认为您的本地用户名,但是如果需要,您可以使用 env.user 覆盖此。 执行模型 文档还有关于如何在每个主机的基础上指定用户名的信息。

  • password:用于显式设置默认连接或sudo密码(如果需要)。 Fabric将在必要时提示您未设置或不显示有效。

  • warn_only:布尔设置,用于确定是否在检测到远程端的错误时退出。有关此行为的更多信息,请参阅 执行模型

还有一些其他的env变量;有关完整列表,请参阅本文档底部的 env vars的完整列表

settings 上下文管理器

在许多情况下,仅临时修改 env vars是有用的,以便给定的设置更改只适用于一个代码块。 Fabric提供了一个 settings 上下文管理器,它采用任意数量的键/值对,并将使用它们来修改其包装块中的 env

例如,在许多情况下,设置 warn_only (见下文)是有用的。要将其应用于几行代码,请使用 settings(warn_only=True),如 contrib exists 函数的简化版本中所示:

from fabric.api import settings, run

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

有关 settings 和其他类似工具的详细信息,请参阅 上下文管理器 API文档。

环境作为共享状态

如上所述,env 对象只是一个字典子类,所以你自己的fabfile代码也可以存储信息。这有时对于在单个执行运行中保持多个任务之间的状态有用。

注解

env 的这个方面在很大程度上是历史的:在过去,fabfiles不是纯Python,因此环境是任务之间通信的唯一方式。现在,你可以直接调用其他任务或子程序,甚至保持模块级共享状态,如果你愿意。

在未来的版本中,Fabric将变得线程安全,此时 env 可能是保持全局状态的唯一容易/安全的方式。

其他考虑

虽然它是 dict 的子类,但是Fabric的 env 已经被修改,使得它的值可以通过属性访问来读取/写入,如在上述一些材料中所见。换句话说,env.host_stringenv['host_string'] 在功能上相同。我们认为属性访问通常可以节省一点打字,并使代码更可读,因此它是与 env 交互的推荐方法。

事实上,它是一个字典可以在其他方面有用,例如使用Python的基于 dict 的字符串插值,如果你需要插入多个env变量到单个字符串,这是特别方便。使用“正常”字符串插值可能看起来像这样:

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

使用字体样式内插更可读和稍短:

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

env vars的完整列表

下面是所有预定义(或由Fabric自身在执行期间定义的)环境变量的列表。虽然其中许多可以直接操作,但通常最好使用 context_managers,通常通过 settings 或通过特定的上下文管理器(如 cd)。

请注意,其中许多可以通过 fab 的命令行开关设置 - 有关详细信息,请参阅 fab 选项和参数。在适当的地方提供交叉引用。

参见

--set

abort_exception

默认: None

Fabric通常通过将错误消息打印到stderr并调用 sys.exit(1) 来处理中止。此设置允许您覆盖此行为(这是 env.abort_exceptionNone 时会发生的情况)。

给它一个可调用,它接受一个字符串(将打印的错误消息),并返回一个异常实例。然后引发该异常对象,而不是 SystemExit (这是 sys.exit 的作用)。

很多时候你只需要将它设置为一个异常类,因为它们完全符合上面的描述(可调用,接受一个字符串,返回一个异常实例)。 env.abort_exception = MyExceptionClass

abort_on_prompts

默认: False

True,Fabric将以非交互模式运行时,在任何时候调用 abort 通常会提示用户输入(例如密码提示,“要连接到什么主机?”提示,prompt 的fabfile调用等)。这允许用户确保Fabric会话将始终完全终止,而不是在不可预见的情况发生时永远阻止用户输入。

1.1 新版功能.

all_hosts

默认: []

fab 设置为当前正在执行的命令的完整主机列表。仅供参考。

参见

执行模型

always_use_pty

默认: True

当设置为 False 时,使 run/sudo 表现为好像已使用 pty=False 调用。

参见

--no-pty

1.0 新版功能.

colorize_errors

默认 False

当设置为 True 时,到终端的错误输出为红色,警告颜色为品红色,使其更容易看清。

1.7 新版功能.

combine_stderr

默认True

导致SSH层合并远程程序的stdout和stderr流,以避免在打印时互相网格化。有关为什么需要它及其影响的详细信息,请参阅 结合stdout和stderr

1.0 新版功能.

command

默认: None

fab 设置为当前执行的命令名(例如,当以 $ fab task1 task2 执行时,在 task1 执行时,env.command 将被设置为 "task1",然后到 "task2"。)仅供参考。

参见

执行模型

command_prefixes

默认: []

prefix 修改,并添加到 run/sudo 执行的命令。

1.0 新版功能.

command_timeout

默认: None

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

1.6 新版功能.

connection_attempts

默认: 1

连接到新服务器时,Fabric将尝试连接的次数。出于向后兼容性原因,它默认只有一个连接尝试。

1.4 新版功能.

cwd

默认: ''

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

dedupe_hosts

默认: True

重复数据删除合并的主机列表,因此任何给定的主机字符串只表示一次(例如,使用 @hosts + @roles-H-R 的组合时)。

设置为 False 时,此选项可放宽重复数据删除,允许明确想在同一主机上多次运行任务的用户(例如,并行运行,尽管它可以顺序运行)。

1.5 新版功能.

disable_known_hosts

默认: False

如果是 True,SSH层将跳过加载用户的known-hosts文件。用于在“已知主机”改变其主机密钥实际上有效的情况下(例如,诸如EC2的云服务器)避免异常。

eagerly_disconnect

默认: False

如果 True,导致 fab 在每个单独的任务执行后关闭连接,而不是在运行结束。这有助于防止大量通常未使用的网络会话堆积并导致每进程打开文件或网络硬件的限制问题。

注解

激活时,此设置将导致断开连接消息出现在整个输出中,而不是在结束。这可能会在未来的版本中得到改进。

effective_roles

默认: []

fab 设置为当前正在执行的命令的角色列表。仅供参考。

1.9 新版功能.

参见

执行模型

exclude_hosts

默认: []

fab 执行期间指定要作为 跳过 的主机字符串列表。通常通过 --exclude-hosts/-x 设置。

1.1 新版功能.

fabfile

默认: fabfile.py

fab 在加载fabf时搜索的文件名模式。要指示特定文件,请使用文件的完整路径。显然,在fabfile中设置它是没有意义的,但它可以在 .fabricrc 文件中或在命令行上指定。

gateway

默认: None

启用通过指定主机的SSH驱动网关。该值应为正常的Fabric主机字符串,如例如 env.host_string。设置此选项时,新创建的连接将设置为将其SSH流量通过远程SSH守护程序路由到最终目标。

1.5 新版功能.

参见

--gateway

gss_(auth|deleg|kex)

默认: False 的所有。

这三个选项(gss_authgss_deleggss_kex)逐字传递到Paramiko的 Client.connect 方法,并控制Kerberos/GSS-API行为。有关详细信息,请参阅Paramiko的文档:GSS-API身份验证GSS-API密钥交换

注解

此功能需要Paramiko 1.15 或以上!您将获得 TypeError 关于Paramiko 1.14 或更早版本的意外关键字参数,因为它缺少Kerberos支持。

1.11 新版功能.

host_string

默认: None

定义当执行 runput 等时Fabric将连接到的当前用户/主机/端口。这是由 fab 在对先前设置的主机列表进行迭代时设置的,也可以在将Fabric用作库时手动设置。

参见

执行模型

forward_agent

默认: False

如果是 True,则允许将本地SSH代理转发到远程端。

1.4 新版功能.

host

默认: None

通过 fab 设置为 env.host_string 的主机名部分。仅供参考。

hosts

默认: []

编写每任务主机列表时使用的全局主机列表。

keepalive

默认: 0 (即没有keepalive)

指定要使用的SSH保持活动间隔的整数;基本上映射到SSH配置选项 ServerAliveInterval。有用的,如果你发现连接是由于医疗卫生的网络硬件或什么有你的超时。

参见

--keepalive

1.1 新版功能.

key

默认: None

包含SSH密钥的字符串或类文件对象;在连接认证期间使用。

注解

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

1.7 新版功能.

key_filename

默认: None

可能是字符串或字符串列表,引用连接时要尝试的SSH密钥文件的文件路径。直接传递到SSH层。可以设置/附加到 -i

linewise

默认: False

强制按行而不是字符/字节缓冲,通常在并行模式下运行时。可以通过 --linewise 激活。此选项由 env.parallel 隐含 - 即使 linewise 为False,如果 parallel 为True,则将发生linewise行为。

1.3 新版功能.

local_user

包含本地系统用户名的只读值。这与 user 的初始值相同,但是 user 可能由CLI参数,Python代码或特定主机字符串更改,local_user 将始终包含相同的值。

no_agent

默认: False

如果 True,将告诉SSH层在使用基于密钥的身份验证时不要找出运行的SSH代理。

0.9.1 新版功能.

参见

--no_agent

no_keys

默认: False

如果 True,将告诉SSH层不从 $HOME/.ssh/ 文件夹加载任何私钥文件。 (当然,仍然会使用通过 fab -i 显式加载的密钥文件。)

0.9.1 新版功能.

参见

-k

parallel

默认: False

True 时,强制所有任务并行运行。暗示 env.linewise

1.3 新版功能.

password

默认: None

SSH层在连接到远程主机时使用的默认密码,和/或 在回答 sudo 提示时使用。

passwords

默认: {}

这个字典主要用于内部使用,并且作为每主机字符串密码缓存自动填充。密钥是完整的 主机字符串,值是密码(字符串)。

警告

如果您手动修改或生成此字典,您必须使用标准的主机字符串 具有用户和端口值。有关主机字符串API的详细信息,请参阅上面的链接。

参见

密码管理

1.0 新版功能.

path

默认: ''

用于在 run/sudo/local 中执行命令时设置 $PATH shell环境变量。建议使用 path 上下文管理器来管理此值,而不是直接设置它。

1.0 新版功能.

pool_size

默认: 0

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

1.3 新版功能.

prompts

默认: {}

prompts 字典允许用户控制交互式提示。如果在命令的标准输出流中找到字典中的键,Fabric将自动回答相应的字典值。

1.9 新版功能.

port

默认: None

当迭代主机列表时,通过 fab 设置为 env.host_string 的端口部分。也可以用于指定默认端口。

real_fabfile

默认: None

fab 设置与fabfile的路径加载,如果它得到了远。仅供参考。

remote_interrupt

默认: None

控制Ctrl-C是远程触发中断还是在本地捕获,如下所示:

  • None (默认值):只有 open_shell 将显示远程中断行为,run/sudo 将在本地捕获中断。

  • False:甚至 open_shell 捕获本地。

  • True:所有功能都会将中断发送到远程端。

1.6 新版功能.

rcfile

默认: $HOME/.fabricrc

加载Fabric的本地设置文件时使用的路径。

reject_unknown_hosts

默认: False

如果是 True,当连接到未在用户的known-hosts文件中列出的主机时,SSH层将引发异常。

system_known_hosts

默认: None

如果设置,应该是 known_hosts 文件的路径。 SSH层将在读取用户的known-hosts文件之前读取此文件。

参见

SSH行为

roledefs

默认: {}

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

参见

执行模型

roles

默认: []

编写每任务主机列表时使用的全局角色列表。

shell

默认: /bin/bash -l -c

用作执行命令时的shell包装器的值。 run。必须能以 <env.shell> "<command goes here>" 格式存在 - 例如默认使用Bash的 -c 选项,它使用命令字符串作为其值。

skip_bad_hosts

默认: False

如果 True,导致 fab (或非 fab 使用 execute)跳过主机,它不能连接到。

1.4 新版功能.

skip_unknown_tasks

默认: False

如果 True,导致 fab (或非 fab 使用 execute)跳过未找到的任务,而不中止。

ssh_config_path

默认: $HOME/.ssh/config

允许指定备用SSH配置文件路径。

1.4 新版功能.

ok_ret_codes

默认: [0]

此列表中的返回码用于确定对 run/sudo/sudo 的调用是否被视为成功。

1.6 新版功能.

sudo_password

默认: None

提交到 sudo 密码提示的默认密码。如果为空或 Noneenv.password 和/或 env.passwords 用作回退。

1.12 新版功能.

sudo_passwords

默认: {}

passwords 相同,但仅用于sudo-only密码。

参见

密码管理

1.12 新版功能.

sudo_prefix

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

实际的 sudo 命令前缀到 sudo 调用命令字符串。在默认远程 $PATH 上没有 sudo 或需要进行其他更改(例如在无密码sudo生效时删除 -p)的用户可能会发现更改此功能非常有用。

参见

sudo 操作; env.sudo_prompt

sudo_prompt

默认: "sudo password:"

传递到远程系统上的 sudo 程序,以便Fabric可以正确识别其密码提示。

参见

sudo 操作; env.sudo_prefix

sudo_user

默认: None

用作 sudouser 参数的后备值,如果没有给出。可用于与 settings 组合。

参见

sudo

tasks

默认: []

fab 设置为要为当前执行的命令执行的完整任务列表。仅供参考。

参见

执行模型

timeout

默认: 10

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

1.4 新版功能.

use_shell

默认: True

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

use_ssh_config

默认: False

设置为 True 以使Fabric负载您的本地SSH配置文件。

1.4 新版功能.

user

默认: 用户的本地用户名

连接到远程主机时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变量。

参见

执行模型--user

version

默认: 当前Fabric版本字符串

主要用于信息目的。不建议修改,但也可能不会破坏任何东西。

参见

--version

warn_only

默认: False

指定是否在 operations 遇到错误条件时发出警告,而不是中止。