Ansible Core 文档

ansible.builtin.stat 模块 – 获取文件或文件系统状态

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定集合关键字，您也可以使用简短的模块名称 stat。但是，我们建议您使用完全限定的集合名称 (FQCN) ansible.builtin.stat，以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合冲突。

摘要 

检索文件的事实信息，类似于 Linux/Unix stat 命令。
对于 Windows 目标，请改用 ansible.windows.win_stat 模块。

参数 

参数	注释
checksum_algorithm 别名：checksum，checksum_algo 字符串	确定文件校验和的算法。如果主机无法使用指定的算法，则会抛出错误。远程主机必须支持指定的哈希方法，如果主机符合 FIPS-140，则 `md5` 可能不可用。目标系统可能会限制可用性，例如 FIPS 系统不允许使用 md5 选项 `"md5"` `"sha1"` ← (默认) `"sha224"` `"sha256"` `"sha384"` `"sha512"`
follow 布尔值	是否跟随符号链接。选项 `false` ← (默认) `true`
get_attributes 别名：attr，attributes 布尔值	如果存在，则使用 lsattr 工具获取文件属性。选项 `false` `true` ← (默认)
get_checksum 布尔值	是否返回文件的校验和。选项 `false` `true` ← (默认)
get_mime 别名：mime，mime_type，mime-type 布尔值	使用文件魔术并返回有关文件性质的数据。这使用大多数 Linux/Unix 系统上找到的 `file` 实用程序。如果可能，这将向返回结果添加 `stat.mimetype` 和 `stat.charset` 字段。在 Ansible 2.3 中，此选项从 `mime` 更改为 `get_mime`，并且默认值更改为 `true`。选项 `false` `true` ← (默认)
path 别名：dest，name 路径 / 必需	要获取事实信息的文件/对象的完整路径。

属性 

属性	支持	描述
check_mode	支持：完全支持	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标，如果不受支持，则操作将被跳过。
diff_mode	支持：不支持	在差异模式下，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息
platform	平台： posix	可以对其进行操作的目标操作系统/系列

另请参阅 

另请参阅

ansible.builtin.file: 管理文件和文件属性。
ansible.windows.win_stat: 有关 **ansible.windows.win_stat** 模块的官方文档。

示例 

# Obtain the stats of /etc/foo.conf, and check that the file still belongs
# to 'root'. Fail otherwise.
- name: Get stats of a file
  ansible.builtin.stat:
    path: /etc/foo.conf
  register: st
- name: Fail if the file does not belong to 'root'
  ansible.builtin.fail:
    msg: "Whoops! file ownership has changed"
  when: st.stat.pw_name != 'root'

# Determine if a path exists and is a symlink. Note that if the path does
# not exist, and we test sym.stat.islnk, it will fail with an error. So
# therefore, we must test whether it is defined.
# Run this to understand the structure, the skipped ones do not pass the
# check performed by 'when'
- name: Get stats of the FS object
  ansible.builtin.stat:
    path: /path/to/something
  register: sym

- name: Print a debug message
  ansible.builtin.debug:
    msg: "islnk isn't defined (path doesn't exist)"
  when: sym.stat.islnk is not defined

- name: Print a debug message
  ansible.builtin.debug:
    msg: "islnk is defined (path must exist)"
  when: sym.stat.islnk is defined

- name: Print a debug message
  ansible.builtin.debug:
    msg: "Path exists and is a symlink"
  when: sym.stat.islnk is defined and sym.stat.islnk

- name: Print a debug message
  ansible.builtin.debug:
    msg: "Path exists and isn't a symlink"
  when: sym.stat.islnk is defined and sym.stat.islnk == False


# Determine if a path exists and is a directory.  Note that we need to test
# both that p.stat.isdir actually exists, and also that it's set to true.
- name: Get stats of the FS object
  ansible.builtin.stat:
    path: /path/to/something
  register: p
- name: Print a debug message
  ansible.builtin.debug:
    msg: "Path exists and is a directory"
  when: p.stat.isdir is defined and p.stat.isdir

- name: Do not calculate the checksum
  ansible.builtin.stat:
    path: /path/to/myhugefile
    get_checksum: no

- name: Use sha256 to calculate the checksum
  ansible.builtin.stat:
    path: /path/to/something
    checksum_algorithm: sha256

返回值 

常见返回值在此处记录此处，以下是此模块特有的字段

