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 可能不可用。 选择 "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	支持: 无	当处于 diff 模式时，将返回有关已更改（或可能需要在 check_mode 中更改）的详细信息
platform	平台: posix	可以操作的目标操作系统/系列

另请参阅

另请参阅

ansible.builtin.file

管理文件和文件属性。

ansible.windows.win_stat

获取有关 Windows 文件的信息。

示例

# 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 字典	包含所有 stat 数据的字典，某些平台可能会添加其他字段。 返回: 成功
atime 浮点数	上次访问的时间 返回: 成功，路径存在且用户可以读取统计信息 示例: 1424348972.575
attributes 列表 / elements=字符串	文件属性列表 返回: 成功，路径存在且用户可以执行该路径 示例: ["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)

集合链接

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