salt.modules.file

### Navigation

- index
- modules |
- next |
- previous |
- « SaltStack.org |
- Documentation home
- Full list of builtin execution modules »

# salt.modules.file

Manage information about files on the minion, set/read user, group, and mode data

`salt.modules.file.` `append`(path, *args)

  Append text to the end of a file

  CLI Example:

      salt '*' file.append /etc/motd \
              "With all thine offerings thou shalt offer salt."\
              "Salt is what makes things taste bad when it isn't in them."

  New in version 0.9.5.

`salt.modules.file.` `check_file_meta`(name, sfn, source, source_sum, user, group, mode, env)

  Check for the changes in the file metadata

`salt.modules.file.` `check_hash`(path, hash)

  Check if a file matches the given hash string

  Returns true if the hash matched, otherwise false. Raises ValueError if the hash was not formatted correctly.

  path
    A file path
  hash
    A string in the form <hash_type>=<hash_value>. For example: `md5=e138491e9d5b97023cea823fe17bac22`

`salt.modules.file.` `check_managed`(name, source, source_hash, user, group, mode, template, makedirs, context, defaults, env, **kwargs)

  Check to see what changes need to be made for a file

`salt.modules.file.` `check_perms`(name, ret, user, group, mode)

  Check the permissions on files and chown if needed

  Note: 'mode' here is expected to be either a string or an integer,

    in which case it will be converted into a base-10 string.

    What this means is that in your YAML salt file, you can specify mode as an integer(eg, 644) or as a string(eg, '644'). But, to specify mode 0777, for example, it must be specified as the string, '0777' otherwise, 0777 will be parsed as an octal and you'd get 511 instead.

`salt.modules.file.` `chgrp`(path, group)

  Change the group of a file

  CLI Example:

      salt '*' file.chgrp /etc/passwd root

`salt.modules.file.` `chown`(path, user, group)

  Chown a file, pass the file the desired user and group

  CLI Example:

      salt '*' file.chown /etc/passwd root root

`salt.modules.file.` `comment`(path, regex, char='#', backup='.bak')

  Comment out specified lines in a file

  path
    The full path to the file to be edited
  regex
    A regular expression used to find the lines that are to be commented; this pattern will be wrapped in parenthesis and will move any preceding/trailing `^` or `$` characters outside the parenthesis (e.g., the pattern `^foo$` will be rewritten as `^(foo)$`)
  char : `#`
    The character to be inserted at the beginning of a line in order to comment it out
  backup : `.bak`

    The file will be backed up before edit with this file extension

    Warning

    This backup will be overwritten each time `sed` / `comment` / `uncomment` is called. Meaning the backup will only be useful after the first invocation.

  CLI Example:

      salt '*' file.comment /etc/modules pcspkr

  New in version 0.9.5.

`salt.modules.file.` `contains`(path, text)

  Return True if the file at `path` contains `text`

  CLI Example:

      salt '*' file.contains /etc/crontab 'mymaintenance.sh'

  New in version 0.9.5.

`salt.modules.file.` `contains_glob`(path, glob)

  Return True if the given glob matches a string in the named file

  CLI Example:

      salt '*' /etc/foobar '*cheese*'

`salt.modules.file.` `contains_regex`(path, regex, lchar='')

  Return True if the given regular expression matches anything in the text of a given file

  CLI Example:

      salt '*' /etc/crontab '^maint'

`salt.modules.file.` `directory_exists`(path)

  Tests to see if path is a valid directory. Returns True/False.

  CLI Example:

      salt '*' file.directory_exists /etc

`salt.modules.file.` `file_exists`(path)

  Tests to see if path is a valid file. Returns True/False.

  CLI Example:

      salt '*' file.file_exists /etc/passwd