键	描述
stat 字典	包含所有状态数据的字典，某些平台可能会添加其他字段。已返回：成功
atime 浮点数	上次访问时间已返回：成功，路径存在且用户可以读取统计信息示例：`1424348972.575`
attributes 列表 / 元素=字符串	文件属性列表已返回：成功，路径存在且用户可以执行路径示例：`["immutable", "extent"]`
charset 字符串	文件字符集或编码已返回：成功，路径存在且用户可以读取统计信息，并且已安装的 python 支持它，并且 `get_mime` 选项为 `true`，将在错误时返回 `unknown`。示例：`"us-ascii"`
checksum 字符串	文件的哈希值已返回：成功，路径存在，用户可以读取统计信息，路径支持哈希并且提供的校验和算法可用示例：`"50ba294cdf28c0d5bcde25708df53346825a429f"`
ctime 浮点数	上次元数据更新或创建的时间（取决于操作系统）已返回：成功，路径存在且用户可以读取统计信息示例：`1424348972.575`
dev 整数	inode 所在的设备已返回：成功，路径存在且用户可以读取统计信息示例：`33`
executable 布尔值	告知调用用户是否对该路径拥有执行权限已返回：成功，路径存在且用户可以执行路径示例： `false`
exists 布尔值	目标路径是否存在已返回：成功示例： `true`
gid 整数	表示文件所有者所属组的数字ID 已返回：成功，路径存在且用户可以读取统计信息示例： `1003`
gr_name 字符串	所有者所属组的名称返回：成功，路径存在，用户可以读取统计信息，可以查找所有者组，并且已安装的Python支持此功能示例： `"www-data"`
inode 整数	路径的inode编号已返回：成功，路径存在且用户可以读取统计信息示例： `12758`
isblk 布尔值	告知路径是否为块设备已返回：成功，路径存在且用户可以读取统计信息示例： `false`
ischr 布尔值	告知路径是否为字符设备已返回：成功，路径存在且用户可以读取统计信息示例： `false`
isdir 布尔值	告知路径是否为目录已返回：成功，路径存在且用户可以读取统计信息示例： `false`
isfifo 布尔值	告知路径是否为命名管道已返回：成功，路径存在且用户可以读取统计信息示例： `false`
isgid 布尔值	告知调用用户的组ID是否与所有者的组ID匹配已返回：成功，路径存在且用户可以读取统计信息示例： `false`
islnk 布尔值	告知路径是否为符号链接已返回：成功，路径存在且用户可以读取统计信息示例： `false`
isreg 布尔值	告知路径是否为普通文件已返回：成功，路径存在且用户可以读取统计信息示例： `true`
issock 布尔值	告知路径是否为Unix域套接字已返回：成功，路径存在且用户可以读取统计信息示例： `false`
isuid 布尔值	告知调用用户的ID是否与所有者的ID匹配已返回：成功，路径存在且用户可以读取统计信息示例： `false`
lnk_source 字符串	符号链接的目标，已针对远程文件系统进行规范化返回：成功，路径存在且用户可以读取统计信息，并且路径为符号链接示例： `"/home/foobar/21102015-1445431274-908472971"`
lnk_target 字符串	符号链接的目标。请注意，相对路径保持相对返回：成功，路径存在且用户可以读取统计信息，并且路径为符号链接示例： `"../foobar/21102015-1445431274-908472971"`
mimetype 字符串	文件魔数数据或MIME类型已返回：成功，路径存在且用户可以读取统计信息，并且已安装的 python 支持它，并且 `get_mime` 选项为 `true`，将在错误时返回 `unknown`。示例： `"application/pdf; charset=binary"`
mode 字符串	文件的Unix权限，以八进制表示形式的字符串表示已返回：成功，路径存在且用户可以读取统计信息示例： `"1755"`
mtime 浮点数	上次修改时间已返回：成功，路径存在且用户可以读取统计信息示例：`1424348972.575`
nlink 整数	指向inode的链接数（硬链接）已返回：成功，路径存在且用户可以读取统计信息示例： `1`
path 字符串	获取事实的文件/对象的完整路径返回：成功，以及路径是否存在示例： `"/path/to/file"`
pw_name 字符串	所有者的用户名返回：成功，路径存在，用户可以读取统计信息，可以查找所有者名称，并且已安装的Python支持此功能示例： `"httpd"`
readable 布尔值	告知调用用户是否具有读取路径的权限返回：成功，路径存在且用户可以读取路径示例： `false`
rgrp 布尔值	告知所有者组是否具有读取权限已返回：成功，路径存在且用户可以读取统计信息示例： `true`
roth 布尔值	告知其他用户是否具有读取权限已返回：成功，路径存在且用户可以读取统计信息示例： `true`
rusr 布尔值	告知所有者是否具有读取权限已返回：成功，路径存在且用户可以读取统计信息示例： `true`
size 整数	普通文件的大小（以字节为单位），某些特殊文件的数据量已返回：成功，路径存在且用户可以读取统计信息示例： `203`
uid 整数	表示文件所有者的数字ID 已返回：成功，路径存在且用户可以读取统计信息示例： `1003`
version 字符串	根据文件系统，文件的版本/生成属性返回：成功，路径存在，用户可以执行路径，lsattr可用且文件系统支持示例： `"381700746"`
wgrp 布尔值	告知所有者组是否具有写入权限已返回：成功，路径存在且用户可以读取统计信息示例： `false`
woth 布尔值	告知其他用户是否具有写入权限已返回：成功，路径存在且用户可以读取统计信息示例： `false`
writeable 布尔值	告知调用用户是否具有写入路径的权限返回：成功，路径存在且用户可以写入路径示例： `false`
wusr 布尔值	告知所有者是否具有写入权限已返回：成功，路径存在且用户可以读取统计信息示例： `true`
xgrp 布尔值	告知所有者组是否具有执行权限已返回：成功，路径存在且用户可以读取统计信息示例： `true`
xoth 布尔值	告知其他用户是否具有执行权限已返回：成功，路径存在且用户可以读取统计信息示例： `true`
xusr 布尔值	告知所有者是否具有执行权限已返回：成功，路径存在且用户可以读取统计信息示例： `true`

作者

Bruce Pennypacker (@bpennypacker)

集合链接