Skip to main content

fab 选项和参数

使用Fabric的最常见方法是通过其命令行工具 fab,在安装Fabric时,该工具应该放在shell的可执行路径上。 fab 努力成为一个很好的Unix公民,使用标准风格的命令行开关,帮助输出等。

基本使用

在其最简单的形式中,fab 可以被调用没有任何选项,并且具有一个或多个参数,其应该是任务名称,例如。:

$ fab task1 task2

概述和教程执行模型 中所详述的,这将运行 task1,然后是 task2,假设Fabric能够找到附近包含具有这些名称的Python函数的fabfile。

但是,可以通过使用提供的选项和/或向单个任务传递参数,将这种简单的用法扩展为更加灵活的东西。

任意远程shell命令

0.9.2 新版功能.

Fabric使用不太常用的命令行约定,可以按以下方式调用:

$ fab [options] -- [shell command]

其中 -- 之后的所有内容都变成临时 run 调用,并且不会解析 fab 选项。如果已在模块级别或命令行中定义了主机列表,则此用法将像单行匿名任务。

例如,假设您只想获取一系列系统的内核信息;你可以这样做:

$ fab -H system1,system2,system3 -- uname -a

这将在字面上等同于以下fabfile:

from fabric.api import run

def anonymous():
    run("uname -a")

好像它是这样执行的:

$ fab -H system1,system2,system3 anonymous

大多数时候,你只想写出你的fabfile中的任务(任何你使用过的东西,你可能会再次使用),但是这个功能提供了一个方便快捷的方法来快速完成一个SSH传递的命令,同时利用您的fabfile的连接设置。

命令行选项

通过 fab --help 可以找到所有可能的命令行选项的快速概述。如果您要查找特定选项的详细信息,我们将在下面详细介绍。

注解

fab 使用Python的 optparse 库,意味着它支持典型的Linux或GNU风格的短和长选项,以及自由混合选项和参数。例如。 fab task1 -H hostname task2 -i path/to/keyfile 与更直接的 fab -H hostname -i path/to/keyfile task1 task2 一样有效。

-a, --no_agent

env.no_agent 设置为 True,强制我们的SSH层在尝试解锁私钥文件时不与SSH代理通信。

0.9.1 新版功能.

-A, --forward-agent

env.forward_agent 设置为 True,启用代理转发。

1.4 新版功能.

--abort-on-prompts

env.abort_on_prompts 设置为 True,每当它提示输入时强制Fabric中止。

1.1 新版功能.

-c RCFILE, --config=RCFILE

env.rcfile 设置为给定的文件路径,Fabric将尝试在启动时加载并使用更新环境变量。

-d COMMAND, --display=COMMAND

打印给定任务的整个docstring(如果有的话)。目前不打印任务的函数签名,所以描述性的docstrings是一个好主意。 (他们是 always 一个好主意,当然 - 只是moreso在这里。)

--connection-attempts=M, -n M

设置尝试连接的次数。设置 env.connection_attempts

1.4 新版功能.

-D, --disable-known-hosts

env.disable_known_hosts 设置为 True,防止Fabric加载用户的SSH known_hosts 文件。

-f FABFILE, --fabfile=FABFILE

要搜索的fabfile名称模式(默认为 fabfile.py),或者作为fabfile加载的显式文件路径(例如 /path/to/my/fabfile.py)。

-F LIST_FORMAT, --list-format=LIST_FORMAT

允许控制 --list 的输出格式。 short 相当于 --shortlistnormal 与完全省略此选项(即默认值)相同,并且 nested 打印出一个嵌套的命名空间树。

1.1 新版功能.

参见

--shortlist--list

-g HOST, --gateway=HOST

环境 设置为 HOST 主机字符串。

1.5 新版功能.

--gss-auth

切换GSS-API身份验证的使用。

1.11 新版功能.

--gss-deleg

切换是否委派GSS-API客户端凭据。

1.11 新版功能.

--gss-kex

切换是否使用GSS-API密钥交换。

1.11 新版功能.

-h, --help

显示标准帮助消息,包含所有可能的选项,并简要概述其功能,然后退出。

--hide=LEVELS

默认情况下隐藏的 输出电平 的逗号分隔列表。

-H HOSTS, --hosts=HOSTS

env.hosts 设置为给定的以逗号分隔的主机字符串列表。

-x HOSTS, --exclude-hosts=HOSTS

