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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，您也可以使用简短的模块名称 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 中更改的内容）的详细信息
平台	平台： 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)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 通信