neulab/tldr huggingface dataset:
Gather text from multiple template files:
/etc/motd: file: - append - template: jinja - sources: - salt://motd/devops-messages.tmpl - salt://motd/hr-messages.tmpl - salt://motd/general-messages.tmpl
New in version 0.9.5.
salt.states.file.blockreplace(name, marker_start='#-- start managed zone --', marker_end='#-- end managed zone --', source=None, source_hash=None, template='jinja', sources=None, source_hashes=None, defaults=None, context=None, content='', append_if_not_found=False, prepend_if_not_found=False, backup='.bak', show_changes=True, append_newline=None, insert_before_match=None, insert_after_match=None) Maintain an edit in a file in a zone delimited by two line markers
Changed in version 2017.7.5,2018.3.1: append_newline argument added. Additionally, to improve idempotence, if the string represented by marker_end is found in the middle of the line, the content preceding the marker will be removed when the block is replaced. This allows one to remove append_newline: False from the SLS and have the block properly replaced if the end of the content block is immediately followed by the marker_end (i.e. no newline before the marker).
A block of content delimited by comments can help you manage several lines entries without worrying about old entries removal. This can help you maintaining an un-managed file containing manual edits.
Additionally, you can use file.accumulated and target this state. All accumulated data dictionaries' content will be added in the content block.
name   Filesystem path to the file to be edited
content The content to be used between the two lines identified by marker_start and marker_end
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.  Both HTTPS and HTTP are supported as well as downloading directly from Amazon S3 compatible URLs with both pre-configured and automatic IAM credentials. (see s3.get state documentation) File retrieval from Openstack Swift object storage is supported via swift://container/object_path URLs, see swift.get documentation.  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 (use ~ in YAML), the file will be created as an empty file and the content will not be managed. This is also the case when a file already exists and the source is undefined; the contents of the file will not be changed or managed.
If the file is hosted on a HTTP or FTP server then the source_hash argument is also required.
A list of sources can also be passed in to provide a default source and a set of fallbacks. The first source in the list that is found to exist will be used and subsequent entries in the list will be ignored.
file_override_example: file.blockreplace: - name: /etc/example.conf - source: - salt://file_that_does_not_exist - salt://file_that_exists
template Templating engine to be used to render the downloaded file. The following engines are supported:
context Overrides default context variables passed to the template
defaults Default context passed to the template
append_if_not_found If markers are not found and this option is set to True, the content block will be appended to the file.
prepend_if_not_found If markers are not found and this option is set to True, the content block will be prepended to the file.
backup The file extension to use for a backup of the file if any edit is made.  Set this to False to skip making a backup.
dry_run If True, do not make any edits to the file and simply return the changes that would be made.
show_changes Controls how changes are presented. If True, the Changes section of the state return will contain a unified diff of the changes made. If False, then it will contain a boolean (True if any changes were made, otherwise False).
append_newline Controls whether or not a newline is appended to the content block. If the value of this argument is True then a newline will be added to the content block. If it is False, then a newline will not be added to the content block. If it is unspecified, then a newline will only be added to the content block if it does not already end in a newline.
Example of usage with an accumulator and with a variable:
{% set myvar = 42 %} hosts-config-block-{{ myvar }}: file.blockreplace: - name: /etc/hosts - marker_start: "# START managed zone {{ myvar }} -DO-NOT-EDIT-" - marker_end: "# END managed zone {{ myvar }} --" - content: 'First line of content' - append_if_not_found: True - backup: '.bak' - show_changes: True
hosts-config-block-{{ myvar }}-accumulated1: file.accumulated: - filename: /etc/hosts - name: my-accumulator-{{ myvar }} - text: "text 2" - require_in: - file: hosts-config-block-{{ myvar }}
hosts-config-block-{{ myvar }}-accumulated2: file.accumulated: - filename: /etc/hosts - name: my-accumulator-{{ myvar }} - text: | text 3 text 4 - require_in: - file: hosts-config-block-{{ myvar }}
will generate and maintain a block of content in /etc/hosts:
# START managed zone 42 -DO-NOT-EDIT- First line of content text 2 text 3 text 4 # END managed zone 42 --
salt.states.file.cached(name, source_hash='', source_hash_name=None, skip_verify=False, saltenv='base') New in version 2017.7.3.
Ensures that a file is saved to the minion's cache. This state is primarily invoked by other states to ensure that we do not re-download a source file if we do not need to.
name   The URL of the file to be cached. To cache a file from an environment other than base, either use the saltenv argument or include the saltenv in the URL (e.g. salt://path/to/file.conf?saltenv=dev).
NOTE: A list of URLs is not supported, this must be a single URL. If a local file is passed here, then the state will obviously not try to download anything, but it will compare a hash if one is specified.
source_hash See the documentation for this same argument in the file.managed state.
NOTE: For remote files not originating from the salt:// fileserver, such as http(s) or ftp servers, this state will not re-download the file if the locally-cached copy matches this hash. This is done to prevent unnecessary downloading on repeated runs of this state. To update the cached copy of a file, it is necessary to update this hash.
source_hash_name See the documentation for this same argument in the file.managed state.
skip_verify See the documentation for this same argument in the file.managed state.
NOTE: Setting this to True will result in a copy of the file being downloaded from a remote (http(s), ftp, etc.) source each time the state is run.
saltenv Used to specify the environment from which to download a file from the Salt fileserver (i.e. those with salt:// URL).
This state will in most cases not be useful in SLS files, but it is useful when writing a state or remote-execution module that needs to make sure that a file at a given URL has been downloaded to the cachedir. One example of this is in the archive.extracted state:
result = __states__['file.cached'](source_match, source_hash=source_hash, source_hash_name=source_hash_name, skip_verify=skip_verify, saltenv=__env__)
This will return a dictionary containing the state's return data, including a result key which will state whether or not the state was successful.  Note that this will not catch exceptions, so it is best used within a try/except.
Once this state has been run from within another state or remote-execution module, the actual location of the cached file can be obtained using cp.is_cached:
cached = __salt__['cp.is_cached'](source_match, saltenv=__env__)
This function will return the cached path of the file, or an empty string if the file is not present in the minion cache.
salt.states.file.comment(name, regex, char='#', backup='.bak') Comment out specified lines in a file.
name   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 The file will be backed up before edit with this file extension
Set to False/None to not keep a backup.
/etc/fstab: file.comment: - regex: ^bind 127.0.0.1
salt.states.file.copy_(name, source, force=False, makedirs=False, preserve=False, user=None, group=None, mode=None, subdir=False, **kwargs) If the file defined by the source option exists on the minion, copy it to the named path. The file will not be overwritten if it already exists, unless the force option is set to True.
NOTE: This state only copies files from one location on a minion to another location on the same minion. For copying files from the master, use a file.managed state.
name   The location of the file to copy to
source The location of the file to copy 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
preserve New in version 2015.5.0.
Set preserve: True to preserve user/group ownership and mode after copying. Default is False. If preserve is set to True, then user/group/mode attributes will be ignored.
user   New in version 2015.5.0.
The user to own the copied file, this defaults to the user salt is running as on the minion. If preserve is set to True, then this will be ignored
group  New in version 2015.5.0.
The group to own the copied file, this defaults to the group salt is running as on the minion. If preserve is set to True or on Windows this will be ignored
mode   New in version 2015.5.0.
The permissions to set on the copied file, aka 644, '0775', '4664'.  If preserve is set to True, then this will be ignored.  Not supported on Windows.
The default mode for new files and directories corresponds umask of salt process. For existing files and directories it's not enforced.
subdir New in version 2015.5.0.
If the name is a directory then place the file inside the named directory
# Use 'copy', not 'copy_' /etc/example.conf: file.copy: - source: /tmp/example.conf
salt.states.file.decode(name, encoded_data=None, contents_pillar=None, encoding_type='base64', checksum='md5') Decode an encoded file and write it to disk
name   Path of the file to be written.
encoded_data The encoded file. Either this option or contents_pillar must be specified.
contents_pillar A Pillar path to the encoded file. Uses the same path syntax as pillar.get. The hashutil.base64_encodefile function can load encoded content into Pillar. Either this option or encoded_data must be specified.
encoding_type The type of encoding.
checksum The hashing algorithm to use to generate checksums. Wraps the hashutil.digest execution function.
write_base64_encoded_string_to_a_file: file.decode: - name: /tmp/new_file - encoding_type: base64 - contents_pillar: mypillar:thefile
write_base64_encoded_string_to_a_file: file.decode: - name: /tmp/new_file - encoding_type: base64 - encoded_data: | Z2V0IHNhbHRlZAo=
Be careful with multi-line strings that the YAML indentation is correct.  E.g.,
write_base64_encoded_string_to_a_file: file.decode: - name: /tmp/new_file - encoding_type: base64 - encoded_data: | {{ salt.pillar.get('path:to:data') | indent(8) }}
salt.states.file.directory(name, user=None, group=None, recurse=None, max_depth=None, dir_mode=None, file_mode=None, makedirs=False, clean=False, require=None, exclude_pat=None, follow_symlinks=False, force=False, backupname=None, allow_symlink=True, children_only=False, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, win_perms_reset=False, **kwargs) Ensure that a named directory is present and has the right perms
name   The location to create or manage a directory, as an absolute path
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. On Windows, this is ignored
recurse Enforce user/group ownership and mode of directory recursively. Accepts a list of strings representing what you would like to recurse.  If mode is defined, will recurse on both file_mode and dir_mode if they are defined. If ignore_files or ignore_dirs is included, files or directories will be left unchanged respectively. directories will be left unchanged respectively. If silent is defined, individual file/directory change notifications will be suppressed.
/var/log/httpd: file.directory: - user: root - group: root - dir_mode: 755 - file_mode: 644 - recurse: - user - group - mode
Leave files or directories unchanged:
/var/log/httpd: file.directory: - user: root - group: root - dir_mode: 755 - file_mode: 644 - recurse: - user - group - mode - ignore_dirs
max_depth Limit the recursion depth. The default is no limit=None. 'max_depth' and 'clean' are mutually exclusive.
dir_mode / mode The permissions mode to set any directories created. Not supported on Windows.
file_mode The permissions mode to set any files created if 'mode' is run in 'recurse'. This defaults to dir_mode. Not supported on Windows.
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.  'clean' and 'max_depth' are mutually exclusive.
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.
follow_symlinks If the desired path is a symlink (or recurse is defined and a symlink is encountered while recursing), follow it and check the permissions of the directory/file to which the symlink points.
Changed in version 3001.1: If set to False symlinks permissions are ignored on Linux systems because it does not support permissions modification. Symlinks permissions are always 0o777 on Linux.
force  If the name of the directory exists and is not a directory and force is set to False, the state will fail. If force is set to True, the file in the way of the directory will be deleted to make room for the directory, unless backupname is set, then it will be renamed.
backupname If the name of the directory exists and is not a directory, it will be renamed to the backupname. If the backupname already exists and force is False, the state will fail. Otherwise, the backupname will be removed first.
allow_symlink If allow_symlink is True and the specified path is a symlink, it will be allowed to remain if it points to a directory. If allow_symlink is False then the state will fail, unless force is also set to True, in which case it will be removed or renamed, depending on the value of the backupname argument.
children_only If children_only is True the base of a path is excluded when performing a recursive operation. In case of /path/to/base, base will be ignored while all of /path/to/base/* are still operated on.
win_owner The owner of the directory. If this is not passed, user will be used. If user is not passed, the account under which Salt is running will be used.
win_perms A dictionary containing permissions to grant and their propagation. For example: {'Administrators': {'perms': 'full_control', 'applies_to': 'this_folder_only'}} Can be a single basic perm or a list of advanced perms. perms must be specified. applies_to is optional and defaults to this_folder_subfolder_files.
win_deny_perms A dictionary containing permissions to deny and their propagation. For example: {'Administrators': {'perms': 'full_control', 'applies_to': 'this_folder_only'}} Can be a single basic perm or a list of advanced perms.
win_inheritance True to inherit permissions from the parent directory, False not to inherit permission.
win_perms_reset If True the existing DACL will be cleared and replaced with the settings defined in this function. If False, new entries will be appended to the existing DACL. Default is False.
Here's an example using the above win_* parameters:
create_config_dir: file.directory: - name: 'C:\config\' - win_owner: Administrators - win_perms: # Basic Permissions dev_ops: perms: full_control # List of advanced permissions appuser: perms: - read_attributes - read_ea - create_folders - read_permissions applies_to: this_folder_only joe_snuffy: perms: read applies_to: this_folder_files - win_deny_perms: fred_snuffy: perms: full_control - win_inheritance: False
salt.states.file.exists(name, **kwargs) Verify that the named file or directory is present or exists. Ensures pre-requisites outside of Salt's purview (e.g., keytabs, private keys, etc.) have been previously satisfied before deployment.
This function does not create the file if it doesn't exist, it will return an error.
name   Absolute path which must exist
salt.states.file.hardlink(name, target, force=False, makedirs=False, user=None, group=None, dir_mode=None, **kwargs) Create a hard link If the file already exists and is a hard link pointing to any location other than the specified target, the hard link will be replaced. If the hard link is a regular file or directory then the state will return False. If the regular file is desired to be replaced with a hard link pass force: True
name   The location of the hard link to create
target The location that the hard link points to
force  If the name of the hard link exists and force is set to False, the state will fail. If force is set to True, the file or directory in the way of the hard link file will be deleted to make room for the hard link, unless backupname is set, when it will be renamed
makedirs If the location of the hard link does not already have a parent directory then the state will fail, setting makedirs to True will allow Salt to create the parent directory
user   The user to own any directories made if makedirs is set to true. This defaults to the user salt is running as on the minion
group  The group ownership set on any directories made if makedirs is set to true. This defaults to the group salt is running as on the minion. On Windows, this is ignored
dir_mode If directories are to be created, passing this option specifies the permissions for those directories.
salt.states.file.keyvalue(name, key=None, value=None, key_values=None, separator='=', append_if_not_found=False, prepend_if_not_found=False, search_only=False, show_changes=True, ignore_if_missing=False, count=1, uncomment=None, key_ignore_case=False, value_ignore_case=False) Key/Value based editing of a file.
This function differs from file.replace in that it is able to search for keys, followed by a customizable separator, and replace the value with the given value. Should the value be the same as the one already in the file, no changes will be made.
Either supply both key and value parameters, or supply a dictionary with key / value pairs. It is an error to supply both.
name   Name of the file to search/replace in.
key    Key to search for when ensuring a value. Use in combination with a value parameter.
value  Value to set for a given key. Use in combination with a key parameter.
key_values Dictionary of key / value pairs to search for and ensure values for.  Used to specify multiple key / values at once.
separator Separator which separates key from value.
append_if_not_found Append the key/value to the end of the file if not found. Note that this takes precedence over prepend_if_not_found.
prepend_if_not_found Prepend the key/value to the beginning of the file if not found. Note that append_if_not_found takes precedence.
show_changes Show a diff of the resulting removals and inserts.
ignore_if_missing Return with success even if the file is not found (or not readable).
count  Number of occurrences to allow (and correct), default is 1. Set to -1 to replace all, or set to 0 to remove all lines with this key regardsless of its value.
NOTE: Any additional occurrences after count are removed.  A count of -1 will only replace all occurrences that are currently uncommented already. Lines commented out will be left alone.
uncomment Disregard and remove supplied leading characters when finding keys. When set to None, lines that are commented out are left for what they are.
NOTE: The argument to uncomment is not a prefix string. Rather; it is a set of characters, each of which are stripped.
key_ignore_case Keys are matched case insensitively. When a value is changed the matched key is kept as-is.
value_ignore_case Values are checked case insensitively, trying to set e.g. 'Yes' while the current value is 'yes', will not result in changes when value_ignore_case is set to True.
An example of using file.keyvalue to ensure sshd does not allow for root to login with a password and at the same time setting the login-gracetime to 1 minute and disabling all forwarding:
sshd_config_harden: file.keyvalue: - name: /etc/ssh/sshd_config - key_values: permitrootlogin: 'without-password' LoginGraceTime: '1m' DisableForwarding: 'yes' - separator: ' ' - uncomment: '# ' - key_ignore_case: True - append_if_not_found: True
The same example, except for only ensuring PermitRootLogin is set correctly.  Thus being able to use the shorthand key and value parameters instead of key_values.
sshd_config_harden: file.keyvalue: - name: /etc/ssh/sshd_config - key: PermitRootLogin - value: without-password - separator: ' ' - uncomment: '# ' - key_ignore_case: True - append_if_not_found: True
NOTE: Notice how the key is not matched case-sensitively, this way it will correctly identify both 'PermitRootLogin' as well as 'permitrootlogin'.
salt.states.file.line(name, content=None, match=None, mode=None, location=None, before=None, after=None, show_changes=True, backup=False, quiet=False, indent=True, create=False, user=None, group=None, file_mode=None) Line-focused editing of a file.
file.line is most useful if you have single lines in a file, potentially a config file, that you would like to manage. It can remove, add, and replace lines.
name   Filesystem path to the file to be edited.
content Content of the line. Allowed to be empty if mode=delete.
replace If line already exists, it will be replaced.
NOTE: If mode=insert is used, at least one of the following options must also be defined: location, before, or after. If location is used, it takes precedence over the other two options.
location In mode=insert only, whether to place the content at the beginning or end of a the file. If location is provided, before and after are ignored. Valid locations:
before Regular expression or an exact case-sensitive fragment of the string.  Will be tried as both a regex and a part of the line.  Must match exactly one line in the file.  This value is only used in ensure and insert modes. The content will be inserted just before this line, matching its indent unless indent=False.
after  Regular expression or an exact case-sensitive fragment of the string.  Will be tried as both a regex and a part of the line.  Must match exactly one line in the file.  This value is only used in ensure and insert modes. The content will be inserted directly after this line, unless before is also provided. If before is not matched, indentation will match this line, unless indent=False.
indent Keep indentation with the previous line. This option is not considered when the delete mode is specified. Default is True.
create Create an empty file if doesn't exist.
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 On Windows, this is ignored.
file_mode The permissions to set on this file, aka 644, 0775, 4664. Not supported on Windows.
If an equal sign (=) appears in an argument to a Salt command, it is interpreted as a keyword argument in the format of key=val. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg:
update_config: file.line: - name: /etc/myconfig.conf - mode: ensure - content: my key = my value - before: somekey.*?
And an sls file:
remove_lines: file.line: - name: /some/file.conf - mode: delete - match: away
If that state is executed 2 more times, this will be the result:
Given that original file with this state:
replace_things: file.line: - name: /some/file.conf - mode: replace - match: away - content: here
The following state:
insert_a_line: file.line: - name: /some/file.txt - mode: insert - after: insert after me - before: insert before me - content: thrice
If this state is executed 3 times, the result will be:
And given this state:
ensure_someblock: file.line: - name: /some/file.conf - mode: ensure - after: Begin SomeBlock - content: this = should be my content - before: End
salt.states.file.managed(name, source=None, source_hash='', source_hash_name=None, keep_source=True, user=None, group=None, mode=None, attrs=None, template=None, makedirs=False, dir_mode=None, context=None, replace=True, defaults=None, backup='', show_changes=True, create=True, contents=None, tmp_dir='', tmp_ext='', contents_pillar=None, contents_grains=None, contents_newline=True, contents_delimiter=':', encoding=None, encoding_errors='strict', allow_empty=True, follow_symlinks=True, check_cmd=None, skip_verify=False, selinux=None, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, win_perms_reset=False, verify_ssl=True, **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, as an absolute path.
source The source file to download to the minion, this source file can be hosted on either the salt master server (salt://), the salt minion local file system (/), or on an HTTP or FTP server (http(s)://, ftp://).
Both HTTPS and HTTP are supported as well as downloading directly from Amazon S3 compatible URLs with both pre-configured and automatic IAM credentials. (see s3.get state documentation) File retrieval from Openstack Swift object storage is supported via swift://container/object_path URLs, see swift.get documentation.  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 (use ~ in YAML), the file will be created as an empty file and the content will not be managed. This is also the case when a file already exists and the source is undefined; the contents of the file will not be changed or managed. If source is left blank or None, please also set replaced to False to make your intention explicit.
A list of sources can also be passed in to provide a default source and a set of fallbacks. The first source in the list that is found to exist will be used and subsequent entries in the list will be ignored. Source list functionality only supports local files and remote files hosted on the salt master server or retrievable via HTTP, HTTPS, or FTP.
file_override_example: file.managed: - source: - salt://file_that_does_not_exist - salt://file_that_exists
Using a Source Hash File The file can contain several checksums for several files. Each line must contain both the file name and the hash.  If no file name is matched, the first hash encountered will be used, otherwise the most secure hash with the correct source file name will be used.
When using a source hash file the source_hash argument needs to be a url, the standard download urls are supported, ftp, http, salt etc:
tomdroid-src-0.7.3.tar.gz: file.managed: - name: /tmp/tomdroid-src-0.7.3.tar.gz - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash
The following lines are all supported formats:
/etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27 sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a  /etc/resolv.conf ead48423703509d37c4a90e6a0d53e143b6fc268
Debian file type *.dsc files are also supported.
Inserting the Source Hash in the SLS Data
The source_hash can be specified as a simple checksum, like so:
tomdroid-src-0.7.3.tar.gz: file.managed: - name: /tmp/tomdroid-src-0.7.3.tar.gz - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz - source_hash: 79eef25f9b0b2c642c62b7f737d4f53f
NOTE: Releases prior to 2016.11.0 must also include the hash type, like in the below example:
tomdroid-src-0.7.3.tar.gz: file.managed: - name: /tmp/tomdroid-src-0.7.3.tar.gz - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz - source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f
Known issues: If the remote server URL has the hash file as an apparent sub-directory of the source file, the module will discover that it has already cached a directory where a file should be cached. For example:
tomdroid-src-0.7.3.tar.gz: file.managed: - name: /tmp/tomdroid-src-0.7.3.tar.gz - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5
/tmp/foo.txt: file.managed: - source: https://mydomain.tld/dir2/foo.txt - source_hash: https://mydomain.tld/hashes - source_hash_name: ./dir2/foo.txt
keep_source Set to False to discard the cached copy of the source file once the state completes. This can be useful for larger files to keep them from taking up space in minion cache. However, keep in mind that discarding the source file will result in the state needing to re-download the source file if the state is run again.
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. On Windows, this is ignored
mode   The permissions to set on this file, e.g. 644, 0775, or 4664.
The default mode for new files and directories corresponds to the umask of the salt process. The mode of existing files and directories will only be changed if mode is specified.
NOTE: This option is not supported on Windows.
Changed in version 2016.11.0: This option can be set to keep, and Salt will keep the mode from the Salt fileserver. This is only supported when the source URL begins with salt://, or for files local to the minion. Because the source option cannot be used with any of the contents options, setting the mode to keep is also incompatible with the contents options.
NOTE: keep does not work with salt-ssh.
attrs  The attributes to have on this file, e.g. a, i. The attributes can be any or a combination of the following characters: aAcCdDeijPsStTu.
template If this setting is applied, the named templating engine will be used to render the downloaded file. The following templates are supported:
makedirs If set to True, then the parent directories will be created to facilitate the creation of the named file. If False, and the parent directory of the destination file doesn't exist, the state will fail.
dir_mode If directories are to be created, passing this option specifies the permissions for those directories. If this is not set, directories will be assigned permissions by adding the execute bit to the mode of the files.
replace If set to False and the file already exists, the file will not be modified even if changes would otherwise be made. Permissions and ownership will still be enforced, however.
backup Overrides the default backup mode for this specific file. See backup_mode documentation for more details.
show_changes Output a unified diff of the old file and the new file. If False return a boolean if any changes were made.
create If set to False, then the file will only be managed if the file already exists on the system.
contents Specify the contents of the file. Cannot be used in combination with source. Ignores hashes and does not use a templating engine.
This value can be either a single string, a multiline YAML string or a list of strings.  If a list of strings, then the strings will be joined together with newlines in the resulting file. For example, the below two example states would result in identical file contents:
/path/to/file1: file.managed: - contents: - This is line 1 - This is line 2
/path/to/file2: file.managed: - contents: | This is line 1 This is line 2
contents_pillar New in version 0.17.0.
Changed in version 2016.11.0: contents_pillar can also be a list, and the pillars will be concatenated together to form one file.
Operates like contents, but draws from a value stored in pillar, using the pillar path syntax used in pillar.get. This is useful when the pillar value contains newlines, as referencing a pillar variable using a jinja/mako template can result in YAML formatting issues due to the newlines causing indentation mismatches.
For example, the following could be used to deploy an SSH private key:
/home/deployer/.ssh/id_rsa: file.managed: - user: deployer - group: deployer - mode: 600 - attrs: a - contents_pillar: userdata:deployer:id_rsa
This would populate /home/deployer/.ssh/id_rsa with the contents of pillar['userdata']['deployer']['id_rsa']. An example of this pillar setup would be like so:
userdata: deployer: id_rsa: | -----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+ GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI -----END RSA PRIVATE KEY-----
NOTE: The private key above is shortened to keep the example brief, but shows how to do multiline string in YAML. The key is followed by a pipe character, and the multiline string is indented two more spaces.
To avoid the hassle of creating an indented multiline YAML string, the file_tree external pillar can be used instead. However, this will not work for binary files in Salt releases before 2015.8.4.
contents_grains New in version 2014.7.0.
Operates like contents, but draws from a value stored in grains, using the grains path syntax used in grains.get. This functionality works similarly to contents_pillar, but with grains.
For example, the following could be used to deploy a "message of the day" file:
write_motd: file.managed: - name: /etc/motd - contents_grains: motd
This would populate /etc/motd file with the contents of the motd grain. The motd grain is not a default grain, and would need to be set prior to running the state:
salt '*' grains.set motd 'Welcome! This system is managed by Salt.'
contents_newline New in version 2014.7.0.
Changed in version 2015.8.4: This option is now ignored if the contents being deployed contain binary data.
If True, files managed using contents, contents_pillar, or contents_grains will have a newline added to the end of the file if one is not present. Setting this option to False will ensure the final line, or entry, does not contain a new line. If the last line, or entry in the file does contain a new line already, this option will not remove it.
contents_delimiter New in version 2015.8.4.
Can be used to specify an alternate delimiter for contents_pillar or contents_grains. This delimiter will be passed through to pillar.get or grains.get when retrieving the contents.
encoding_errors Error encoding scheme. Default is `'strict'`.  See https://docs.python.org/2/library/codecs.html#codec-base-classes for the list of available schemes.
allow_empty New in version 2015.8.4.
If set to False, then the state will fail if the contents specified by contents_pillar or contents_grains are empty.
follow_symlinks New in version 2014.7.0.
If the desired path is a symlink follow it and make changes to the file to which the symlink points.
The specified command will be run with an appended argument of a temporary file containing the new managed contents. If the command exits with a zero status the new managed contents will be written to the managed destination. If the command exits with a nonzero exit code, the state will fail and no changes will be made to the file.
For example, the following could be used to verify sudoers before making changes:
/etc/sudoers: file.managed: - user: root - group: root - mode: 0440 - attrs: i - source: salt://sudoers/files/sudoers.jinja - template: jinja - check_cmd: /usr/sbin/visudo -c -f
NOTE: This check_cmd functions differently than the requisite check_cmd.
tmp_dir Directory for temp file created by check_cmd. Useful for checkers dependent on config file location (e.g. daemons restricted to their own config directories by an apparmor profile).
/etc/dhcp/dhcpd.conf: file.managed: - user: root - group: root - mode: 0755 - tmp_dir: '/etc/dhcp' - contents: "# Managed by Salt" - check_cmd: dhcpd -t -cf
tmp_ext Suffix for temp file created by check_cmd. Useful for checkers dependent on config file extension (e.g. the init-checkconf upstart config checker).
/etc/init/test.conf: file.managed: - user: root - group: root - mode: 0440 - tmp_ext: '.conf' - contents: - 'description "Salt Minion"' - 'start on started mountall' - 'stop on shutdown' - 'respawn' - 'exec salt-minion' - check_cmd: init-checkconf -f
selinux Allows setting the selinux user, role, type, and range of a managed file
/tmp/selinux.test file.managed: - user: root - selinux: seuser: system_u serole: object_r setype: system_conf_t seranage: s0
win_perms A dictionary containing permissions to grant and their propagation. For example: {'Administrators': {'perms': 'full_control'}} Can be a single basic perm or a list of advanced perms. perms must be specified. applies_to does not apply to file objects.
win_deny_perms A dictionary containing permissions to deny and their propagation. For example: {'Administrators': {'perms': 'full_control'}} Can be a single basic perm or a list of advanced perms. perms must be specified. applies_to does not apply to file objects.
create_config_file: file.managed: - name: C:\config\settings.cfg - source: salt://settings.cfg - win_owner: Administrators - win_perms: # Basic Permissions dev_ops: perms: full_control # List of advanced permissions appuser: perms: - read_attributes - read_ea - create_folders - read_permissions joe_snuffy: perms: read - win_deny_perms: fred_snuffy: perms: full_control - win_inheritance: False
salt.states.file.missing(name, **kwargs) Verify that the named file or directory is missing, this returns True only if the named file is missing but does not remove the file if it is present.
name   Absolute path which must NOT exist
salt.states.file.mknod(name, ntype, major=0, minor=0, user=None, group=None, mode='0600') Create a special file similar to the 'nix mknod command. The supported device types are p (fifo pipe), c (character device), and b (block device). Provide the major and minor numbers when specifying a character device or block device. A fifo pipe does not require this information. The command will create the necessary dirs if needed. If a file of the same name not of the same type/major/minor exists, it will not be overwritten or unlinked (deleted). This is logically in place as a safety measure because you can really shoot yourself in the foot here and it is the behavior of 'nix mknod. It is also important to note that not just anyone can create special devices. Usually this is only done as root.  If the state is executed as none other than root on a minion, you may receive a permission error.
name   name of the file
ntype  node type 'p' (fifo pipe), 'c' (character device), or 'b' (block device)
major  major number of the device does not apply to a fifo pipe
minor  minor number of the device does not apply to a fifo pipe
user   owning user of the device/pipe
group  owning group of the device/pipe
mode   permissions on the device/pipe
/dev/chr: file.mknod: - ntype: c - major: 180 - minor: 31 - user: root - group: root - mode: 660
/dev/blk: file.mknod: - ntype: b - major: 8 - minor: 999 - user: root - group: root - mode: 660
/dev/fifo: file.mknod: - ntype: p - user: root - group: root - mode: 660
salt.states.file.mod_beacon(name, **kwargs) Create a beacon to monitor a file based on a beacon state argument.
NOTE: This state exists to support special handling of the beacon state argument for supported state functions. It should not be called directly.
salt.states.file.mod_run_check_cmd(cmd, filename, **check_cmd_opts) Execute the check_cmd logic.
Return a result dict if check_cmd succeeds (check_cmd == 0) otherwise return True
salt.states.file.not_cached(name, saltenv='base') New in version 2017.7.3.
Ensures that a file is not present in the minion's cache, deleting it if found. This state is primarily invoked by other states to ensure that a fresh copy is fetched.
name   The URL of the file to be removed from cache. To remove a file from cache in an environment other than base, either use the saltenv argument or include the saltenv in the URL (e.g.  salt://path/to/file.conf?saltenv=dev).
NOTE: A list of URLs is not supported, this must be a single URL. If a local file is passed here, the state will take no action.
salt.states.file.patch(name, source=None, source_hash=None, source_hash_name=None, skip_verify=False, template=None, context=None, defaults=None, options='', reject_file=None, strip=None, saltenv=None, **kwargs) Ensure that a patch has been applied to the specified file or directory
Changed in version 2019.2.0: The hash and dry_run_first options are now ignored, as the logic which determines whether or not the patch has already been applied no longer requires them. Additionally, this state now supports patch files that modify more than one file. To use these sort of patches, specify a directory (and, if necessary, the strip option) instead of a file.
NOTE: A suitable patch executable must be available on the minion. Also, keep in mind that the pre-check this state does to determine whether or not changes need to be made will create a temp file and send all patch output to that file. This means that, in the event that the patch would not have applied cleanly, the comment included in the state results will reference a temp file that will no longer exist once the state finishes running.
name   The file or directory to which the patch should be applied
source The patch file to apply
Changed in version 2019.2.0: The source can now be from any file source supported by Salt (salt://, http://, https://, ftp://, etc.).  Templating is also now supported.
source_hash Works the same way as in file.managed.
source_hash_name Works the same way as in file.managed
skip_verify Works the same way as in file.managed
template Works the same way as in file.managed
context Works the same way as in file.managed
defaults Works the same way as in file.managed
options Extra options to pass to patch. This should not be necessary in most cases.
NOTE: For best results, short opts should be separate from one another.  The -N and -r, and -o options are used internally by this state and cannot be used here. Additionally, instead of using -pN or --strip=N, use the strip option documented below.
reject_file If specified, any rejected hunks will be written to this file. If not specified, then they will be written to a temp file which will be deleted when the state finishes running.
IMPORTANT: The parent directory must exist. Also, this will overwrite the file if it is already present.
strip  Number of directories to strip from paths in the patch file. For example, using the below SLS would instruct Salt to use -p1 when applying the patch:
/etc/myfile.conf: file.patch: - source: salt://myfile.patch - strip: 1
New in version 2019.2.0: In previous versions, -p1 would need to be passed as part of the options value.
saltenv Specify the environment from which to retrieve the patch file indicated by the source parameter. If not provided, this defaults to the environment from which the state is being executed.
NOTE: Ignored when the patch file is from a non-salt:// source.
# Equivalent to ``patch --forward /opt/myfile.txt myfile.patch`` /opt/myfile.txt: file.patch: - source: salt://myfile.patch
salt.states.file.prepend(name, text=None, makedirs=False, source=None, source_hash=None, template='jinja', sources=None, source_hashes=None, defaults=None, context=None, header=None) Ensure that some text appears at the beginning of a file
The text will not be prepended again if it already exists in the file. You may specify a single line of text or a list of lines to append.
/etc/motd: file.prepend: - text: | Thou hadst better eat salt with the Philosophers of Greece, than sugar with the Courtiers of Italy. - Benjamin Franklin
/etc/motd: file.prepend: - 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."
Optionally, require the text to appear exactly as specified (order and position). Combine with multi-line or multiple lines of input.
/etc/motd: file.prepend: - header: True - text: - This will be the very first line in the file. - The 2nd line, regardless of duplicates elsewhere in the file. - These will be written anew if they do not appear verbatim.
/etc/motd: file: - prepend - template: jinja - sources: - salt://motd/devops-messages.tmpl - salt://motd/hr-messages.tmpl - salt://motd/general-messages.tmpl
salt.states.file.recurse(name, source, keep_source=True, clean=False, require=None, user=None, group=None, dir_mode=None, file_mode=None, sym_mode=None, template=None, context=None, replace=True, defaults=None, include_empty=False, backup='', include_pat=None, exclude_pat=None, maxdepth=None, keep_symlinks=False, force_symlinks=False, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, **kwargs) Recurse through a subdirectory on the master and copy said subdirectory 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.
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. On Windows, this is ignored
dir_mode The permissions mode to set on any directories created.
file_mode The permissions mode to set on any files created.
sym_mode The permissions mode to set on any symlink created.
NOTE: The template option is required when recursively applying templates.
include_empty Set this to True if empty directories should also be created (default is False)
backup Overrides the default backup mode for all replaced files. See backup_mode documentation for more details.
include_pat When copying, include only this pattern, or list of patterns, 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' ...
Changed in version 3001: List patterns are now supported
- include_pat: - hello01 - hello02
exclude_pat Exclude this pattern, or list of patterns, from the source when copying.  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 within that result apply exclude_pat.
Also, when 'clean=True', exclude this pattern from the removal list and preserve in the destination.  Example:
- exclude_pat: APPDATA*               :: glob matches APPDATA.01, APPDATA.02,.. for exclusion - exclude_pat: E@(APPDATA)|(TEMPDATA) :: regexp matches APPDATA or TEMPDATA for exclusion
- exclude_pat: - APPDATA.01 - APPDATA.02
maxdepth When copying, only copy paths which are of depth maxdepth from the source path.  Example:
- maxdepth: 0      :: Only include files located in the source directory - maxdepth: 1      :: Only include files located in the source or immediate subdirectories