# salt.modules.file

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

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

  New in version 0.9.5.

  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."

`salt.modules.file.` `blockreplace`(path, marker_start='#-- start managed zone --', marker_end='#-- end managed zone --', content='', append_if_not_found=False, backup='.bak', dry_run=False, show_changes=True)

  Replace content of a text block in a file, delimited by line markers

  New in version Hydrogen.

  A block of content delimited by comments can help you manage several lines entries without worrying about old entries removal.

  Note

  This function will store two copies of the file in-memory (the original version and the edited version) in order to detect changes and only edit the targeted file if necessary.

  path
    Filesystem path to the file to be edited
  marker_start
    The line content identifying a line as the start of the content block. Note that the whole line containing this marker will be considered, so whitespaces or extra content before or after the marker is included in final output
  marker_end
    The line content identifying a line as the end of the content block. Note that the whole line containing this marker will be considered, so whitespaces or extra content before or after the marker is included in final output
  content
    The content to be used between the two lines identified by marker_start and marker_stop.
  append_if_not_found : False
    If markers are not found and set to `True` then, the markers and content will be appended to the file.
  backup
    The file extension to use for a backup of the file if any edit is made. Set to `False` to skip making a backup.
  dry_run
    Don't make any edits to the file.
  show_changes
    Output a unified diff of the old file and the new file. If `False`, return a boolean if any changes were made.

  CLI Example:

      salt '*' file.blockreplace /etc/hosts '#-- start managed zone foobar : DO NOT EDIT --' \
      '#-- end managed zone foobar --' $'10.0.1.1 foo.foobar\n10.0.1.2 bar.foobar' True

`salt.modules.file.` `check_file_meta`(name, sfn, source, source_sum, user, group, mode, saltenv, template=None, contents=None)

  Check for the changes in the file metadata.

  CLI Example:

      salt '*' file.check_file_meta /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' base

`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`

  CLI Example:

      salt '*' file.check_hash /etc/fstab md5=<md5sum>

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

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

  CLI Example:

      salt '*' file.check_managed /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' jinja True None None base

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

  Check the permissions on files and chown if needed

  CLI Example:

      salt '*' file.check_perms /etc/sudoers '{}' root root 400

`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')

  Deprecated since version 0.17.0: Use `replace()` instead.

  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

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

  Deprecated since version 0.17.0: Use `search()` instead.

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

  CLI Example:

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

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

  Deprecated since version 0.17.0: Use `search()` instead.

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

  CLI Example:

      salt '*' file.contains_glob /etc/foobar '*cheese*'

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

  Deprecated since version 0.17.0: Use `search()` instead.

  Return True if the given regular expression matches on any line in the text of a given file.

  If the lchar argument (leading char) is specified, it will strip lchar from the left side of each line before trying to match

  CLI Example:

      salt '*' file.contains_regex /etc/crontab

`salt.modules.file.` `contains_regex_multiline`(path, regex)

  Deprecated since version 0.17.0: Use `search()` instead.

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

  Traverses multiple lines at a time, via the salt BufferedReader (reads in chunks)

  CLI Example:

      salt '*' file.contains_regex_multiline /etc/crontab '^maint'

`salt.modules.file.` `copy`(src, dst)

  Copy a file or directory

  CLI Example:

      salt '*' file.copy /path/to/src /path/to/dst

`salt.modules.file.` `delete_backup`(path, backup_id)

  Restore a previous version of a file that was backed up using Salt's file state backup system.

  New in version 0.17.0.

  path
    The path on the minion to check for backups
  backup_id
    The numeric id for the backup you wish to delete, as found using `file.list_backups`

  CLI Example:

      salt '*' file.restore_backup /foo/bar/baz.txt 0

`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 criteria.

  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_devmm`(name)

  Get major/minor info from a device

  CLI Example:

      salt '*' file.get_devmm /dev/chr

`salt.modules.file.` `get_diff`(minionfile, masterfile, env=None, saltenv='base')

  Return unified diff of file compared to file on master

  CLI Example:

      salt '*' file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc

`salt.modules.file.` `get_gid`(path, follow_symlinks=True)

  Return the id of the group that owns a given file

  CLI Example:

      salt '*' file.get_gid /etc/passwd

  Changed in version 0.16.4: `follow_symlinks` option added

`salt.modules.file.` `get_group`(path, follow_symlinks=True)

  Return the group that owns a given file

  CLI Example:

      salt '*' file.get_group /etc/passwd

  Changed in version 0.16.4: `follow_symlinks` option added

`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'`

  CLI Example:

      salt '*' file.get_hash /etc/shadow

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

  Return the managed file data for file.managed

  CLI Example:

      salt '*' file.get_managed /etc/httpd/conf.d/httpd.conf jinja salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' base None None