env.exclude_hosts 设置为以逗号分隔的主机字符串列表,然后保留在最终主机列表之外。

1.1 新版功能.

-i KEY_FILENAME

当设置为文件路径时,将以SSH身份文件(通常是私钥)加载给定文件。此选项可能重复多次。设置(或追加到) env.key_filename

-I, --initial-password-prompt

在会话开始时(在fabfile加载和选项解析之后,但在执行任何任务之前)强制提供密码以便预填 env.password

这对于通过 --password 设置密码或通过在fabfile中设置 env.password 的防火运行(尤其是并行会话,其中不能运行时输入)非常有用,这是不可取的。

注解

输入到此提示中的值将 overwrite 通过 env.password 在模块级或通过 --password 提供。

参见

密码管理

--initial-sudo-password-prompt

--initial-password-prompt,但预填充 sudo_password 而不是 password

1.12 新版功能.

-k

env.no_keys 设置为 True,强制SSH层不在主目录中查找SSH私钥文件。

0.9.1 新版功能.

--keepalive=KEEPALIVE

env.keepalive 设置为给定(整数)值,指定SSH保持活动间隔。

1.1 新版功能.

--linewise

强制输出逐行缓冲,而不是逐字节缓冲。常用于或需要 并行执行

1.3 新版功能.

-l, --list

正常导入fabfile,但打印所有发现的任务和退出的列表。还将打印每个任务的docstring的第一行,如果它有一个,在它旁边(如果必要,截断)。

在 0.9.1 版更改: 添加docstring到输出。

-p PASSWORD, --password=PASSWORD

env.password 设置为给定字符串;则在进行SSH连接或调用 sudo 程序时,它将用作默认密码。

-P, --parallel

env.parallel 设置为 True,使任务并行运行。

1.3 新版功能.

参见

并行执行

--no-pty

env.always_use_pty 设置为 False,导致所有 run/sudo 调用的行为像指定了 pty=False

1.0 新版功能.

-r, --reject-unknown-hosts

env.reject_unknown_hosts 设置为 True,使Fabric在连接到用户的SSH known_hosts 文件中找不到的主机时中止。

-R ROLES, --roles=ROLES

环境 设置为以逗号分隔的角色名称列表。

--set KEY=VALUE,...

允许您为任意Fabric Env变量设置默认值。以这种方式设置的值具有低优先级 - 它们不会覆盖也在命令行中指定的更多特定env var。例如。:

fab --set password=foo --password=bar

将导致 env.password = 'bar',而不是 'foo'

多个 KEY=VALUE 对可以是逗号分隔的,例如。 fab --set var1=val1,var2=val2

