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	支持: 无	在 diff 模式下，将返回有关已更改内容（或可能需要在 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)

集合链接

• 问题跟踪器
• 存储库（来源）
• 通讯