`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 '*' file.get_selinux_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, follow_symlinks=True)

  Return the id of the user that owns a given file

  CLI Example:

      salt '*' file.get_uid /etc/passwd

  Changed in version 0.16.4: `follow_symlinks` option added

`salt.modules.file.` `get_user`(path, follow_symlinks=True)

  Return the user that owns a given file

  CLI Example:

      salt '*' file.get_user /etc/passwd

  Changed in version 0.16.4: `follow_symlinks` option added

`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.` `is_blkdev`(name)

  Check if a file exists and is a block device.

  CLI Example:

      salt '*' file.is_blkdev /dev/blk

`salt.modules.file.` `is_chrdev`(name)

  Check if a file exists and is a character device.

  CLI Example:

      salt '*' file.is_chrdev /dev/chr

`salt.modules.file.` `is_fifo`(name)

  Check if a file exists and is a FIFO.

  CLI Example:

      salt '*' file.is_fifo /dev/fifo

`salt.modules.file.` `list_backups`(path, limit=None)

  Lists the previous versions of a file backed up using Salt's file state backup system.

  New in version 0.17.0.

  path
    The path on the minion to check for backups
  limit
    Limit the number of results to the most recent N backups

  CLI Example:

      salt '*' file.list_backups /foo/bar/baz.txt

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

  Ensure that the directory containing this path is available.

  CLI Example:

      salt '*' file.makedirs /opt/code

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

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

  CLI Example:

      salt '*' file.makedirs_perms /opt/code

`salt.modules.file.` `manage_file`(name, sfn, ret, source, source_sum, user, group, mode, saltenv, backup, template=None, show_diff=True, contents=None, dir_mode=None)

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

  CLI Example:

      salt '*' file.manage_file /etc/httpd/conf.d/httpd.conf '{}' salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' base ''

`salt.modules.file.` `mkdir`(dir_path, user=None, group=None, mode=None)

  Ensure that a directory is available.

  CLI Example:

      salt '*' file.mkdir /opt/jetty/context

`salt.modules.file.` `mknod`(name, ntype, major=0, minor=0, user=None, group=None, mode='0600')

  > Create a block device, character device, or fifo pipe. Identical to the gnu mknod.

  > CLI Examples:

      salt '*' file.mknod /dev/chr c 180 31
      salt '*' file.mknod /dev/blk b 8 999
      salt '*' file.nknod /dev/fifo p

`salt.modules.file.` `mknod_blkdev`(name, major, minor, user=None, group=None, mode='0660')

  Create a block device.

  CLI Example:

      salt '*' file.mknod_blkdev /dev/blk 8 999

`salt.modules.file.` `mknod_chrdev`(name, major, minor, user=None, group=None, mode='0660')

  Create a character device.

  CLI Example:

      salt '*' file.mknod_chrdev /dev/chr 180 31

`salt.modules.file.` `mknod_fifo`(name, user=None, group=None, mode='0660')

  Create a FIFO pipe.

  CLI Example:

      salt '*' file.mknod_fifo /dev/fifo

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

  New in version 0.10.4.

  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

`salt.modules.file.` `psed`(path, before, after, limit='', backup='.bak', flags='gMS', escape_all=False, multi=False)

  Deprecated since version 0.17.0: Use `replace()` instead.

  Make a simple edit to a file (pure Python version)

  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
  flags : `gMS`
    Flags to modify the search. Valid values are:
      - `g`: Replace all occurrences of the pattern, not just the first.
      - `I`: Ignore case.
      - `L`: Make `\w`, `\W`, `\b`, `\B`, `\s` and `\S` dependent on the locale.
      - `M`: Treat multiple lines as a single line.
      - `S`: Make . match all characters, including newlines.
      - `U`: Make `\w`, `\W`, `\b`, `\B`, `\d`, `\D`, `\s` and `\S` dependent on Unicode.
      - `X`: Verbose (whitespace is ignored).
  multi: `False`
    If True, treat the entire file as a single line

  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'

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

  Remove the named file

  CLI Example:

      salt '*' file.remove /tmp/foo

`salt.modules.file.` `rename`(src, dst)

  Rename a file or directory

  CLI Example:

      salt '*' file.rename /path/to/src /path/to/dst

`salt.modules.file.` `replace`(path, pattern, repl, count=0, flags=0, bufsize=1, backup='.bak', dry_run=False, search_only=False, show_changes=True)

  Replace occurances of a pattern in a file

  New in version 0.17.0.

  This is a pure Python implementation that wraps Python's `sub()`.

  Parameters: | path -- Filesystem path to the file to be edited pattern -- The PCRE search repl -- The replacement text count -- Maximum number of pattern occurrences to be replaced flags (list or int) -- A list of flags defined in the re module documentation. Each list item should be a string that will correlate to the human-friendly flag name. E.g., `['IGNORECASE', 'MULTILINE']`. Note: multiline searches must specify `file` as the `bufsize` argument below. bufsize (int or str) -- How much of the file to buffer into memory at once. The default value `1` processes one line at a time. The special value `file` may be specified which will read the entire file into memory before processing. Note: multiline searches must specify `file` buffering. backup -- The file extension to use for a backup of the file before editing. Set to `False` to skip making a backup. dry_run -- Don't make any edits to the file search_only -- Just search for the pattern; ignore the replacement; stop on the first match show_changes -- Output a unified diff of the old file and the new file. If `False` return a boolean if any changes were made. Note: using this option will store two copies of the file in-memory (the original version and the edited version) in order to generate the diff.
  Return type: | bool or str

  CLI Example:

      salt '*' file.replace /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'
      salt '*' file.replace /some/file 'before' 'after' flags='[MULTILINE, IGNORECASE]'

`salt.modules.file.` `restore_backup`(path, backup_id)

  Restore a previous version of a file that was backed up using Salt's file state backup system.

  New in version 0.17.0.

  path
    The path on the minion to check for backups
  backup_id
    The numeric id for the backup you wish to restore, as found using `file.list_backups`

  CLI Example:

      salt '*' file.restore_backup /foo/bar/baz.txt 0

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

  Reset the SELinux context on a given path

  CLI Example:

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

`salt.modules.file.` `search`(path, pattern, flags=0, bufsize=1)

  Search for occurances of a pattern in a file

  New in version 0.17.0.

  Params are identical to `replace()`.

  CLI Example:

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

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

  Deprecated since version 0.17.0: Use `replace()` instead.

  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
  negate_match : False

    Negate the search command (`!`)

    New in version 0.17.0.

  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'

`salt.modules.file.` `sed_contains`(path, text, limit='', flags='g')

  Deprecated since version 0.17.0: Use `search()` instead.

  Return True if the file at `path` contains `text`. Utilizes sed to perform the search (line-wise search).

  Note: the `p` flag will be added to any flags you pass in.

  CLI Example:

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

`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 '*' file.set_selinux_context path <role> <type> <range>

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

  Check the source list and return the source to use

  CLI Example:

      salt '*' file.source_list salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' base

`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.` `symlink`(src, link)

  Create a symbolic link to a file

  CLI Example:

      salt '*' file.symlink /path/to/file /path/to/link

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

  New in version 0.9.5.

  Just like the `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

`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')

  Deprecated since version 0.17.0: Use `replace()` instead.

  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
  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'

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

  Convert user name to a uid

  CLI Example:

      salt '*' file.user_to_uid root

Current Salt release: 0.17.1

#### Previous topic

salt.modules.extfs

#### Next topic

salt.modules.freebsd_sysctl

### Quick search

Enter search terms or a module, class or function name.

### Upcoming SaltStack Events

My conferences on Lanyrd