除了基本字符串值之外,您还可以通过省略 =VALUE (例如 fab --set KEY)将env vars设置为True,并且可以通过保留等号来将值设置为空字符串(因此设置为False等效值),但省略 VALUE (例如 fab --set KEY=

1.4 新版功能.

-s SHELL, --shell=SHELL

env.shell 设置为给定字符串,覆盖用于执行远程命令的缺省shell包装程序。

--shortlist

类似于 --list,但没有任何装饰,只是任务名称用换行符分隔,没有缩进或docstrings。

0.9.2 新版功能.

参见

--list

--show=LEVELS

要添加到默认显示的 输出电平 的逗号分隔列表。

参见

runsudo

--ssh-config-path

设置 env.ssh_config_path

1.4 新版功能.

--skip-bad-hosts

设置 env.skip_bad_hosts,使Fabric跳过不可用的主机。

1.4 新版功能.

--skip-unknown-tasks

设置 env.skip_unknown_tasks,使Fabric跳过未知任务。

--sudo-password

设置 env.sudo_password

1.12 新版功能.

--timeout=N, -t N

设置连接超时(秒)。设置 env.timeout

1.4 新版功能.

--command-timeout=N, -T N

设置远程命令超时(秒)。设置 env.command_timeout

1.6 新版功能.

-u USER, --user=USER

env.user 设置为给定字符串;在进行SSH连接时,它将被用作默认用户名。

-V, --version

显示Fabric的版本号,然后退出。

-w, --warn-only

env.warn_only 设置为 True,使Fabric即使在命令遇到错误条件时仍继续执行。

-z, --pool-size

设置 env.pool_size,它指定并行执行期间并发运行的进程数。

1.3 新版功能.

参见

并行执行

每任务参数

命令行选项 中给出的选项适用于整个 fab 的调用;即使订单混合在一起,选项仍适用于所有给定的任务。此外,由于任务只是Python函数,通常需要在运行时向它们传递参数。

回答这两个需求是“每任务参数”的概念,这是一个特殊的语法,可以粘到任何任务名称的末尾:

  • 使用冒号(:)将任务名称与其参数分开;

  • 使用逗号(,)将参数彼此分隔(可以通过使用反斜杠(即 \,)进行转义);

  • 对于关键字参数使用等号(=),或对于位置参数省略它们。也可以使用反斜杠进行转义。

此外,由于此过程涉及字符串解析,所有值将最终作为Python字符串,因此计划相应。 (我们希望在未来的Fabric版本中改进这一点,只要可以找到一个直观的语法)。

例如,可以如此定义“创建新用户”任务(为了简洁省略大部分实际逻辑):

def new_user(username, admin='no', comment="No comment provided"):
    print("New User (%s): %s" % (username, comment))
    pass

您可以只指定用户名:

$ fab new_user:myusername

或者将其视为明确的关键字参数:

$ fab new_user:username=myusername

如果两个参数都给定,您可以再次将它们作为位置参数:

$ fab new_user:myusername,yes

或者混合搭配,就像在Python:

$ fab new_user:myusername,admin=yes

上面的 print 调用对于说明转义的逗号很有用,像这样:

$ fab new_user:myusername,admin=no,comment='Gary\, new developer (starts Monday)'

注解

引用反斜杠转义的逗号是必需的,因为不这样做会导致shell语法错误。当参数涉及其他与shell相关的字符(如空格)时,也需要引用。

以上所有都被翻译成预期的Python函数调用。例如,上面的最后一个调用将变成:

>>> new_user('myusername', admin='yes', comment='Gary, new developer (starts Monday)')

角色和主机

任务执行部分 中所述,有一些每任务关键字参数(hosthostsroleroles),它们实际上不映射到任务函数本身,但是用于设置每任务主机和/或角色列表。

这些特殊的kwargs是从args/kwargs发送到任务函数本身的 删除;这是如果你的任务没有定义kwargs有问题,你不会遇到TypeError。 (这也意味着如果你 用这些名称定义参数,你将无法以这种方式指定 - 一个令人遗憾但必要的牺牲。)

注解

如果给出这些kwarg的复数和单数形式,则复数的值将胜出,并且单数将被丢弃。

当使用这些参数的复数形式时,必须使用分号(;),因为逗号已经用于将参数彼此分隔。此外,由于您的shell可能会考虑分号是一个特殊字符,因此您需要引用主机列表字符串以防止shell解释。:

$ fab new_user:myusername,hosts="host1;host2"

再次,因为 hosts kwarg从发送到 new_user 任务函数的参数列表中删除,所以实际的Python调用将是 new_user('myusername'),并且该函数将在 ['host1', 'host2'] 的主机列表上执行。

设置文件

Fabric目前支持一个简单的用户设置文件,或 fabricrc (认为 bashrc,但对于 fab),它应该包含一个或多个键值对,每行一个。这些行将受 string.split('=') 的约束,因此当前只能用于指定字符串设置。任何这样的键值对将用于在 fab 运行时更新 环境,并且在加载任何fabfile之前加载。

默认情况下,Fabric查找 ~/.fabricrc,这可以通过将 -c 标志指定为 fab 来覆盖。

例如,如果您的典型SSH登录用户名与工作站用户名不同,并且您不想在项目的fabfile中修改 env.user (可能是因为您希望其他人也使用它),您可以编写一个 fabricrc 文件:

user = ssh_user_name

然后,当运行 fab 时,您的fabfile将加载 env.user 设置为 'ssh_user_name'。该fabfile的其他用户可以做同样的,允许fabfile本身对于默认用户名干净无关。

退出状态

如果 fab 成功地在所有主机上执行所有命令,则返回success(0)。

除此以外,

  • 如果指定了无效的命令或选项,则 fab 将中止退出状态为1。

  • 如果到主机的连接失败,fab 将退出,退出状态为1.它不会尝试下一个主机。

  • 如果本地或远程命令失败(返回非零状态),则 fab 将退出,退出状态为1.可以在日志中找到原始命令的退出状态。

  • 如果抛出了Python异常,则 fab 将退出状态为1,并中止。