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)$) Note that you _need_ the leading ^, otherwise each time you run highstate, another comment char will be inserted.

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=None, mode=None, makedirs=False, clean=False, require=None, exclude_pat=None, **kwargs)

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:

Example:

/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, user=None, group=None, mode=None, **kwargs)

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.