`salt.modules.file.` `find`(path, **kwargs)

  Approximate the Unix find(1) command and return a list of paths that meet the specified critera.

  The options include match criteria:

      name    = path-glob                 # case sensitive
      iname   = path-glob                 # case insensitive
      regex   = path-regex                # case sensitive
      iregex  = path-regex                # case insensitive
      type    = file-types                # match any listed type
      user    = users                     # match any listed user
      group   = groups                    # match any listed group
      size    = [+-]number[size-unit]     # default unit = byte
      mtime   = interval                  # modified since date
      grep    = regex                     # search file contents

  and/or actions:

      delete [= file-types]               # default type = 'f'
      exec    = command [arg ...]         # where {} is replaced by pathname
      print  [= print-opts]

  The default action is 'print=path'.

  file-glob:

      *                = match zero or more chars
      ?                = match any char
      [abc]            = match a, b, or c
      [!abc] or [^abc] = match anything except a, b, and c
      [x-y]            = match chars x through y
      [!x-y] or [^x-y] = match anything except chars x through y
      {a,b,c}          = match a or b or c

  path-regex: a Python re (regular expression) pattern to match pathnames

  file-types: a string of one or more of the following:

      a: all file types
      b: block device
      c: character device
      d: directory
      p: FIFO (named pipe)
      f: plain file
      l: symlink
      s: socket

  users: a space and/or comma separated list of user names and/or uids

  groups: a space and/or comma separated list of group names and/or gids

  size-unit:

      b: bytes
      k: kilobytes
      m: megabytes
      g: gigabytes
      t: terabytes

  interval:

      [<num>w] [<num>[d]] [<num>h] [<num>m] [<num>s]

      where:
          w: week
          d: day
          h: hour
          m: minute
          s: second

  print-opts: a comma and/or space separated list of one or more of the following:

      group: group name
      md5:   MD5 digest of file contents
      mode:  file permissions (as integer)
      mtime: last modification time (as time_t)
      name:  file basename
      path:  file absolute path
      size:  file size in bytes
      type:  file type
      user:  user name

  CLI Examples:

      salt '*' file.find / type=f name=\*.bak size=+10m
      salt '*' file.find /var mtime=+30d size=+10m print=path,size,mtime
      salt '*' file.find /var/log name=\*.[0-9] mtime=+30d size=+10m delete

`salt.modules.file.` `get_gid`(path)

  Return the id of the group that owns a given file

  CLI Example:

      salt '*' file.get_gid /etc/passwd

`salt.modules.file.` `get_group`(path)

  Return the group that owns a given file

  CLI Example:

      salt '*' file.get_group /etc/passwd

`salt.modules.file.` `get_hash`(path, form='md5', chunk_size=4096)

  Get the hash sum of a file

  This is better than `get_sum` for the following reasons:

    - It does not read the entire file into memory.

    - It does not return a string on error. The returned value of

        `get_sum` cannot really be trusted since it is vulnerable to collisions: `get_sum(..., 'xyz') == 'Hash xyz not supported'`

`salt.modules.file.` `get_managed`(name, template, source, source_hash, user, group, mode, env, context, defaults, **kwargs)

  Return the managed file data for file.managed

`salt.modules.file.` `get_mode`(path)

  Return the mode of a file

  CLI Example:

      salt '*' file.get_mode /etc/passwd

`salt.modules.file.` `get_selinux_context`(path)

  Get an SELinux context from a given path

  CLI Example:

      salt '*' selinux.get_context /etc/hosts

`salt.modules.file.` `get_sum`(path, form='md5')

  Return the sum for the given file, default is md5, sha1, sha224, sha256, sha384, sha512 are supported

  CLI Example:

      salt '*' file.get_sum /etc/passwd sha512

`salt.modules.file.` `get_uid`(path)

  Return the id of the user that owns a given file

  CLI Example:

      salt '*' file.get_uid /etc/passwd

`salt.modules.file.` `get_user`(path)

  Return the user that owns a given file

  CLI Example:

      salt '*' file.get_user /etc/passwd

`salt.modules.file.` `gid_to_group`(gid)

  Convert the group id to the group name on this system

  CLI Example:

      salt '*' file.gid_to_group 0

`salt.modules.file.` `group_to_gid`(group)

  Convert the group to the gid on this system

  CLI Example:

      salt '*' file.group_to_gid root

`salt.modules.file.` `makedirs`(path, user=None, group=None, mode=None)

  Ensure that the directory containing this path is available.

