f5networks.f5_modules.bigip_ucs_fetch 模块 – 从远程节点获取 UCS 文件

注意

此模块是 f5networks.f5_modules 集合（版本 1.32.1）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install f5networks.f5_modules。

要在 playbook 中使用它，请指定：f5networks.f5_modules.bigip_ucs_fetch。

f5networks.f5_modules 1.0.0 中的新增功能

概要 

此模块用于从远程计算机获取 UCS 文件，并将它们以主机名组织的结构存储在本地文件树中。编写此模块是为了创建和传输可能不存在的 UCS 文件，它不需要预先创建 UCS 文件。因此，除非 fail_on_missing 设置为“yes”，否则缺少远程 UCS 不算错误。

参数 

参数	注释
async_timeout 整数	在设备上创建新的 UCS 文件时使用的参数。等待 API 异步接口完成其任务的秒数。接受的值范围在 `150` 到 `1800` 秒之间。默认值： `150`
attributes 别名: attr 字符串	生成的文件系统对象应具有的属性。要获取受支持的标志，请查看目标系统上 chattr 的手册页。此字符串应包含与 lsattr 显示的顺序相同的属性。假设 `=` 运算符为默认值，否则需要在字符串中包含 `+` 或 `-` 运算符。
backup 布尔值	创建一个包含时间戳信息的备份文件，以便在错误覆盖文件时可以恢复原始文件。选项 `false` ← (默认) `true`
create_on_missing 布尔值	如果远程系统上不存在该文件，则根据 `src` 的值创建 UCS。当设置为 `false`，并且 `fail_on_missing` 设置为 `false` 时，如果设备上缺少 ucs 文件，模块将返回无更改。选项 `false` `true` ← (默认)
dest 路径	用于保存 UCS 文件的目录。当 `only_create_file` 设置为 `false` 时，此选项是强制性的。
encryption_password 字符串	如果需要，用于加密 UCS 文件的密码。
fail_on_missing 布尔值	如果远程系统上缺少 UCS 文件，则使模块失败。此选项始终优先于 `create_on_missing`，因此，当设置为 `true` 时，如果缺少 UCS，即使 `create_on_missing` 选项设置为 `true`，模块也将始终失败。当设置为 `false`，并且 `create_on_missing` 设置为 `false` 时，如果设备上缺少 ucs 文件，模块将返回无更改。选项 `false` ← (默认) `true`
force 布尔值	如果 `false`，则仅当目标不存在时才会传输该文件。选项 `false` `true` ← (默认)
group 字符串	应拥有文件系统对象的所有者的组名，就像将提供给 chown 一样。如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留以前的所有权。
mode 任意	生成的文件系统对象应具有的权限。对于那些习惯于 /usr/bin/chmod 的人，请记住模式实际上是八进制数。您必须为 Ansible 提供足够的信息来正确解析它们。为了获得一致的结果，请引用八进制数（例如，`'644'` 或 `'1777'`），以便 Ansible 接收一个字符串并可以将其自身从字符串转换为数字。添加前导零（例如，`0755`）有时可以工作，但在循环和其他一些情况下可能会失败。如果 Ansible 未遵循这些规则中的任何一条而获得一个数字，最终将得到一个十进制数，这将产生意外的结果。从 Ansible 1.8 开始，模式可以指定为符号模式（例如，`u+rwx` 或 `u=rw,g=r,o=r`）。如果未指定 `mode` 并且目标文件系统对象不存在，则在设置新创建的文件系统对象的模式时，将使用系统上的默认 `umask`。如果未指定 `mode` 并且目标文件系统对象确实存在，则将使用现有文件系统对象的模式。指定 `mode` 是确保使用正确的权限创建文件系统对象的最佳方法。有关更多详细信息，请参见 CVE-2020-1736。
only_create_file 布尔值在 f5networks.f5_modules 1.12.0 中添加	如果 `true`，则该文件在设备上创建，但不下载。如果设备上已存在 UCS 归档文件，则不会进行任何更改，也不会下载该文件。要重新创建保留在设备上的 UCS 文件，请在使用 `only_create_file` 设置为 `true` 的情况下运行此模块之前，使用 `bigip_ucs` 模块将其删除。选项 `false` ← (默认) `true`
owner 字符串	应拥有文件系统对象的用户名称，如同传递给 chown 的参数。如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下可以保留之前的属主。指定数字用户名将被视为用户 ID 而不是用户名。为避免混淆，请避免使用数字用户名。
provider 字典在 f5networks.f5_modules 1.0.0 中添加	包含连接详细信息的字典对象。
auth_provider 字符串	配置身份验证提供程序，以便从远程设备获取身份验证令牌。此选项主要用于处理 BIG-IQ 设备。
no_f5_teem 布尔值	如果为 `yes`，则不会将 TEEM 遥测数据发送到 F5。您可以通过设置环境变量 `F5_TELEMETRY_OFF` 来省略此选项。之前使用的变量 `F5_TEEM` 已被弃用，因为它名称容易引起混淆。选项 `false` ← (默认) `true`
password 别名: pass, pwd 字符串 / 必需	用于连接 BIG-IP 或 BIG-IQ 的用户帐户的密码。您可以通过设置环境变量 `F5_PASSWORD` 来省略此选项。
server 字符串 / 必需	BIG-IP 主机或 BIG-IQ 主机。您可以通过设置环境变量 `F5_SERVER` 来省略此选项。
server_port 整数	BIG-IP 服务器端口。您可以通过设置环境变量 `F5_SERVER_PORT` 来省略此选项。默认值: `443`
timeout 整数	指定与网络设备通信（用于连接或发送命令）的超时时间（秒）。如果在操作完成之前超出超时时间，模块将报错。
transport 字符串	配置连接到远程设备时使用的传输连接。选项 `"rest"` ← (默认)
user 字符串 / 必需	用于连接 BIG-IP 或 BIG-IQ 的用户名。此用户必须在设备上具有管理权限。您可以通过设置环境变量 `F5_USER` 来省略此选项。
validate_certs 布尔值	如果为 `no`，则不验证 SSL 证书。仅在个人控制的站点上使用自签名证书时才使用此选项。您可以通过设置环境变量 `F5_VALIDATE_CERTS` 来省略此选项。选项 `false` `true` ← (默认)
selevel 字符串	SELinux 文件系统对象上下文的 level 部分。这是 MLS/MCS 属性，有时称为 `range`。当设置为 `_default` 时，如果可用，它将使用策略的 `level` 部分。
serole 字符串	SELinux 文件系统对象上下文的 role 部分。当设置为 `_default` 时，如果可用，它将使用策略的 `role` 部分。
setype 字符串	SELinux 文件系统对象上下文的 type 部分。当设置为 `_default` 时，如果可用，它将使用策略的 `type` 部分。
seuser 字符串	SELinux 文件系统对象上下文的 user 部分。默认情况下，它使用 `system` 策略（如果适用）。当设置为 `_default` 时，如果可用，它将使用策略的 `user` 部分。
src 字符串	要在远程服务器上创建以进行下载的 UCS 文件名。该文件在 /var/local/ucs/ 中检索或创建。当 `only_create_file` 设置为 `true` 时，此选项是强制性的。
unsafe_writes 布尔值	影响何时使用原子操作以防止数据损坏或从目标文件系统对象读取不一致的数据。默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统的配置方式或损坏方式会阻止这种情况。一个示例是 docker 挂载的文件系统对象，这些对象无法从容器内部以原子方式更新，只能以不安全的方式写入。当原子操作失败时，此选项允许 Ansible 回退到不安全的方法来更新文件系统对象（但是，它不会强制 Ansible 执行不安全的写入）。重要！不安全的写入会受到竞争条件的影响，并可能导致数据损坏。选项 `false` ← (默认) `true`

