salt.states.file

### Navigation

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

# salt.states.file

## Operations on files, directories and symlinks.

Salt States can aggressively manipulate files on a system. There are a number of ways in which files can be managed.

Regular files can be enforced with the `managed` function. This function downloads files from the salt master and places them on the target system. The downloaded files can be rendered as a jinja, mako, or wempy template adding a dynamic component to file management. An example of `file.managed` which makes use of the jinja templating system would look like this:

    /etc/http/conf/http.conf:
      file.managed:
        - source: salt://apache/http.conf
        - user: root
        - group: root
        - mode: 644
        - template: jinja
        - context:
            custom_var: "override"
        - defaults:
            custom_var: "default value"
            other_var: 123

Directories can be managed via the `directory` function. This function can create and enforce the permissions on a directory. A directory statement will look like this:

    /srv/stuff/substuf:
      file.directory:
        - user: fred
        - group: users
        - mode: 755
        - makedirs: True

If you need to enforce user and/or group ownership recursively on the directory's contents, you can do so by adding a `recurse` directive:

    /srv/stuff/substuf:
      file.directory:
        - user: fred
        - group: users
        - mode: 755
        - makedirs: True
        - recurse:
          - user
          - group

Symlinks can be easily created, the symlink function is very simple and only takes a few arguments:

    /etc/grub.conf:
      file.symlink:
        - target: /boot/grub/grub.conf

Recursive directory management can also be set via the `recurse` function. Recursive directory management allows for a directory on the salt master to be recursively copied down to the minion. This is a great tool for deploying large code and configuration systems. A recurse state would look something like this:

    /opt/code/flask:
      file.recurse:
        - source: salt://code/flask

`salt.states.file.` `absent`(name)

  Verify that the named file or directory is absent, this will work to reverse any of the functions in the file state module.

  name
    The path which should be deleted

`salt.states.file.` `accumulated`(name, filename, text, **kwargs)

  Prepare accumulator which can be used in template in file.managed state. accumulator dictionary becomes available in template.

  name
    Accumulator name
  filename
    Filename which would receive this accumulator (see file.managed state documentation about ''name``)
  text
    String or list for adding in accumulator
  require_in / watch_in
    One of them required for sure we fill up accumulator before we manage the file. Probably the same as filename

`salt.states.file.` `append`(name, text=None, makedirs=False, source=None, source_hash=None)

  Ensure that some text appears at the end of a file

  The text will not be appended again if it already exists in the file. You may specify a single line of text or a list of lines to append.

  Multi-line example:

      /etc/motd:
        file.append:
          - text: |
              Thou hadst better eat salt with the Philosophers of Greece,
              than sugar with the Courtiers of Italy.
              - Benjamin Franklin

  Multiple lines of text:

      /etc/motd:
        file.append:
          - text:
            - Trust no one unless you have eaten much salt with him.
            - Salt is born of the purest of parents: the sun and the sea.

  New in version 0.9.5.

