neulab/tldr huggingface dataset:
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.
salt '*' file.comment /etc/modules pcspkr
salt.modules.file.comment_line(path, regex, char='#', cmnt=True, backup='.bak') Comment or Uncomment a line in a text file.
• path -- string The full path to the text file.
• regex -- string A regex expression that begins with ^ that will find the line you wish to comment. Can be as simple as ^color =
• char -- string The character used to comment a line in the type of file you're referencing.  Default is #
• cmnt -- boolean True to comment the line. False to uncomment the line. Default is True.
• backup -- string The file extension to give the backup file. Default is .bak Set to False/None to not keep a backup.
Returns boolean Returns True if successful, False if not
The following example will comment out the pcspkr line in the /etc/modules file using the default # character and create a backup file named modules.bak
salt '*' file.comment_line '/etc/modules' '^pcspkr'
The following example will uncomment the log_level setting in minion config file if it is set to either warning, info, or debug using the # character and create a backup file named minion.bk
salt '*' file.comment_line 'C:\salt\conf\minion' '^log_level: (warning|info|debug)' '#' False '.bk'
salt.modules.file.contains(path, text) Deprecated since version 0.17.0: Use search() instead.
Return True if the file at path contains text
salt '*' file.contains /etc/crontab 'mymaintenance.sh'
salt.modules.file.contains_glob(path, glob_expr) Deprecated since version 0.17.0: Use search() instead.
Return True if the given glob matches a string in the named file
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
salt '*' file.contains_regex /etc/crontab
salt.modules.file.copy(src, dst, recurse=False, remove_existing=False) Copy a file or directory from source to dst
In order to copy a directory, the recurse flag is required, and will by default overwrite files in the destination with the same path, and retain all other existing files. (similar to cp -r on unix)
remove_existing will remove all files in the target directory, and then copy files from the source.
NOTE: The copy function accepts paths that are local to the Salt minion.  This function does not support salt://, http://, or the other additional file paths that are supported by states.file.managed and states.file.recurse.
salt '*' file.copy /path/to/src /path/to/dst salt '*' file.copy /path/to/src_dir /path/to/dst_dir recurse=True salt '*' file.copy /path/to/src_dir /path/to/dst_dir recurse=True remove_existing=True
salt.modules.file.delete_backup(path, backup_id) New in version 0.17.0.
Delete a previous version of a file that was backed up using Salt's file state backup system.
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
salt '*' file.delete_backup /var/cache/salt/minion/file_backup/home/foo/bar/baz.txt 0
salt.modules.file.directory_exists(path) Tests to see if path is a valid directory.  Returns True/False.
salt '*' file.directory_exists /etc
salt.modules.file.dirname(path) Returns the directory component of a pathname
{%- from salt['file.dirname'](tpldir) + '/vars.jinja' import parent_vars %}
salt '*' file.dirname 'test/path/filename.config'
salt.modules.file.diskusage(path) Recursively calculate disk usage of path and return it in bytes
salt '*' file.diskusage /path/to/check
salt.modules.file.extract_hash(hash_fn, hash_type='sha256', file_name='', source='', source_hash_name=None) Changed in version 2016.3.5: Prior to this version, only the file_name argument was considered for filename matches in the hash file. This would be problematic for cases in which the user was relying on a remote checksum file that they do not control, and they wished to use a different name for that file on the minion from the filename on the remote server (and in the checksum file). For example, managing /tmp/myfile.tar.gz when the remote file was at https://mydomain.tld/different_name.tar.gz. The file.managed state now also passes this function the source URI as well as the source_hash_name (if specified). In cases where source_hash_name is specified, it takes precedence over both the file_name and source. When it is not specified, file_name takes precedence over source. This allows for better capability for matching hashes.
Changed in version 2016.11.0: File name and source URI matches are no longer disregarded when source_hash_name is specified. They will be used as fallback matches if there is no match to the source_hash_name value.
This routine is called from the file.managed state to pull a hash from a remote file.  Regular expressions are used line by line on the source_hash file, to find a potential candidate of the indicated hash type. This avoids many problems of arbitrary file layout rules. It specifically permits pulling hash codes from debian *.dsc files.
If no exact match of a hash and filename are found, then the first hash found (if any) will be returned. If no hashes at all are found, then None will be returned.
openerp_7.0-latest-1.tar.gz: file.managed: - name: /tmp/openerp_7.0-20121227-075624-1_all.deb - source: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0-20121227-075624-1.tar.gz - source_hash: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0-20121227-075624-1.dsc
salt '*' file.extract_hash /path/to/hash/file sha512 /etc/foo
salt.modules.file.file_exists(path) Tests to see if path is a valid file.  Returns True/False.
salt '*' file.file_exists /etc/passwd
salt.modules.file.find(path, *args, **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]
and/or depth criteria:
maxdepth = maximum depth to transverse in path mindepth = minimum depth to transverse before checking files or directories
The default action is print=path
path-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 Regex (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
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
salt '*' file.get_devmm /dev/chr
salt.modules.file.get_diff(file1, file2, saltenv='base', show_filenames=True, show_changes=True, template=False, source_hash_file1=None, source_hash_file2=None) Return unified diff of two files
file1  The first file to feed into the diff utility
Changed in version 2018.3.0: Can now be either a local or remote file. In earlier releases, thuis had to be a file local to the minion.
file2  The second file to feed into the diff utility
Changed in version 2018.3.0: Can now be either a local or remote file. In earlier releases, this had to be a file on the salt fileserver (i.e.  salt://somefile.txt)
show_filenames: True Set to False to hide the filenames in the top two lines of the diff.
show_changes: True If set to False, and there are differences, then instead of a diff a simple message stating that show_changes is set to False will be returned.
template: False Set to True if two templates are being compared. This is not useful except for within states, with the obfuscate_templates option set to True.
source_hash_file1 If file1 is an http(s)/ftp URL and the file exists in the minion's file cache, this option can be passed to keep the minion from re-downloading the archive if the cached copy matches the specified hash.
source_hash_file2 If file2 is an http(s)/ftp URL and the file exists in the minion's file cache, this option can be passed to keep the minion from re-downloading the archive if the cached copy matches the specified hash.
salt '*' file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc salt '*' file.get_diff /tmp/foo.txt /tmp/bar.txt
salt.modules.file.get_gid(path, follow_symlinks=True) Return the id of the group that owns a given file
path   file or directory of which to get the gid
follow_symlinks indicated if symlinks should be followed
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
path   file or directory of which to get the group
salt '*' file.get_group /etc/passwd
salt.modules.file.get_hash(path, form='sha256', chunk_size=65536) 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'
form   desired sum format
chunk_size amount to sum at once
salt '*' file.get_hash /etc/shadow
salt.modules.file.get_managed(name, template, source, source_hash, source_hash_name, user, group, mode, attrs, saltenv, context, defaults, skip_verify=False, verify_ssl=True, **kwargs) Return the managed file data for file.managed
name   location where the file lives on the server
source managed source file
source_hash hash of the source file
source_hash_name When source_hash refers to a remote file, this specifies the filename to look for in that file.
user   Owner of file
group  Group owner of file
mode   Permissions of file
attrs  Attributes of file
context Variables to add to the template context
defaults Default values of for context_dict
skip_verify If True, hash verification of remote file sources (http://, https://, ftp://) will be skipped, and the source_hash argument will be ignored.
salt '*' file.get_managed /etc/httpd/conf.d/httpd.conf jinja salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' None root root '755' base None None
salt.modules.file.get_mode(path, follow_symlinks=True) Return the mode of a file
path   file or directory of which to get the mode
salt '*' file.get_mode /etc/passwd
Changed in version 2014.1.0: follow_symlinks option added
salt.modules.file.get_selinux_context(path) Get an SELinux context from a given path
salt '*' file.get_selinux_context /etc/hosts
salt.modules.file.get_source_sum(file_name='', source='', source_hash=None, source_hash_name=None, saltenv='base', verify_ssl=True) New in version 2016.11.0.
Used by file.get_managed to obtain the hash and hash type from the parameters specified below.
file_name Optional file name being managed, for matching with file.extract_hash.
source Source file, as used in file and other states. If source_hash refers to a file containing hashes, then this filename will be used to match a filename in that file. If the source_hash is a hash expression, then this argument will be ignored.
source_hash Hash file/expression, as used in file and other states. If this value refers to a remote URL or absolute path to a local file, it will be cached and file.extract_hash will be used to obtain a hash from it.
source_hash_name Specific file name to look for when source_hash refers to a remote file, used to disambiguate ambiguous matches.
saltenv: base Salt fileserver environment from which to retrieve the source_hash. This value will only be used when source_hash refers to a file on the Salt fileserver (i.e. one beginning with salt://).
salt '*' file.get_source_sum /tmp/foo.tar.gz source=http://mydomain.tld/foo.tar.gz source_hash=499ae16dcae71eeb7c3a30c75ea7a1a6 salt '*' file.get_source_sum /tmp/foo.tar.gz source=http://mydomain.tld/foo.tar.gz source_hash=https://mydomain.tld/hashes.md5 salt '*' file.get_source_sum /tmp/foo.tar.gz source=http://mydomain.tld/foo.tar.gz source_hash=https://mydomain.tld/hashes.md5 source_hash_name=./dir2/foo.tar.gz
salt.modules.file.get_sum(path, form='sha256') Return the checksum for the given file. The following checksum algorithms are supported:
• sha1
• sha224
• sha256 (default)
• sha384
• sha512
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
path   file or directory of which to get the uid
salt '*' file.get_uid /etc/passwd
salt.modules.file.get_user(path, follow_symlinks=True) Return the user that owns a given file
path   file or directory of which to get the user
salt '*' file.get_user /etc/passwd
salt.modules.file.gid_to_group(gid) Convert the group id to the group name on this system
gid    gid to convert to a group name
salt '*' file.gid_to_group 0
salt.modules.file.grep(path, pattern, *opts) Grep for a string in the specified file
NOTE: This function's return value is slated for refinement in future versions of Salt
path   Path to the file to be searched
NOTE: Globbing is supported (i.e. /var/log/foo/*.log, but if globbing is being used then the path should be quoted to keep the shell from attempting to expand the glob expression.
pattern Pattern to match. For example: test, or a[0-5]
opts   Additional command-line flags to pass to the grep command. For example: -v, or -i -B2
NOTE: The options should come after a double-dash (as shown in the examples below) to keep Salt's own argument parser from interpreting them.
salt '*' file.grep /etc/passwd nobody salt '*' file.grep /etc/sysconfig/network-scripts/ifcfg-eth0 ipaddr -- -i salt '*' file.grep /etc/sysconfig/network-scripts/ifcfg-eth0 ipaddr -- -i -B2 salt '*' file.grep "/etc/sysconfig/network-scripts/*" ipaddr -- -i -l
salt.modules.file.group_to_gid(group) Convert the group to the gid on this system
group  group to convert to its gid
salt '*' file.group_to_gid root
salt.modules.file.is_blkdev(name) Check if a file exists and is a block device.
salt '*' file.is_blkdev /dev/blk
salt.modules.file.is_chrdev(name) Check if a file exists and is a character device.
salt '*' file.is_chrdev /dev/chr
salt.modules.file.is_fifo(name) Check if a file exists and is a FIFO.
salt '*' file.is_fifo /dev/fifo
salt.modules.file.is_hardlink(path) Check if the path is a hard link by verifying that the number of links is larger than 1
salt '*' file.is_hardlink /path/to/link
salt.modules.file.is_link(path) Check if the path is a symbolic link
salt '*' file.is_link /path/to/link
salt.modules.file.join(*args) Return a normalized file system path for the underlying OS
This can be useful at the CLI but is frequently useful when scripting combining path variables:
{% set www_root = '/var' %} {% set app_dir = 'myapp' %}
myapp_config: file: - managed - name: {{ salt['file.join'](www_root, app_dir, 'config.yaml') }}
salt '*' file.join '/' 'usr' 'local' 'bin'
salt.modules.file.lchown(path, user, group) Chown a file, pass the file the desired user and group without following symlinks.
salt.modules.file.line(path, content=None, match=None, mode=None, location=None, before=None, after=None, show_changes=True, backup=False, quiet=False, indent=True) New in version 2015.8.0.
Line-focused editing of a file.
NOTE: file.line exists for historic reasons, and is not generally recommended. It has a lot of quirks.  You may find file.replace to be more suitable.
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 a single line at a time.
path   Filesystem path to the file to be edited.
content Content of the line. Allowed to be empty if mode='delete'.
match  Match the target line for an action by a fragment of a string or regular expression.
If neither before nor after are provided, and match is also None, match falls back to the content value.
mode   Defines how to edit a line. One of the following options is required:
ensure If line does not exist, it will be added. If before and after are specified either zero lines, or lines that contain the content line are allowed to be in between before and after. If there are lines, and none of them match then it will produce an error.
replace If line already exists, the entire line will be replaced.
delete Delete the line, if found.
insert Nearly identical to ensure. If a line does not exist, it will be added.
The differences are that multiple (and non-matching) lines are alloweed between before and after, if they are specified. The line will always be inserted right before before. insert also allows the use of location to specify that the line should be added at the beginning or end of the file.
NOTE: If mode='insert' is used, at least one of location, before, or after is required.  If location is used, before and after are ignored.
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:
start  Place the content at the beginning of the file.
end    Place the content at the end of the file.
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, with matching indentation 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 provided, indentation will match this line, unless indent=False.
show_changes Output a unified diff of the old file and the new file.  If False return a boolean if any changes were made.  Default is True
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.
backup Create a backup of the original file with the extension: "Year-Month-Day-Hour-Minutes-Seconds".
quiet  Do not raise any exceptions. E.g. ignore the fact that the file that is tried to be edited does not exist and nothing really happened.
indent Keep indentation with the previous line. This option is not considered when the delete mode is specified. Default is True
salt '*' file.line /etc/nsswitch.conf "networks:        files dns" after="hosts:.*?" mode='ensure'
NOTE: 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:
salt '*' file.line /path/to/file content="CREATEMAIL_SPOOL=no" match="CREATE_MAIL_SPOOL=yes" mode="replace"
Here's a simple config file.
[some_config] # Some config file # this line will go away
here=False away=True goodybe=away
salt \* file.line /some/file.conf mode=delete match=away
This will produce:
[some_config] # Some config file
here=False away=True goodbye=away
If that command is executed 2 more times, this will be the result:
here=False
If we reset the file to its original state and run
salt \* file.line /some/file.conf mode=replace match=away content=here
Three passes will this state will result in this file:
[some_config] # Some config file here
here=False here here
Each pass replacing the first line found.
Given this file:
insert after me something insert before me
The following command
salt \* file.line /some/file.txt mode=insert after="insert after me" before="insert before me" content=thrice
If that command is executed 3 times, the result will be:
insert after me something thrice thrice thrice insert before me
If the mode is ensure instead, it will fail each time. To succeed, we need to remove the incorrect line between before and after:
insert after me insert before me
With an ensure mode, this will insert thrice the first time and make no changes for subsequent calls. For something simple this is fine, but if you have instead blocks like this:
Begin SomeBlock foo = bar End
Begin AnotherBlock another = value End
And you try to use ensure this way:
salt \* file.line  /tmp/fun.txt mode="ensure" content="this = should be my content" after="Begin SomeBlock" before="End"
This will fail because there are multiple End lines. Without that problem, it still would fail because there is a non-matching line, foo = bar. Ensure only allows either zero, or the matching line present to be present in between before and after.
salt.modules.file.link(src, path) New in version 2014.1.0.
Create a hard link to a file
salt '*' file.link /path/to/file /path/to/link
salt.modules.file.list_backup(path, limit=None) This function is an alias of list_backups. New in version 0.17.0.
Lists the previous versions of a file backed up using Salt's file state backup system.
limit  Limit the number of results to the most recent N backups
salt '*' file.list_backups /foo/bar/baz.txt
salt.modules.file.list_backups(path, limit=None) New in version 0.17.0.
salt.modules.file.list_backups_dir(path, limit=None) Lists the previous versions of a directory backed up using Salt's file state backup system.
path   The directory on the minion to check for backups
salt '*' file.list_backups_dir /foo/bar/baz/
salt.modules.file.lsattr(path) New in version 2018.3.0.
Changed in version 2018.3.1: If lsattr is not installed on the system, None is returned.
Changed in version 2018.3.4: If on AIX, None is returned even if in filesystem as lsattr on AIX is not the same thing as the linux version.
Obtain the modifiable attributes of the given file. If path is to a directory, an empty list is returned.
path   path to file to obtain attributes of. File/directory must exist.
salt '*' file.lsattr foo1.txt
salt.modules.file.lstat(path) New in version 2014.1.0.
Returns the lstat attributes for the given file or dir. Does not support symbolic links.
salt '*' file.lstat /path/to/file
salt.modules.file.makedirs_(path, user=None, group=None, mode=None) Ensure that the directory containing this path is available.
NOTE: The path must end with a trailing slash otherwise the directory/directories will be created up to the parent directory. For example if path is /opt/code, then it would be treated as /opt/ but if the path ends with a trailing slash like /opt/code/, then it would be treated as /opt/code/.
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.
salt '*' file.makedirs_perms /opt/code
salt.modules.file.manage_file(name, sfn, ret, source, source_sum, user, group, mode, attrs, saltenv, backup, makedirs=False, template=None, show_changes=True, contents=None, dir_mode=None, follow_symlinks=True, skip_verify=False, keep_mode=False, encoding=None, encoding_errors='strict', seuser=None, serole=None, setype=None, serange=None, verify_ssl=True, **kwargs) Checks the destination against what was retrieved with get_managed and makes the appropriate modifications (if necessary).
name   location to place the file
sfn    location of cached file on the minion
This is the path to the file stored on the minion. This file is placed on the minion using cp.cache_file.  If the hash sum of that file matches the source_sum, we do not transfer the file to the minion again.
This file is then grabbed and if it has template set, it renders the file to be placed into the correct place on the system using salt.files.utils.copyfile()
ret    The initial state return data structure. Pass in None to use the default structure.
source file reference on the master
source_sum sum hash for source
backup backup_mode
attrs  attributes to be set on file: '' means remove all of them
makedirs make directories if they do not exist
template format of templating
show_changes Include diff in state return
contents: contents to be placed in the file
dir_mode mode for directories created with makedirs
skip_verify: False If True, hash verification of remote file sources (http://, https://, ftp://) will be skipped, and the source_hash argument will be ignored.
keep_mode: False If True, and the source is a file from the Salt fileserver (or a local file on the minion), the mode of the destination file will be set to the mode of the source file.
NOTE: keep_mode does not work with salt-ssh.
As a consequence of how the files are transferred to the minion, and the inability to connect back to the master with salt-ssh, salt is unable to stat the file as it exists on the fileserver and thus cannot mirror the mode on the salt-ssh minion
encoding If specified, then the specified encoding will be used. Otherwise, the file will be encoded using the system locale (usually UTF-8). See https://docs.python.org/3/library/codecs.html#standard-encodings for the list of available encodings.
encoding_errors: 'strict' Default is `'strict'`.  See https://docs.python.org/2/library/codecs.html#codec-base-classes for the error handling schemes.
salt '*' file.manage_file /etc/httpd/conf.d/httpd.conf '' '{}' salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' '' base ''
Changed in version 2014.7.0: follow_symlinks option added
salt.modules.file.mkdir(dir_path, user=None, group=None, mode=None) Ensure that a directory is available.
salt '*' file.mkdir /opt/jetty/context
salt.modules.file.mknod(name, ntype, major=0, minor=0, user=None, group=None, mode='0600') New in version 0.17.0.
Create a block device, character device, or fifo pipe.  Identical to the gnu mknod.
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') New in version 0.17.0.
Create a block device.
salt '*' file.mknod_blkdev /dev/blk 8 999
salt.modules.file.mknod_chrdev(name, major, minor, user=None, group=None, mode='0660') New in version 0.17.0.
Create a character device.
salt '*' file.mknod_chrdev /dev/chr 180 31
salt.modules.file.mknod_fifo(name, user=None, group=None, mode='0660') New in version 0.17.0.
Create a FIFO pipe.
salt '*' file.mknod_fifo /dev/fifo
salt.modules.file.move(src, dst) Move a file or directory
salt '*' file.move /path/to/src /path/to/dst
salt.modules.file.normpath(path) Returns Normalize path, eliminating double slashes, etc.
{%- from salt['file.normpath'](tpldir + '/../vars.jinja') import parent_vars %}
salt '*' file.normpath 'a/b/c/..'
salt.modules.file.open_files(by_pid=False) Return a list of all physical open files on the system.
salt '*' file.open_files salt '*' file.open_files by_pid=True
salt.modules.file.pardir() Return the relative parent directory path symbol for underlying OS
This can be useful when constructing Salt Formulas.
{% set pardir = salt['file.pardir']() %} {% set final_path = salt['file.join']('subdir', pardir, 'confdir') %}
salt '*' file.pardir
salt.modules.file.patch(originalfile, patchfile, options='', dry_run=False) New in version 0.10.4.
Apply a patch to a file or directory.
Equivalent to:
patch <options> -i <patchfile> <originalfile>
Or, when a directory is patched:
patch <options> -i <patchfile> -d <originalfile> -p0
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.
NOTE: Windows now supports using patch as of 3004.
In order to use this function in Windows, please install the patch binary through your own means and ensure it's found in the system Path. If installing through git-for-windows, please select the optional "Use Git and optional Unix tools from the Command Prompt" option when installing Git.
salt '*' file.patch /opt/file.txt /tmp/file.txt.patch
salt '*' file.patch C:\file1.txt C:\file3.patch
salt.modules.file.path_exists_glob(path) Tests to see if path after expansion is a valid path (file or directory).  Expansion allows usage of ? * and character ranges []. Tilde expansion is not supported. Returns True/False.
salt '*' file.path_exists_glob /etc/pam*/pass*
salt.modules.file.prepend(path, *args, **kwargs) New in version 2014.7.0.
Prepend text to the beginning of a file
*args  strings to prepend to the file
salt '*' file.prepend /etc/motd \ "With all thine offerings thou shalt offer salt." \ "Salt is what makes things taste bad when it isn't in them."
salt '*' file.prepend /etc/motd args='cheese=spam'
salt '*' file.prepend /etc/motd args="['cheese=spam','spam=cheese']"
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)
sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"
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.
salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'
salt.modules.file.read(path, binary=False) New in version 2017.7.0.
Return the content of the file.
Parameters binary (bool) -- Whether to read and return binary data
salt '*' file.read /path/to/file
salt.modules.file.readdir(path) New in version 2014.1.0.
Return a list containing the contents of a directory
salt '*' file.readdir /path/to/dir/
salt.modules.file.readlink(path, canonicalize=False) New in version 2014.1.0.
Return the path that a symlink points to If canonicalize is set to True, then it return the final target
salt '*' file.readlink /path/to/link
salt.modules.file.remove(path) Remove the named file. If a directory is supplied, it will be recursively deleted.
salt '*' file.remove /tmp/foo
Changed in version 3000: The method now works on all types of file system entries, not just files, directories and symlinks.
salt.modules.file.remove_backup(path, backup_id) This function is an alias of delete_backup. New in version 0.17.0.
salt.modules.file.rename(src, dst) Rename a file or directory
salt '*' file.rename /path/to/src /path/to/dst
salt.modules.file.replace(path, pattern, repl, count=0, flags=8, bufsize=1, append_if_not_found=False, prepend_if_not_found=False, not_found_content=None, backup='.bak', dry_run=False, search_only=False, show_changes=True, ignore_if_missing=False, preserve_inode=True, backslash_literal=False) New in version 0.17.0.
Replace occurrences of a pattern in a file. If show_changes is True, then a diff of what changed will be returned, otherwise a True will be returned when changes are made, and False when no changes are made.
This is a pure Python implementation that wraps Python's sub().
path   Filesystem path to the file to be edited. If a symlink is specified, it will be resolved to its target.
pattern A regular expression, to be matched using Python's search().
repl   The replacement text
count: 0 Maximum number of pattern occurrences to be replaced. If count is a positive integer n, only n occurrences will be replaced, otherwise all occurrences will be replaced.
flags (list or int) A list of flags defined in the re module documentation from the Python standard library. Each list item should be a string that will correlate to the human-friendly flag name. E.g., ['IGNORECASE', 'MULTILINE']. Optionally, flags may be an int, with a value corresponding to the XOR (|) of all the desired flags. Defaults to 8 (which supports 'MULTILINE').
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.
append_if_not_found: False New in version 2014.7.0.
If set to True, and pattern is not found, then the content will be appended to the file.
prepend_if_not_found: False New in version 2014.7.0.
If set to True and pattern is not found, then the content will be prepended to the file.
not_found_content New in version 2014.7.0.
Content to use for append/prepend if not found. If None (default), uses repl. Useful when repl uses references to group in pattern.
backup: .bak The file extension to use for a backup of the file before editing. Set to False to skip making a backup.
dry_run: False If set to True, no changes will be made to the file, the function will just return the changes that would have been made (or a True/False value if show_changes is set to False).
search_only: False If set to true, this no changes will be performed on the file, and this function will simply return True if the pattern was matched, and False if not.
show_changes: True If True, return a diff of changes made. Otherwise, return True if changes were made, and False if not.
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. This may not normally be a concern, but could impact performance if used with large files.
ignore_if_missing: False New in version 2015.8.0.
If set to True, this function will simply return False if the file doesn't exist. Otherwise, an error will be thrown.
preserve_inode: True New in version 2015.8.0.
Preserve the inode of the file, so that any hard links continue to share the inode with the original filename. This works by copying the file, reading from the copy, and writing to the file at the original inode. If False, the file will be moved rather than copied, and a new file will be written to a new inode, but using the original filename. Hard links will then share an inode with the backup, instead (if using backup to create a backup copy).
backslash_literal: False New in version 2016.11.7.
Interpret backslashes as literal backslashes for the repl and not escape characters.  This will help when using append/prepend so that the backslashes are not interpreted for the repl on the second run of the state.
salt '*' file.replace /path/to/file pattern='=' repl=':' salt '*' file.replace /path/to/file pattern="bind-address\s*=" repl='bind-address:'
salt '*' file.replace /etc/httpd/httpd.conf pattern='LogLevel warn' repl='LogLevel info' salt '*' file.replace /some/file pattern='before' repl='after' flags='[MULTILINE, IGNORECASE]'
salt.modules.file.restore_backup(path, backup_id) New in version 0.17.0.
Restore a previous version of a file that was backed up using Salt's file state backup system.
backup_id The numeric id for the backup you wish to restore, as found using file.list_backups
salt '*' file.restore_backup /foo/bar/baz.txt 0
salt.modules.file.restorecon(path, recursive=False) Reset the SELinux context on a given path
salt '*' file.restorecon /home/user/.ssh/authorized_keys
salt.modules.file.rmdir(path) New in version 2014.1.0.
Remove the specified directory. Fails if a directory is not empty.
salt '*' file.rmdir /tmp/foo/
salt.modules.file.search(path, pattern, flags=8, bufsize=1, ignore_if_missing=False, multiline=False) New in version 0.17.0.
Search for occurrences of a pattern in a file
Except for multiline, params are identical to replace().
multiline If true, inserts 'MULTILINE' into flags and sets bufsize to 'file'.
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
options: -r -e Options to pass to sed
flags: g Flags to modify the sed search; e.g., i for case-insensitive pattern matching
negate_match: False Negate the search command (!)
New in version 0.17.0.
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.
salt.modules.file.seek_read(path, size, offset) New in version 2014.1.0.
Seek to a position on a file and read it
seek   amount to read at once
offset offset to start into the file
salt '*' file.seek_read /path/to/file 4096 0
salt.modules.file.seek_write(path, data, offset) New in version 2014.1.0.
Seek to a position on a file and write to it
data   data to write to file
offset position in file to start writing
salt '*' file.seek_write /path/to/file 'some data' 4096
salt.modules.file.set_mode(path, mode) Set the mode of a file
path   file or directory of which to set the mode
mode   mode to set the path to
salt '*' file.set_mode /etc/passwd 0644
salt.modules.file.set_selinux_context(path, user=None, role=None, type=None, range=None, persist=False) Changed in version 3001: Added persist option
Set a specific SELinux label on a given path
salt '*' file.set_selinux_context path <user> <role> <type> <range> salt '*' file.set_selinux_context /etc/yum.repos.d/epel.repo system_u object_r system_conf_t s0
salt.modules.file.source_list(source, source_hash, saltenv) Check the source list and return the source to use
salt '*' file.source_list salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' base
salt.modules.file.stats(path, hash_type=None, follow_symlinks=True) Return a dict containing the stats for a given file
salt '*' file.stats /etc/passwd
salt.modules.file.statvfs(path) New in version 2014.1.0.
Perform a statvfs call against the filesystem that the file resides on
salt '*' file.statvfs /path/to/file
salt.modules.file.symlink(src, path) Create a symbolic link (symlink, soft link) to a file
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
salt '*' file.touch /var/log/emptyfile
salt.modules.file.truncate(path, length) New in version 2014.1.0.
Seek to a position on a file and delete everything after that point
length offset into file to truncate
salt '*' file.truncate /path/to/file 512
salt.modules.file.uid_to_user(uid) Convert a uid to a user name
uid    uid to convert to a username
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
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
salt '*' file.uncomment /etc/hosts.deny 'ALL: PARANOID'
salt.modules.file.user_to_uid(user) Convert user name to a uid
user   user name to convert to its uid
salt '*' file.user_to_uid root
salt.modules.file.write(path, *args, **kwargs) New in version 2014.7.0.
Write text to a file, overwriting any existing contents.
*args  strings to write to the file
salt '*' file.write /etc/motd \ "With all thine offerings thou shalt offer salt."
salt '*' file.write /etc/motd args='cheese=spam'
salt '*' file.write /etc/motd args="['cheese=spam','spam=cheese']"
salt.modules.firewalld Support for firewalld.
New in version 2015.2.0.
salt.modules.firewalld.add_interface(zone, interface, permanent=True) Bind an interface to a zone
salt '*' firewalld.add_interface zone eth0
salt.modules.firewalld.add_masquerade(zone=None, permanent=True) Enable masquerade on a zone.  If zone is omitted, default zone will be used.
salt '*' firewalld.add_masquerade
To enable masquerade on a specific zone
salt '*' firewalld.add_masquerade dmz
salt.modules.firewalld.add_port(zone, port, permanent=True, force_masquerade=False) Allow specific ports in a zone.
salt '*' firewalld.add_port internal 443/tcp
force_masquerade when a zone is created ensure masquerade is also enabled on that zone.
salt.modules.firewalld.add_port_fwd(zone, src, dest, proto='tcp', dstaddr='', permanent=True, force_masquerade=False) Add port forwarding.
salt '*' firewalld.add_port_fwd public 80 443 tcp
salt.modules.firewalld.add_rich_rule(zone, rule, permanent=True) Add a rich rule to a zone
salt '*' firewalld.add_rich_rule zone 'rule'
salt.modules.firewalld.add_service(service, zone=None, permanent=True) Add a service for zone. If zone is omitted, default zone will be used.
salt '*' firewalld.add_service ssh
To assign a service to a specific zone:
salt '*' firewalld.add_service ssh my_zone
salt.modules.firewalld.add_service_port(service, port) Add a new port to the specified service.
salt '*' firewalld.add_service_port zone 80
salt.modules.firewalld.add_service_protocol(service, protocol) Add a new protocol to the specified service.
salt '*' firewalld.add_service_protocol zone ssh
salt.modules.firewalld.add_source(zone, source, permanent=True) Bind a source to a zone
salt '*' firewalld.add_source zone 192.168.1.0/24
salt.modules.firewalld.allow_icmp(zone, icmp, permanent=True) Allow a specific ICMP type on a zone
salt '*' firewalld.allow_icmp zone echo-reply
salt.modules.firewalld.block_icmp(zone, icmp, permanent=True) Block a specific ICMP type on a zone
salt '*' firewalld.block_icmp zone echo-reply
salt.modules.firewalld.default_zone() Print default zone for connections and interfaces
salt '*' firewalld.default_zone
salt.modules.firewalld.delete_service(name, restart=True) Delete an existing service
salt '*' firewalld.delete_service my_service
By default firewalld will be reloaded. However, to avoid reloading you need to specify the restart as False
salt '*' firewalld.delete_service my_service False
salt.modules.firewalld.delete_zone(zone, restart=True) Delete an existing zone
salt '*' firewalld.delete_zone my_zone
salt '*' firewalld.delete_zone my_zone False
salt.modules.firewalld.get_icmp_types(permanent=True) Print predefined icmptypes
salt '*' firewalld.get_icmp_types
salt.modules.firewalld.get_interfaces(zone, permanent=True) List interfaces bound to a zone
salt '*' firewalld.get_interfaces zone
salt.modules.firewalld.get_masquerade(zone=None, permanent=True) Show if masquerading is enabled on a zone.  If zone is omitted, default zone will be used.
salt '*' firewalld.get_masquerade zone
salt.modules.firewalld.get_rich_rules(zone, permanent=True) List rich rules bound to a zone
salt '*' firewalld.get_rich_rules zone
salt.modules.firewalld.get_service_ports(service) List ports of a service.
salt '*' firewalld.get_service_ports zone
salt.modules.firewalld.get_service_protocols(service) List protocols of a service.
salt '*' firewalld.get_service_protocols zone
salt.modules.firewalld.get_services(permanent=True) Print predefined services
salt '*' firewalld.get_services
salt.modules.firewalld.get_sources(zone, permanent=True) List sources bound to a zone
salt '*' firewalld.get_sources zone
salt.modules.firewalld.get_zones(permanent=True) Print predefined zones
salt '*' firewalld.get_zones
salt.modules.firewalld.list_all(zone=None, permanent=True) List everything added for or enabled in a zone
salt '*' firewalld.list_all
List a specific zone
salt '*' firewalld.list_all my_zone
salt.modules.firewalld.list_icmp_block(zone, permanent=True) List ICMP blocks on a zone
salt '*' firewlld.list_icmp_block zone
salt.modules.firewalld.list_port_fwd(zone, permanent=True) List port forwarding
salt '*' firewalld.list_port_fwd public
salt.modules.firewalld.list_ports(zone, permanent=True) List all ports in a zone.
salt '*' firewalld.list_ports
salt.modules.firewalld.list_services(zone=None, permanent=True) List services added for zone as a space separated list.  If zone is omitted, default zone will be used.
salt '*' firewalld.list_services
salt '*' firewalld.list_services my_zone
salt.modules.firewalld.list_zones(permanent=True) List everything added for or enabled in all zones
salt '*' firewalld.list_zones
salt.modules.firewalld.make_permanent() Make current runtime configuration permanent.
salt '*' firewalld.make_permanent
salt.modules.firewalld.new_service(name, restart=True) Add a new service
salt '*' firewalld.new_service my_service
salt '*' firewalld.new_service my_service False
salt.modules.firewalld.new_zone(zone, restart=True) Add a new zone
salt '*' firewalld.new_zone my_zone
salt '*' firewalld.new_zone my_zone False
salt.modules.firewalld.reload_rules() Reload the firewall rules, which makes the permanent configuration the new runtime configuration without losing state information.
salt '*' firewalld.reload_rules
salt.modules.firewalld.remove_interface(zone, interface, permanent=True) Remove an interface bound to a zone
salt '*' firewalld.remove_interface zone eth0
salt.modules.firewalld.remove_masquerade(zone=None, permanent=True) Remove masquerade on a zone.  If zone is omitted, default zone will be used.
salt '*' firewalld.remove_masquerade
To remove masquerade on a specific zone
salt '*' firewalld.remove_masquerade dmz
salt.modules.firewalld.remove_port(zone, port, permanent=True) Remove a specific port from a zone.
salt '*' firewalld.remove_port internal 443/tcp
salt.modules.firewalld.remove_port_fwd(zone, src, dest, proto='tcp', dstaddr='', permanent=True) Remove Port Forwarding.
salt '*' firewalld.remove_port_fwd public 80 443 tcp
salt.modules.firewalld.remove_rich_rule(zone, rule, permanent=True) Add a rich rule to a zone
salt '*' firewalld.remove_rich_rule zone 'rule'