注释 

注意

BIG-IP 没有提供通过任何接口获取系统上 UCS 文件校验和的方法，可能只能直接登录到盒子（但这不支持设备模式）。因此，此模块所能做的最好办法是检查磁盘上是否存在该文件；不进行校验和。
如果您将此模块与 Ansible Tower 或 Ansible AWX 一起使用，您应该了解这些 Ansible 产品如何在受限环境中执行作业。更多信息可以在这里找到 https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/module-usage-with-tower.html
一些运行时间较长的任务可能会导致 BIG-IP 上的 REST 接口超时，为避免这种情况，请根据此 KB 文章调整计时器 https://support.f5.com/csp/article/K94602685
有关使用 Ansible 管理 F5 Networks 设备的更多信息，请参见 https://ansible.org.cn/integrations/networks/f5。
需要 BIG-IP 软件版本 >= 12。
F5 模块仅操作 F5 产品的运行配置。为确保 BIG-IP 特定配置持久保存到磁盘，请务必至少包含一个使用 f5networks.f5_modules.bigip_config 模块保存运行配置的任务。有关正确使用该模块保存运行配置，请参阅该模块的文档。

示例 

- name: Download a new UCS
  bigip_ucs_fetch:
    src: cs_backup.ucs
    dest: /tmp/cs_backup.ucs
    provider:
      server: lb.mydomain.com
      user: admin
      password: secret
  delegate_to: localhost

- name: Only create new UCS, no download
  bigip_ucs_fetch:
    src: cs_backup.ucs
    only_create_file: true
    provider:
      server: lb.mydomain.com
      user: admin
      password: secret
  delegate_to: localhost

- name: Recreate UCS file left on device - remove file first
  bigip_ucs:
    ucs: cs_backup.ucs
    state: absent
    provider:
      server: lb.mydomain.com
      user: admin
      password: secret
  delegate_to: localhost

- name: Recreate UCS file left on device - create new file
  bigip_ucs_fetch:
    src: cs_backup.ucs
    only_create_file: true
    provider:
      server: lb.mydomain.com
      user: admin
      password: secret
  delegate_to: localhost

返回值 

通用返回值记录在此处这里，以下是此模块特有的字段

键	描述
backup_file 字符串	备份文件的名称。返回值: changed 且如果 backup=yes 示例: `"/path/to/file.txt.2015-02-12@22:09~"`
checksum 字符串	下载文件的 SHA1 校验和。返回值: success 或 changed 示例: `"7b46bbe4f8ebfee64761b5313855618f64c64109"`
dest 字符串	UCS 保存到 Ansible 主机上的位置。返回值: success 示例: `"/path/to/file.txt"`
gid 整数	执行后，UCS 文件的组 ID。返回值: success 示例: `100`
group 字符串	执行后，UCS 文件的组。返回值: success 示例: `"httpd"`
md5sum 字符串	下载文件的 MD5 校验和。返回值: changed 或 success 示例: `"96cacab4c259c4598727d7cf2ceb3b45"`
mode 字符串	执行后，目标 UCS 的权限。返回值: success 示例: `"420"`
owner 字符串	执行后，UCS 文件的所有者。返回值: success 示例: `"httpd"`
size 整数	执行后，目标 UCS 的大小。返回值: success 示例: `1220`
src 字符串	要在远程 BIG-IP 上下载的 UCS 文件名。如果未指定，则这是一个随机生成的文件名。返回值: changed 示例: `"cs_backup.ucs"`
uid 整数	执行后，UCS 文件的所有者 ID。返回值: success 示例: `100`

作者

Tim Rupp (@caphrim007)
Wojciech Wypior (@wojtek0806)