`salt.states.file.` `comment`(name, 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.

  Usage:

      /etc/fstab:
        file.comment:
          - regex: ^bind 127.0.0.1

  New in version 0.9.5.

`salt.states.file.` `directory`(name, user=None, group=None, recurse=[], mode=None, makedirs=False, clean=False, require=None, exclude_pat=None)

  Ensure that a named directory is present and has the right perms

  name
    The location to create or manage a directory
  user
    The user to own the directory, this defaults to the user salt is running as on the minion
  group
    The group ownership set for the directory, this defaults to the group salt is running as on the minion
  recurse
    Enforce user/group ownership of directory recursively
  mode
    The permissions to set on this directory, aka 755
  makedirs
    If the directory is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file.
  clean
    Make sure that only files that are set up by salt and required by this function are kept. If this option is set then everything in this directory will be deleted unless it is required.
  require
    Require other resources such as packages or files
  exclude_pat
    When 'clean' is set to True, exclude this pattern from removal list and preserve in the destination.

`salt.states.file.` `exists`(name)

  Verify that the named file or directory is present or exists. Ensures pre-requisites outside of salts per-vue have been previously satisified (aka, keytabs, private keys, etc.) before deployment

  name
    Absolute path which must exist

`salt.states.file.` `managed`(name, source=None, source_hash='', user=None, group=None, mode=None, template=None, makedirs=False, context=None, replace=True, defaults=None, env=None, backup='', **kwargs)

  Manage a given file, this function allows for a file to be downloaded from the salt master and potentially run through a templating system.

  name
    The location of the file to manage
  source

    The source file to download to the minion, this source file can be hosted on either the salt master server, or on an http or ftp server. For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs. If source is left blank or None, the file will be created as an empty file and the content will not be managed

    If the file is hosted on a http or ftp server then the source_hash argument is also required

  source_hash:

    This can be either a file which contains a source hash string for the source, or a source hash string. The source hash string is the hash algorithm followed by the hash of the file: md5=e138491e9d5b97023cea823fe17bac22

    The file can contain checksums for several files, in this case every line must consist of full name of the file and checksum separated by space:

    /etc/rc.conf md5=ef6e82e4006dee563d98ada2a2a80a27 /etc/resolv.conf sha256=c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a

  user
    The user to own the file, this defaults to the user salt is running as on the minion
  group
    The group ownership set for the file, this defaults to the group salt is running as on the minion
  mode
    The permissions to set on this file, aka 644, 0775, 4664
  template
    If this setting is applied then the named templating engine will be used to render the downloaded file, currently jinja, mako, and wempy are supported
  makedirs
    If the file is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file.
  replace
    If this file should be replaced. If false, this command will not overwrite file contents but will enforce permissions if the file exists already. Default is true.
  context
    Overrides default context variables passed to the template.
  defaults
    Default context passed to the template.
  backup
    Overrides the default backup mode for this specific file

`salt.states.file.` `patch`(name, source=None, hash=None, options='', dry_run_first=True, env='base')

  Apply a patch to a file. Note: a suitable `patch` executable must be available on the minion when using this state function.

  name
    The file to with the patch will be applied.
  source
    The source patch to download to the minion, this source file must be hosted on the salt master server. If the file is located in the directory named spam, and is called eggs, the source string is salt://spam/eggs. A source is required.
  hash
    Hash of the patched file. If the hash of the target file matches this value then the patch is assumed to have been applied. The hash string is the hash algorithm followed by the hash of the file: md5=e138491e9d5b97023cea823fe17bac22
  options
    Extra options to pass to patch.
  dry_run_first : `True`
    Run patch with `--dry-run` first to check if it will apply cleanly.

  Usage:

      # Equivalent to ``patch --forward /opt/file.txt file.patch``
      /opt/file.txt:
        file.patch:
          - source: salt://file.patch
          - hash: md5=e138491e9d5b97023cea823fe17bac22

`salt.states.file.` `recurse`(name, source, clean=False, require=None, user=None, group=None, dir_mode=None, file_mode=None, template=None, context=None, defaults=None, env=None, include_empty=False, backup='', include_pat=None, exclude_pat=None, **kwargs)

  Recurse through a subdirectory on the master and copy said subdirecory over to the specified path.

  name
    The directory to set the recursion in
  source
    The source directory, this directory is located on the salt master file server and is specified with the salt:// protocol. If the directory is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs
  clean
    Make sure that only files that are set up by salt and required by this function are kept. If this option is set then everything in this directory will be deleted unless it is required.
  require
    Require other resources such as packages or files
  user
    The user to own the directory, this defaults to the user salt is running as on the minion
  group
    The group ownership set for the directory, this defaults to the group salt is running as on the minion
  dir_mode
    The permissions mode to set any directories created
  file_mode
    The permissions mode to set any files created
  template
    If this setting is applied then the named templating engine will be used to render the downloaded file, currently jinja, mako, and wempy are supported
  context
    Overrides default context variables passed to the template.
  defaults
    Default context passed to the template.
  include_empty
    Set this to True if empty directories should also be created (default is False)
  include_pat

    When copying, include only this pattern from the source. Default is glob match , if prefixed with E@ then regexp match Example:

        - include_pat: hello*       :: glob matches 'hello01', 'hello02' ... but not 'otherhello'
        - include_pat: E@hello      :: regexp matches 'otherhello', 'hello01' ...

  exclude_pat

    When copying, exclude this pattern from the source. If both include_pat and exclude_pat are supplied, then it will apply conditions cumulatively. i.e. first select based on include_pat and then with in that result, applies exclude_pat.

    Also when 'clean=True', exclude this pattern from the removal list and preserve in the destination. Example:

        - exclude: APPDATA*               :: glob matches APPDATA.01, APPDATA.02,.. for exclusion
        - exclude: E@(APPDATA)|(TEMPDATA) :: regexp matches APPDATA or TEMPDATA for exclusion

`salt.states.file.` `rename`(name, source, force=False, makedirs=False)

  If the source file exists on the system, rename it to the named file. The named file will not be overwritten if it already exists unless the force option is set to True.

  name
    The location of the file to rename to
  source
    The location of the file to move to the location specified with name
  force:
    If the target location is present then the file will not be moved, specify "force: True" to overwrite the target file
  makedirs:
    If the target subdirectories don't exist create them

`salt.states.file.` `sed`(name, before, after, limit='', backup='.bak', options='-r -e', flags='g')

  Maintain a simple edit to a file

  The file will be searched for the `before` pattern before making the edit and then searched for the `after` pattern to verify the edit was successful using `salt.modules.file.contains`. In general the `limit` pattern should be as specific as possible and `before` and `after` should contain the minimal text to be changed.

  Usage:

      # Disable the epel repo by default
      /etc/yum.repos.d/epel.repo:
        file.sed:
          - before: 1
          - after: 0
          - limit: ^enabled=

      # Remove ldap from nsswitch
      /etc/nsswitch.conf:
        file.sed:
          - before: 'ldap'
          - after: ''
          - limit: '^passwd:'

  New in version 0.9.5.

`salt.states.file.` `symlink`(name, target, force=False, makedirs=False)

  Create a symlink

  name
    The location of the symlink to create
  target
    The location that the symlink points to
  force
    If the location of the symlink exists and is not a symlink then the state will fail, set force to True and any file or directory in the way of the symlink file will be deleted to make room for the symlink
  makedirs
    If the location of the symlink does not already have a parent directory then the state will fail, setting makedirs to True will allow Salt to create the parent directory

`salt.states.file.` `touch`(name, atime=None, mtime=None, makedirs=False)

  Replicate the 'nix "touch" command to create a new empty file or update the atime and mtime of an existing file.

  Usage:

      /var/log/httpd/logrotate.empty:
        file.touch

  New in version 0.9.5.

`salt.states.file.` `uncomment`(name, 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

  Usage:

      /etc/adduser.conf:
        file.uncomment:
          - regex: EXTRA_GROUPS

  New in version 0.9.5.

## Comments

comments powered by Disqus

### Navigation

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