`salt.modules.file.` `makedirs_perms`(name, user=None, group=None, mode=493)

  Taken and modified from os.makedirs to set user, group and mode for each directory created.

`salt.modules.file.` `manage_file`(name, sfn, ret, source, source_sum, user, group, mode, env, backup)

  Checks the destination against what was retrieved with get_managed and makes the appropriate modifications (if necessary).

`salt.modules.file.` `patch`(originalfile, patchfile, options='', dry_run=False)

  Apply a patch to a file

  Equivalent to:

      patch <options> <originalfile> <patchfile>

  originalfile
    The full path to the file or directory to be patched
  patchfile
    A patch file to apply to `originalfile`
  options
    Options to pass to patch.

  CLI Example:

      salt '*' file.patch /opt/file.txt /tmp/file.txt.patch

  New in version 0.10.4.

`salt.modules.file.` `remove`(path)

`salt.modules.file.` `restorecon`(path, recursive=False)

  Reset the SELinux context on a given path

  CLI Example:

      salt '*' selinux.restorecon /home/user/.ssh/authorized_keys

`salt.modules.file.` `sed`(path, before, after, limit='', backup='.bak', options='-r -e', flags='g', escape_all=False)

  Make a simple edit to a file

  Equivalent to:

      sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"

  path
    The full path to the file to be edited
  before
    A pattern to find in order to replace with `after`
  after
    Text that will replace `before`
  limit : `''`
    An initial pattern to search for before searching for `before`
  backup : `.bak`
    The file will be backed up before edit with this file extension; WARNING: each time `sed`/`comment`/`uncomment` is called will overwrite this backup
  options : `-r -e`
    Options to pass to sed
  flags : `g`
    Flags to modify the sed search; e.g., `i` for case-insensitve pattern matching

  Forward slashes and single quotes will be escaped automatically in the `before` and `after` patterns.

  CLI Example:

      salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'

  New in version 0.9.5.

`salt.modules.file.` `set_mode`(path, mode)

  Set the mode of a file

  CLI Example:

      salt '*' file.set_mode /etc/passwd 0644

`salt.modules.file.` `set_selinux_context`(path, user=None, role=None, type=None, range=None)

  Set a specific SELinux label on a given path

  CLI Example:

      salt '*' selinux.chcon path <role> <type> <range>

`salt.modules.file.` `source_list`(source, source_hash, env)

  Check the source list and return the source to use

`salt.modules.file.` `stats`(path, hash_type='md5', follow_symlink=False)

  Return a dict containing the stats for a given file

  CLI Example:

      salt '*' file.stats /etc/passwd

`salt.modules.file.` `touch`(name, atime=None, mtime=None)

  Just like 'nix's "touch" command, create a file if it doesn't exist or simply update the atime and mtime if it already does.

  atime:
    Access time in Unix epoch time
  mtime:
    Last modification in Unix epoch time

  CLI Example:

      salt '*' file.touch /var/log/emptyfile

  New in version 0.9.5.

`salt.modules.file.` `uid_to_user`(uid)

  Convert a uid to a user name

  CLI Example:

      salt '*' file.uid_to_user 0

`salt.modules.file.` `uncomment`(path, regex, char='#', backup='.bak')

  Uncomment specified commented lines in a file

  path
    The full path to the file to be edited
  regex
    A regular expression used to find the lines that are to be uncommented. This regex should not include the comment character. A leading `^` character will be stripped for convenience (for easily switching between comment() and uncomment()).
  char : `#`
    The character to remove in order to uncomment a line; if a single whitespace character follows the comment it will also be removed
  backup : `.bak`
    The file will be backed up before edit with this file extension; WARNING: each time `sed`/`comment`/`uncomment` is called will overwrite this backup

  CLI Example:

      salt '*' file.uncomment /etc/hosts.deny 'ALL: PARANOID'

  New in version 0.9.5.

`salt.modules.file.` `user_to_uid`(user)

  Convert user name to a uid

  CLI Example:

      salt '*' file.user_to_uid root

## Comments

comments powered by Disqus

### Navigation

- index
- modules |
- next |
- previous |
- « SaltStack.org |
- Documentation home
- Full list of builtin execution modules »