Documentation

stat - retrieve file or file system status

New in version 1.3.

Synopsis

Retrieves facts for a file similar to the linux/unix ‘stat’ command.

Options

parameter required default choices comments
checksum_algorithm
(added in 2.0)
no sha1
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512
Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm.

aliases: checksum_algo, checksum
follow
no
    Whether to follow symlinks
    get_checksum
    (added in 1.8)
    no True
      Whether to return a checksum of the file (default sha1)
      get_md5
      no True
        Whether to return the md5 sum of the file. Will return None if we're unable to use md5 (Common for FIPS-140 compliant systems)
        mime
        (added in 2.1)
        no
        • True
        • False
        Use file magic and return data about the nature of the file. this uses the 'file' utility found on most Linux/Unix systems.
        This will add both `mime_type` and 'charset' fields to the return, if possible.

        aliases: mime_type, mime-type
        path
        yes
          The full path of the file/object to get the facts of

          Examples

          # Obtain the stats of /etc/foo.conf, and check that the file still belongs
          # to 'root'. Fail otherwise.
          - stat: path=/etc/foo.conf
            register: st
          - 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'
          - stat: path=/path/to/something
            register: sym
          - debug: msg="islnk isn't defined (path doesn't exist)"
            when: sym.stat.islnk is not defined
          - debug: msg="islnk is defined (path must exist)"
            when: sym.stat.islnk is defined
          - debug: msg="Path exists and is a symlink"
            when: sym.stat.islnk is defined and sym.stat.islnk
          - 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.
          - stat: path=/path/to/something
            register: p
          - debug: msg="Path exists and is a directory"
            when: p.stat.isdir is defined and p.stat.isdir
          
          # Don't do md5 checksum
          - stat: path=/path/to/myhugefile get_md5=no
          
          # Use sha256 to calculate checksum
          - stat: path=/path/to/something checksum_algorithm=sha256
          

          Return Values

          Common return values are documented here Common Return Values, the following are the fields unique to this module:

          name description returned type sample
          stat dictionary containing all the stat data success dictionary
          contains:
          name description returned type sample
          isuid Tells you if the invoking user's id matches the owner's id success, path exists and user can read stats boolean False
          uid Numeric id representing the file owner success, path exists and user can read stats int 1003
          exists if the destination path actually exists or not success boolean True
          checksum_algorithm hash of the path success, path exists, user can read stats, path supports hashing and supplied checksum algorithm is available string 50ba294cdf28c0d5bcde25708df53346825a429f
          woth Tells you if others have write permission success, path exists and user can read stats boolean False
          mtime Time of last modification success, path exists and user can read stats float 1424348972.58
          inode Inode number of the path success, path exists and user can read stats int 12758
          isgid Tells you if the invoking user's group id matches the owner's group id success, path exists and user can read stats boolean False
          size Size in bytes for a plain file, ammount of data for some special files success, path exists and user can read stats int 203
          wgrp Tells you if the owner's group has write permission success, path exists and user can read stats boolean False
          charset file character set or encoding success, path exists and user can read stats and installed python supports it and the `mime` option was true, will return 'unknown' on error. string us-ascii
          isreg Tells you if the path is a regular file success, path exists and user can read stats boolean True
          pw_name User name of owner success, path exists and user can read stats and installed python supports it string httpd
          gid Numeric id representing the group of the owner success, path exists and user can read stats int 1003
          ischr Tells you if the path is a character device success, path exists and user can read stats boolean False
          mime_type file magic data or mime-type success, path exists and user can read stats and installed python supports it and the `mime` option was true, will return 'unknown' on error. string PDF document, version 1.2
          wusr Tells you if the owner has write permission success, path exists and user can read stats boolean True
          xoth Tells you if others have execute permission success, path exists and user can read stats boolean True
          rusr Tells you if the owner has read permission success, path exists and user can read stats boolean True
          nlink Number of links to the inode (hard links) success, path exists and user can read stats int 1
          issock Tells you if the path is a unix domain socket success, path exists and user can read stats boolean False
          rgrp Tells you if the owner's group has read permission success, path exists and user can read stats boolean True
          gr_name Group name of owner success, path exists and user can read stats and installed python supports it string www-data
          path The full path of the file/object to get the facts of success and if path exists string /path/to/file
          xusr Tells you if the owner has execute permission success, path exists and user can read stats boolean True
          atime Time of last access success, path exists and user can read stats float 1424348972.58
          lnk_source Original path success, path exists and user can read stats and the path is a symbolic link string /home/foobar/21102015-1445431274-908472971
          md5 md5 hash of the path success, path exists and user can read stats and path supports hashing and md5 is supported string f88fa92d8cf2eeecf4c0a50ccc96d0c0
          isdir Tells you if the path is a directory success, path exists and user can read stats boolean False
          ctime Time of last metadata update or creation (depends on OS) success, path exists and user can read stats float 1424348972.58
          isblk Tells you if the path is a block device success, path exists and user can read stats boolean False
          xgrp Tells you if the owner's group has execute permission success, path exists and user can read stats boolean True
          dev Device the inode resides on success, path exists and user can read stats int 33
          roth Tells you if others have read permission success, path exists and user can read stats boolean True
          isfifo Tells you if the path is a named pipe success, path exists and user can read stats boolean False
          mode Unix permissions of the file in octal success, path exists and user can read stats octal 1755
          islnk Tells you if the path is a symbolic link success, path exists and user can read stats boolean False


          This is a Core Module

          For more information on what this means please read Core Modules

          For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.