salt.modules.file
Manage information about regular files, directories, and special files on the minion, set/read user, group, mode, and data
- class
salt.modules.file.
AttrChanges
(added, removed) -
-
added
-
Alias for field number 0
-
removed
-
Alias for field number 1
-
-
New in version 2014.1.0.
Test whether the Salt process has the specified access to the file. One of the following modes must be specified:
f: Test the existence of the path r: Test the readability of the path w: Test the writability of the path x: Test whether the path can be executed
CLI Example:
salt '*' file.access /path/to/file f salt '*' file.access /path/to/file x
salt.modules.file.access(path, mode)
-
New in version 0.9.5.
Append text to the end of a file
- path
-
path to file
- *args
-
strings to append to file
CLI Example:
salt '*' file.append /etc/motd \ "With all thine offerings thou shalt offer salt." \ "Salt is what makes things taste bad when it isn't in them."
Attention
If you need to pass a string to append and that string contains an equal sign, you must include the argument name, args. For example:
salt '*' file.append /etc/motd args='cheese=spam' salt '*' file.append /etc/motd args="['cheese=spam','spam=cheese']"
salt.modules.file.append(path, *args, **kwargs)
-
Return the contents after applying the templating engine
- contents
-
template string
- template
-
template format
- context
-
Overrides default context variables passed to the template.
- defaults
-
Default context passed to the template.
CLI Example:
salt '*' file.apply_template_on_contents \ contents='This is a {{ template }} string.' \ template=jinja \ "context={}" "defaults={'template': 'cool'}" \ saltenv=base
salt.modules.file.apply_template_on_contents(contents, template, context, defaults, saltenv)
-
Returns the final component of a pathname
New in version 2015.5.0.
This can be useful at the CLI but is frequently useful when scripting.
{%- set filename = salt['file.basename'](source_file) %}
CLI Example:
salt '*' file.basename 'test/test.config'
salt.modules.file.basename(path)
-
New in version 2014.1.0.
Replace content of a text block in a file, delimited by line markers
A block of content delimited by comments can help you manage several lines entries without worrying about old entries removal.
Note
This function will store two copies of the file in-memory (the original version and the edited version) in order to detect changes and only edit the targeted file if necessary.
- path
-
Filesystem path to the file to be edited
- marker_start
-
The line content identifying a line as the start of the content block. Note that the whole line containing this marker will be considered, so whitespace or extra content before or after the marker is included in final output
- marker_end
-
The line content identifying the end of the content block. As of versions 2017.7.5 and 2018.3.1, everything up to the text matching the marker will be replaced, so it's important to ensure that your marker includes the beginning of the text you wish to replace.
- content
-
The content to be used between the two lines identified by marker_start and marker_stop.
- append_if_not_found: False
-
If markers are not found and set to
True
then, the markers and content will be appended to the file. - prepend_if_not_found: False
-
If markers are not found and set to
True
then, the markers and content will be prepended to the file. - insert_before_match
-
If markers are not found, this parameter can be set to a regex which will insert the block before the first found occurrence in the file.
New in version 3001.
- insert_after_match
-
If markers are not found, this parameter can be set to a regex which will insert the block after the first found occurrence in the file.
New in version 3001.
- backup
-
The file extension to use for a backup of the file if any edit is made. Set to
False
to skip making a backup. - dry_run: False
-
If
True
, do not make any edits to the file and simply return the changes that would be made. - show_changes: True
-
Controls how changes are presented. If
True
, this function will return a unified diff of the changes made. If False, then it will return a boolean (True
if any changes were made, otherwiseFalse
). - append_newline: False
-
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 isFalse
, then a newline will not be added to the content block. If it isNone
then a newline will only be added to the content block if it does not already end in a newline.New in version 2016.3.4.
Changed in version 2017.7.5,2018.3.1: New behavior added when value is
None
.Changed in version 2019.2.0: The default value of this argument will change to
None
to match the behavior of thefile.blockreplace state
CLI Example:
salt '*' file.blockreplace /etc/hosts '#-- start managed zone foobar : DO NOT EDIT --' \ '#-- end managed zone foobar --' $'10.0.1.1 foo.foobar\n10.0.1.2 bar.foobar' True
salt.modules.file.blockreplace(path, marker_start='#-- start managed zone --', marker_end='#-- end managed zone --', content='', append_if_not_found=False, prepend_if_not_found=False, backup='.bak', dry_run=False, show_changes=True, append_newline=False, insert_before_match=None, insert_after_match=None)
-
New in version 2018.3.0.
Change the attributes of files. This function accepts one or more files and the following options:
- operator
-
Can be wither
add
orremove
. Determines whether attributes should be added or removed from files - attributes
-
One or more of the following characters:
aAcCdDeijPsStTu
, representing attributes to add to/remove from files - version
-
a version number to assign to the file(s)
- flags
-
One or more of the following characters:
RVf
, representing flags to assign to chattr (recurse, verbose, suppress most errors)
CLI Example:
salt '*' file.chattr foo1.txt foo2.txt operator=add attributes=ai salt '*' file.chattr foo3.txt operator=remove attributes=i version=2
salt.modules.file.chattr(*files, **kwargs)
-
Check for the changes in the file metadata.
CLI Example:
salt '*' file.check_file_meta /etc/httpd/conf.d/httpd.conf None salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' None base
Note
Supported hash types include sha512, sha384, sha256, sha224, sha1, and md5.
- name
-
Path to file destination
- sfn
-
Template-processed source file contents
- source
-
URL to file source
- source_sum
-
File checksum information as a dictionary
{hash_type: md5, hsum: <md5sum>}
- user
-
Destination file user owner
- group
-
Destination file group owner
- mode
-
Destination file permissions mode
- attrs
-
Destination file attributes
New in version 2018.3.0.
- saltenv
-
Salt environment used to resolve source files
- contents
-
File contents
- seuser
-
selinux user attribute
New in version 3001.
- serole
-
selinux role attribute
New in version 3001.
- setype
-
selinux type attribute
New in version 3001.
- serange
-
selinux range attribute
New in version 3001.
- verify_ssl
-
If
False
, remote https file sources (https://
) will not attempt to validate the servers certificate. Default is True.New in version 3002.
salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, attrs, saltenv, contents=None, seuser=None, serole=None, setype=None, serange=None, verify_ssl=True)
-
Check if a file matches the given hash string
Returns
True
if the hash matches, otherwiseFalse
.- path
-
Path to a file local to the minion.
- hash
-
The hash to check against the file specified in the
path
argument.Changed in version 2016.11.4.
For this and newer versions the hash can be specified without an accompanying hash type (e.g.
e138491e9d5b97023cea823fe17bac22
), but for earlier releases it is necessary to also specify the hash type in the format<hash_type>=<hash_value>
(e.g.md5=e138491e9d5b97023cea823fe17bac22
).
CLI Example:
salt '*' file.check_hash /etc/fstab e138491e9d5b97023cea823fe17bac22 salt '*' file.check_hash /etc/fstab md5=e138491e9d5b97023cea823fe17bac22
salt.modules.file.check_hash(path, file_hash)
-
Check to see what changes need to be made for a file
CLI Example:
salt '*' file.check_managed /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' jinja True None None base
salt.modules.file.check_managed(name, source, source_hash, source_hash_name, user, group, mode, attrs, template, context, defaults, saltenv, contents=None, skip_verify=False, seuser=None, serole=None, setype=None, serange=None, **kwargs)
-
Return a dictionary of what changes need to be made for a file
Changed in version 3001: selinux attributes added
- verify_ssl
-
If
False
, remote https file sources (https://
) and source_hash will not attempt to validate the servers certificate. Default is True.New in version 3002.
CLI Example:
salt '*' file.check_managed_changes /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' jinja True None None base
salt.modules.file.check_managed_changes(name, source, source_hash, source_hash_name, user, group, mode, attrs, template, context, defaults, saltenv, contents=None, skip_verify=False, keep_mode=False, seuser=None, serole=None, setype=None, serange=None, verify_ssl=True, **kwargs)
-
Changed in version 3001: Added selinux options
Check the permissions on files, modify attributes and chown if needed. File attributes are only verified if lsattr(1) is installed.
CLI Example:
salt '*' file.check_perms /etc/sudoers '{}' root root 400 ai
Changed in version 2014.1.3:
follow_symlinks
option added
salt.modules.file.check_perms(name, ret, user, group, mode, attrs=None, follow_symlinks=False, seuser=None, serole=None, setype=None, serange=None)
-
Change the group of a file
- path
-
path to the file or directory
- group
-
group owner
CLI Example:
salt '*' file.chgrp /etc/passwd root
salt.modules.file.chgrp(path, group)
-
Chown a file, pass the file the desired user and group
- path
-
path to the file or directory
- user
-
user owner
- group
-
group owner
CLI Example:
salt '*' file.chown /etc/passwd root root
salt.modules.file.chown(path, user, group)
-
Deprecated since version 0.17.0: Use
replace()
instead.Comment out specified lines in a file
- path
-
The full path to the file to be edited
- regex
-
A regular expression used to find the lines that are to be commented; this pattern will be wrapped in parenthesis and will move any preceding/trailing
^
or$
characters outside the parenthesis (e.g., the pattern^foo$
will be rewritten as^(foo)$
) - char:
#
-
The character to be inserted at the beginning of a line in order to comment it out
- backup:
.bak
-
The file will be backed up before edit with this file extension
Warning
This backup will be overwritten each time
sed
/comment
/uncomment
is called. Meaning the backup will only be useful after the first invocation.
CLI Example:
salt '*' file.comment /etc/modules pcspkr
salt.modules.file.comment(path, regex, char='#', backup='.bak')
-
Comment or Uncomment a line in a text file.
- Parameters
-
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
CLI Example:
The following example will comment out the
pcspkr
line in the/etc/modules
file using the default#
character and create a backup file namedmodules.bak
salt '*' file.comment_line '/etc/modules' '^pcspkr'
CLI Example:
The following example will uncomment the
log_level
setting inminion
config file if it is set to eitherwarning
,info
, ordebug
using the#
character and create a backup file namedminion.bk
salt '*' file.comment_line 'C:\salt\conf\minion' '^log_level: (warning|info|debug)' '#' False '.bk'
salt.modules.file.comment_line(path, regex, char='#', cmnt=True, backup='.bak')
-
Deprecated since version 0.17.0: Use
search()
instead.Return
True
if the file atpath
containstext
CLI Example:
salt '*' file.contains /etc/crontab 'mymaintenance.sh'
salt.modules.file.contains(path, text)
-
Deprecated since version 0.17.0: Use
search()
instead.Return
True
if the given glob matches a string in the named fileCLI Example:
salt '*' file.contains_glob /etc/foobar '*cheese*'
salt.modules.file.contains_glob(path, glob_expr)
-
Deprecated since version 0.17.0: Use
search()
instead.Return True if the given regular expression matches on any line in the text of a given file.
If the lchar argument (leading char) is specified, it will strip lchar from the left side of each line before trying to match
CLI Example:
salt '*' file.contains_regex /etc/crontab
salt.modules.file.contains_regex(path, regex, lchar='')
-
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
andstates.file.recurse
.CLI Example:
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.copy(src, dst, recurse=False, remove_existing=False)
-
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
CLI Example:
salt '*' file.delete_backup /var/cache/salt/minion/file_backup/home/foo/bar/baz.txt 0
salt.modules.file.delete_backup(path, backup_id)
-
Tests to see if path is a valid directory. Returns True/False.
CLI Example:
salt '*' file.directory_exists /etc
salt.modules.file.directory_exists(path)
-
Returns the directory component of a pathname
New in version 2015.5.0.
This can be useful at the CLI but is frequently useful when scripting.
{%- from salt['file.dirname'](tpldir) + '/vars.jinja' import parent_vars %}
CLI Example:
salt '*' file.dirname 'test/path/filename.config'
salt.modules.file.dirname(path)
-
Recursively calculate disk usage of path and return it in bytes
CLI Example:
salt '*' file.diskusage /path/to/check
salt.modules.file.diskusage(path)
-
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 athttps://mydomain.tld/different_name.tar.gz
. Thefile.managed
state now also passes this function the source URI as well as thesource_hash_name
(if specified). In cases wheresource_hash_name
is specified, it takes precedence over both thefile_name
andsource
. When it is not specified,file_name
takes precedence oversource
. 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 thesource_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 thesource_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.For example:
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
CLI Example:
salt '*' file.extract_hash /path/to/hash/file sha512 /etc/foo
salt.modules.file.extract_hash(hash_fn, hash_type='sha256', file_name='', source='', source_hash_name=None)
-
Tests to see if path is a valid file. Returns True/False.
CLI Example:
salt '*' file.file_exists /etc/passwd
salt.modules.file.file_exists(path)
-
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 pathnamesfile-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 uidsgroups
: a space and/or comma separated list of group names and/or gidssize-unit
:b: bytes k: kilobytes m: megabytes g: gigabytes t: terabytes
interval:
[<num>w] [<num>d] [<num>h] [<num>m] [<num>s] where: w: week d: day h: hour m: minute s: second
print-opts: a comma and/or space separated list of one or more of the following:
group: group name md5: MD5 digest of file contents mode: file permissions (as integer) mtime: last modification time (as time_t) name: file basename path: file absolute path size: file size in bytes type: file type user: user name
CLI Examples:
salt '*' file.find / type=f name=\*.bak size=+10m salt '*' file.find /var mtime=+30d size=+10m print=path,size,mtime salt '*' file.find /var/log name=\*.[0-9] mtime=+30d size=+10m delete
salt.modules.file.find(path, *args, **kwargs)
-
Get major/minor info from a device
CLI Example:
salt '*' file.get_devmm /dev/chr
salt.modules.file.get_devmm(name)
-
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 toFalse
will be returned. - template: False
-
Set to
True
if two templates are being compared. This is not useful except for within states, with theobfuscate_templates
option set toTrue
.New in version 2018.3.0.
- 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.New in version 2018.3.0.
- 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.New in version 2018.3.0.
CLI Examples:
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_diff(file1, file2, saltenv='base', show_filenames=True, show_changes=True, template=False, source_hash_file1=None, source_hash_file2=None)
-
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
CLI Example:
salt '*' file.get_gid /etc/passwd
Changed in version 0.16.4:
follow_symlinks
option added
salt.modules.file.get_gid(path, follow_symlinks=True)
-
Return the group that owns a given file
- path
-
file or directory of which to get the group
- follow_symlinks
-
indicated if symlinks should be followed
CLI Example:
salt '*' file.get_group /etc/passwd
Changed in version 0.16.4:
follow_symlinks
option added
salt.modules.file.get_group(path, follow_symlinks=True)
-
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'
- path
-
path to the file or directory
- form
-
desired sum format
- chunk_size
-
amount to sum at once
CLI Example:
salt '*' file.get_hash /etc/shadow
- This is better than
salt.modules.file.get_hash(path, form='sha256', chunk_size=65536)
-
Return the managed file data for file.managed
- name
-
location where the file lives on the server
- template
-
template format
- 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.New in version 2016.3.5.
- user
-
Owner of file
- group
-
Group owner of file
- mode
-
Permissions of file
- attrs
-
Attributes of file
New in version 2018.3.0.
- 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 thesource_hash
argument will be ignored.New in version 2016.3.0.
- verify_ssl
-
If
False
, remote https file sources (https://
) and source_hash will not attempt to validate the servers certificate. Default is True.New in version 3002.
CLI Example:
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_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 mode of a file
- path
-
file or directory of which to get the mode
- follow_symlinks
-
indicated if symlinks should be followed
CLI Example:
salt '*' file.get_mode /etc/passwd
Changed in version 2014.1.0:
follow_symlinks
option added
salt.modules.file.get_mode(path, follow_symlinks=True)
-
Get an SELinux context from a given path
CLI Example:
salt '*' file.get_selinux_context /etc/hosts
salt.modules.file.get_selinux_context(path)
-
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. Ifsource_hash
refers to a file containing hashes, then this filename will be used to match a filename in that file. If thesource_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 andfile.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 withsalt://
). - verify_ssl
-
If
False
, remote https file sources (https://
) and source_hash will not attempt to validate the servers certificate. Default is True.New in version 3002.
CLI Example:
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_source_sum(file_name='', source='', source_hash=None, source_hash_name=None, saltenv='base', verify_ssl=True)
-
Return the checksum for the given file. The following checksum algorithms are supported:
md5
sha1
sha224
sha256 (default)
sha384
sha512
- path
-
path to the file or directory
- form
-
desired sum format
CLI Example:
salt '*' file.get_sum /etc/passwd sha512
salt.modules.file.get_sum(path, form='sha256')
-
Return the id of the user that owns a given file
- path
-
file or directory of which to get the uid
- follow_symlinks
-
indicated if symlinks should be followed
CLI Example:
salt '*' file.get_uid /etc/passwd
Changed in version 0.16.4:
follow_symlinks
option added
salt.modules.file.get_uid(path, follow_symlinks=True)
-
Return the user that owns a given file
- path
-
file or directory of which to get the user
- follow_symlinks
-
indicated if symlinks should be followed
CLI Example:
salt '*' file.get_user /etc/passwd
Changed in version 0.16.4:
follow_symlinks
option added
salt.modules.file.get_user(path, follow_symlinks=True)
-
Convert the group id to the group name on this system
- gid
-
gid to convert to a group name
CLI Example:
salt '*' file.gid_to_group 0
salt.modules.file.gid_to_group(gid)
-
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
, ora[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.
CLI Example:
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.grep(path, pattern, *opts)
-
Convert the group to the gid on this system
- group
-
group to convert to its gid
CLI Example:
salt '*' file.group_to_gid root
salt.modules.file.group_to_gid(group)
-
Check if a file exists and is a block device.
CLI Example:
salt '*' file.is_blkdev /dev/blk
salt.modules.file.is_blkdev(name)
-
Check if a file exists and is a character device.
CLI Example:
salt '*' file.is_chrdev /dev/chr
salt.modules.file.is_chrdev(name)
-
Check if a file exists and is a FIFO.
CLI Example:
salt '*' file.is_fifo /dev/fifo
salt.modules.file.is_fifo(name)
-
Check if the path is a hard link by verifying that the number of links is larger than 1
CLI Example:
salt '*' file.is_hardlink /path/to/link
salt.modules.file.is_hardlink(path)
-
Check if the path is a symbolic link
CLI Example:
salt '*' file.is_link /path/to/link
salt.modules.file.is_link(path)
-
Return a normalized file system path for the underlying OS
New in version 2014.7.0.
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') }}
CLI Example:
salt '*' file.join '/' 'usr' 'local' 'bin'
salt.modules.file.join(*args)
-
Chown a file, pass the file the desired user and group without following symlinks.
- path
-
path to the file or directory
- user
-
user owner
- group
-
group owner
CLI Example:
salt '*' file.chown /etc/passwd root root
salt.modules.file.lchown(path, user, group)
-
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 findfile.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
norafter
are provided, andmatch
is alsoNone
, match falls back to thecontent
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
andafter
are specified either zero lines, or lines that contain thecontent
line are allowed to be in betweenbefore
andafter
. 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
andafter
, if they are specified. The line will always be inserted right beforebefore
.insert
also allows the use oflocation
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 oflocation
,before
, orafter
is required. Iflocation
is used,before
andafter
are ignored. -
- location
-
In
mode='insert'
only, whether to place thecontent
at the beginning or end of a the file. Iflocation
is provided,before
andafter
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
andinsert
modes. Thecontent
will be inserted just before this line, with matching indentation unlessindent=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
andinsert
modes. Thecontent
will be inserted directly after this line, unlessbefore
is also provided. Ifbefore
is not provided, indentation will match this line, unlessindent=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 isTrue
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 isTrue
CLI Example:
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 ofkey=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"
Examples:
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:
[some_config] # Some config file 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 betweenbefore
andafter
.
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 2014.1.0.
Create a hard link to a file
CLI Example:
salt '*' file.link /path/to/file /path/to/link
salt.modules.file.link(src, path)
-
New in version 0.17.0.
Lists the previous versions of a file backed up using Salt's file state backup system.
- path
-
The path on the minion to check for backups
- limit
-
Limit the number of results to the most recent N backups
CLI Example:
salt '*' file.list_backups /foo/bar/baz.txt
salt.modules.file.list_backups(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
- limit
-
Limit the number of results to the most recent N backups
CLI Example:
salt '*' file.list_backups_dir /foo/bar/baz/
salt.modules.file.list_backups_dir(path, limit=None)
-
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 onAIX
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.
CLI Example:
salt '*' file.lsattr foo1.txt
salt.modules.file.lsattr(path)
-
New in version 2014.1.0.
Returns the lstat attributes for the given file or dir. Does not support symbolic links.
CLI Example:
salt '*' file.lstat /path/to/file
salt.modules.file.lstat(path)
-
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/
.CLI Example:
salt '*' file.makedirs /opt/code/
salt.modules.file.makedirs_(path, user=None, group=None, mode=None)
-
Taken and modified from os.makedirs to set user, group and mode for each directory created.
CLI Example:
salt '*' file.makedirs_perms /opt/code
salt.modules.file.makedirs_perms(name, user=None, group=None, mode='0755')
-
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
- user
-
user owner
- group
-
group owner
- backup
-
backup_mode
- attrs
-
attributes to be set on file: '' means remove all of them
New in version 2018.3.0.
- 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 thesource_hash
argument will be ignored.New in version 2016.3.0.
- keep_mode: False
-
If
True
, and thesource
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.
New in version 2017.7.0.
- encoding_errors: 'strict'
-
Default is
`'strict'`
. See https://docs.python.org/2/library/codecs.html#codec-base-classes for the error handling schemes.New in version 2017.7.0.
- seuser
-
selinux user attribute
New in version 3001.
- serange
-
selinux range attribute
New in version 3001.
- setype
-
selinux type attribute
New in version 3001.
- serange
-
selinux range attribute
New in version 3001.
- verify_ssl
-
If
False
, remote https file sources (https://
) will not attempt to validate the servers certificate. Default is True.New in version 3002.
CLI Example:
salt '*' file.manage_file /etc/httpd/conf.d/httpd.conf '' '{}' salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' '' base ''
Changed in version 2014.7.0:
follow_symlinks
option added
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)
-
Ensure that a directory is available.
CLI Example:
salt '*' file.mkdir /opt/jetty/context
salt.modules.file.mkdir(dir_path, user=None, group=None, mode=None)
-
New in version 0.17.0.
Create a block device, character device, or fifo pipe. Identical to the gnu mknod.
CLI Examples:
salt '*' file.mknod /dev/chr c 180 31 salt '*' file.mknod /dev/blk b 8 999 salt '*' file.nknod /dev/fifo p
salt.modules.file.mknod(name, ntype, major=0, minor=0, user=None, group=None, mode='0600')
-
New in version 0.17.0.
Create a block device.
CLI Example:
salt '*' file.mknod_blkdev /dev/blk 8 999
salt.modules.file.mknod_blkdev(name, major, minor, user=None, group=None, mode='0660')
-
New in version 0.17.0.
Create a character device.
CLI Example:
salt '*' file.mknod_chrdev /dev/chr 180 31
salt.modules.file.mknod_chrdev(name, major, minor, user=None, group=None, mode='0660')
-
New in version 0.17.0.
Create a FIFO pipe.
CLI Example:
salt '*' file.mknod_fifo /dev/fifo
salt.modules.file.mknod_fifo(name, user=None, group=None, mode='0660')
-
Move a file or directory
CLI Example:
salt '*' file.move /path/to/src /path/to/dst
salt.modules.file.move(src, dst)
-
Returns Normalize path, eliminating double slashes, etc.
New in version 2015.5.0.
This can be useful at the CLI but is frequently useful when scripting.
{%- from salt['file.normpath'](tpldir + '/../vars.jinja') import parent_vars %}
CLI Example:
salt '*' file.normpath 'a/b/c/..'
salt.modules.file.normpath(path)
-
Return a list of all physical open files on the system.
CLI Examples:
salt '*' file.open_files salt '*' file.open_files by_pid=True
salt.modules.file.open_files(by_pid=False)
-
Return the relative parent directory path symbol for underlying OS
New in version 2014.7.0.
This can be useful when constructing Salt Formulas.
{% set pardir = salt['file.pardir']() %} {% set final_path = salt['file.join']('subdir', pardir, 'confdir') %}
CLI Example:
salt '*' file.pardir
salt.modules.file.pardir()
-
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.
CLI Example:
salt '*' file.patch /opt/file.txt /tmp/file.txt.patch
salt.modules.file.patch(originalfile, patchfile, options='', dry_run=False)
-
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.
New in version 2014.7.0.
CLI Example:
salt '*' file.path_exists_glob /etc/pam*/pass*
salt.modules.file.path_exists_glob(path)
-
New in version 2014.7.0.
Prepend text to the beginning of a file
- path
-
path to file
- *args
-
strings to prepend to the file
CLI Example:
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."
Attention
If you need to pass a string to append and that string contains an equal sign, you must include the argument name, args. For example:
salt '*' file.prepend /etc/motd args='cheese=spam' salt '*' file.prepend /etc/motd args="['cheese=spam','spam=cheese']"
salt.modules.file.prepend(path, *args, **kwargs)
-
Deprecated since version 0.17.0: Use
replace()
instead.Make a simple edit to a file (pure Python version)
Equivalent to:
sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"
- path
-
The full path to the file to be edited
- before
-
A pattern to find in order to replace with
after
- after
-
Text that will replace
before
- limit:
''
-
An initial pattern to search for before searching for
before
- backup:
.bak
-
The file will be backed up before edit with this file extension; WARNING: each time
sed
/comment
/uncomment
is called will overwrite this backup - flags:
gMS
-
- Flags to modify the search. Valid values are:
-
g
: Replace all occurrences of the pattern, not just the first.I
: Ignore case.L
: Make\w
,\W
,\b
,\B
,\s
and\S
dependent on the locale.M
: Treat multiple lines as a single line.S
: Make . match all characters, including newlines.U
: Make\w
,\W
,\b
,\B
,\d
,\D
,\s
and\S
dependent on Unicode.X
: Verbose (whitespace is ignored).
- multi:
False
-
If True, treat the entire file as a single line
Forward slashes and single quotes will be escaped automatically in the
before
andafter
patterns.CLI Example:
salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'
salt.modules.file.psed(path, before, after, limit='', backup='.bak', flags='gMS', escape_all=False, multi=False)
-
New in version 2017.7.0.
Return the content of the file.
- Parameters
-
binary (bool) -- Whether to read and return binary data
CLI Example:
salt '*' file.read /path/to/file
salt.modules.file.read(path, binary=False)
-
New in version 2014.1.0.
Return a list containing the contents of a directory
CLI Example:
salt '*' file.readdir /path/to/dir/
salt.modules.file.readdir(path)
-
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
CLI Example:
salt '*' file.readlink /path/to/link
salt.modules.file.readlink(path, canonicalize=False)
-
Remove the named file. If a directory is supplied, it will be recursively deleted.
CLI Example:
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(path)
-
Rename a file or directory
CLI Example:
salt '*' file.rename /path/to/src /path/to/dst
salt.modules.file.rename(src, dst)
-
New in version 0.17.0.
Replace occurrences of a pattern in a file. If
show_changes
isTrue
, then a diff of what changed will be returned, otherwise aTrue
will be returned when changes are made, andFalse
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
, onlyn
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 valuefile
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 whenrepl
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 aTrue
/False
value ifshow_changes
is set toFalse
). - 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, andFalse
if not. - show_changes: True
-
If
True
, return a diff of changes made. Otherwise, returnTrue
if changes were made, andFalse
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 returnFalse
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 usingbackup
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.
If an equal sign (
=
) appears in an argument to a Salt command it is interpreted as a keyword argument in the formatkey=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.replace /path/to/file pattern='=' repl=':' salt '*' file.replace /path/to/file pattern="bind-address\s*=" repl='bind-address:'
CLI Examples:
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.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.
Restore 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 restore, as found using
file.list_backups
CLI Example:
salt '*' file.restore_backup /foo/bar/baz.txt 0
salt.modules.file.restore_backup(path, backup_id)
-
Reset the SELinux context on a given path
CLI Example:
salt '*' file.restorecon /home/user/.ssh/authorized_keys
salt.modules.file.restorecon(path, recursive=False)
-
New in version 2014.1.0.
Remove the specified directory. Fails if a directory is not empty.
CLI Example:
salt '*' file.rmdir /tmp/foo/
salt.modules.file.rmdir(path)
-
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 setsbufsize
to 'file'.New in version 2015.8.0.
CLI Example:
salt '*' file.search /etc/crontab 'mymaintenance.sh'
salt.modules.file.search(path, pattern, flags=8, bufsize=1, ignore_if_missing=False, multiline=False)
-
Deprecated since version 0.17.0: Use
replace()
instead.Make a simple edit to a file
Equivalent to:
sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"
- path
-
The full path to the file to be edited
- before
-
A pattern to find in order to replace with
after
- after
-
Text that will replace
before
- limit:
''
-
An initial pattern to search for before searching for
before
- backup:
.bak
-
The file will be backed up before edit with this file extension; WARNING: each time
sed
/comment
/uncomment
is called will overwrite this backup - options:
-r -e
-
Options to pass to sed
- flags:
g
-
Flags to modify the sed search; e.g.,
i
for case-insensitive pattern matching - negate_match: False
-
Negate the search command (
!
)New in version 0.17.0.
Forward slashes and single quotes will be escaped automatically in the
before
andafter
patterns.CLI Example:
salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'
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
search()
instead.Return True if the file at
path
containstext
. Utilizes sed to perform the search (line-wise search).Note: the
p
flag will be added to any flags you pass in.CLI Example:
salt '*' file.contains /etc/crontab 'mymaintenance.sh'
salt.modules.file.sed_contains(path, text, limit='', flags='g')
-
New in version 2014.1.0.
Seek to a position on a file and read it
- path
-
path to file
- seek
-
amount to read at once
- offset
-
offset to start into the file
CLI Example:
salt '*' file.seek_read /path/to/file 4096 0
salt.modules.file.seek_read(path, size, offset)
-
New in version 2014.1.0.
Seek to a position on a file and write to it
- path
-
path to file
- data
-
data to write to file
- offset
-
position in file to start writing
CLI Example:
salt '*' file.seek_write /path/to/file 'some data' 4096
salt.modules.file.seek_write(path, data, offset)
-
Set the mode of a file
- path
-
file or directory of which to set the mode
- mode
-
mode to set the path to
CLI Example:
salt '*' file.set_mode /etc/passwd 0644
salt.modules.file.set_mode(path, mode)
-
Changed in version 3001: Added persist option
Set a specific SELinux label on a given path
CLI Example:
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.set_selinux_context(path, user=None, role=None, type=None, range=None, persist=False)
-
Check the source list and return the source to use
CLI Example:
salt '*' file.source_list salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' base
salt.modules.file.source_list(source, source_hash, saltenv)
-
Return a dict containing the stats for a given file
CLI Example:
salt '*' file.stats /etc/passwd
salt.modules.file.stats(path, hash_type=None, follow_symlinks=True)
-
New in version 2014.1.0.
Perform a statvfs call against the filesystem that the file resides on
CLI Example:
salt '*' file.statvfs /path/to/file
salt.modules.file.statvfs(path)
-
Create a symbolic link (symlink, soft link) to a file
CLI Example:
salt '*' file.symlink /path/to/file /path/to/link
salt.modules.file.symlink(src, path)
-
New in version 0.9.5.
Just like the
touch
command, create a file if it doesn't exist or simply update the atime and mtime if it already does.- atime:
-
Access time in Unix epoch time
- mtime:
-
Last modification in Unix epoch time
CLI Example:
salt '*' file.touch /var/log/emptyfile
salt.modules.file.touch(name, atime=None, mtime=None)
-
New in version 2014.1.0.
Seek to a position on a file and delete everything after that point
- path
-
path to file
- length
-
offset into file to truncate
CLI Example:
salt '*' file.truncate /path/to/file 512
salt.modules.file.truncate(path, length)
-
Convert a uid to a user name
- uid
-
uid to convert to a username
CLI Example:
salt '*' file.uid_to_user 0
salt.modules.file.uid_to_user(uid)
-
Deprecated since version 0.17.0: Use
replace()
instead.Uncomment specified commented lines in a file
- path
-
The full path to the file to be edited
- regex
-
A regular expression used to find the lines that are to be uncommented. This regex should not include the comment character. A leading
^
character will be stripped for convenience (for easily switching between comment() and uncomment()). - char:
#
-
The character to remove in order to uncomment a line
- backup:
.bak
-
The file will be backed up before edit with this file extension; WARNING: each time
sed
/comment
/uncomment
is called will overwrite this backup
CLI Example:
salt '*' file.uncomment /etc/hosts.deny 'ALL: PARANOID'
salt.modules.file.uncomment(path, regex, char='#', backup='.bak')
-
Convert user name to a uid
- user
-
user name to convert to its uid
CLI Example:
salt '*' file.user_to_uid root
salt.modules.file.user_to_uid(user)
-
New in version 2014.7.0.
Write text to a file, overwriting any existing contents.
- path
-
path to file
- *args
-
strings to write to the file
CLI Example:
salt '*' file.write /etc/motd \ "With all thine offerings thou shalt offer salt."
Attention
If you need to pass a string to append and that string contains an equal sign, you must include the argument name, args. For example:
salt '*' file.write /etc/motd args='cheese=spam' salt '*' file.write /etc/motd args="['cheese=spam','spam=cheese']"
salt.modules.file.write(path, *args, **kwargs)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.file.html