Manage information about regular files, directories, and special files on the minion, set/read user, group, mode, and data
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
New in version 2014.1.0: (Hydrogen)
CLI Example:
salt '*' file.access /path/to/file f
salt '*' file.access /path/to/file x
New in version 0.9.5.
Append text to the end of a 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."
Replace content of a text block in a file, delimited by line markers
New in version 2014.1.0: (Hydrogen)
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.
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
Check for the changes in the file metadata.
CLI Example:
salt '*' file.check_file_meta /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' base
Check if a file matches the given hash string
Returns true if the hash matched, otherwise false. Raises ValueError if the hash was not formatted correctly.
CLI Example:
salt '*' file.check_hash /etc/fstab md5=<md5sum>
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
Check the permissions on files and chown if needed
CLI Example:
salt '*' file.check_perms /etc/sudoers '{}' root root 400
Changed in version 2014.1.3: follow_symlinks option added
Change the group of a file
CLI Example:
salt '*' file.chgrp /etc/passwd root
Chown a file, pass the file the desired user and group
CLI Example:
salt '*' file.chown /etc/passwd root root
Deprecated since version 0.17.0: Use replace() instead.
Comment out specified lines in a file
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
Deprecated since version 0.17.0: Use search() instead.
Return True if the file at path contains text
CLI Example:
salt '*' file.contains /etc/crontab 'mymaintenance.sh'
Deprecated since version 0.17.0: Use search() instead.
Return True if the given glob matches a string in the named file
CLI Example:
salt '*' file.contains_glob /etc/foobar '*cheese*'
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
Deprecated since version 0.17.0: Use search() instead.
Return True if the given regular expression matches anything in the text of a given file
Traverses multiple lines at a time, via the salt BufferedReader (reads in chunks)
CLI Example:
salt '*' file.contains_regex_multiline /etc/crontab '^maint'
Copy a file or directory
CLI Example:
salt '*' file.copy /path/to/src /path/to/dst
Restore a previous version of a file that was backed up using Salt's file state backup system.
New in version 0.17.0.
CLI Example:
salt '*' file.restore_backup /foo/bar/baz.txt 0
Tests to see if path is a valid directory. Returns True/False.
CLI Example:
salt '*' file.directory_exists /etc
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 lay out rules. It specifically permits pulling hash codes from debian *.dsc files.
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 /etc/foo sha512 /path/to/hash/file
Tests to see if path is a valid file. Returns True/False.
CLI Example:
salt '*' file.file_exists /etc/passwd
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]
The default action is 'print=path'.
file-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 re (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
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
Get major/minor info from a device
CLI Example:
salt '*' file.get_devmm /dev/chr
Return unified diff of file compared to file on master
CLI Example:
salt '*' file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc
Return the id of the group that owns a given file
CLI Example:
salt '*' file.get_gid /etc/passwd
Changed in version 0.16.4: follow_symlinks option added
Return the group that owns a given file
CLI Example:
salt '*' file.get_group /etc/passwd
Changed in version 0.16.4: follow_symlinks option added
Get the hash sum of a file
It does not read the entire file into memory.
get_sum cannot really be trusted since it is vulnerable to collisions: get_sum(..., 'xyz') == 'Hash xyz not supported'
CLI Example:
salt '*' file.get_hash /etc/shadow
Return the managed file data for file.managed
CLI Example:
salt '*' file.get_managed /etc/httpd/conf.d/httpd.conf jinja salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' base None None
Return the mode of a file
CLI Example:
salt '*' file.get_mode /etc/passwd
Changed in version 2014.1.0: follow_symlinks option added
Get an SELinux context from a given path
CLI Example:
salt '*' file.get_selinux_context /etc/hosts
Return the sum for the given file, default is md5, sha1, sha224, sha256, sha384, sha512 are supported
CLI Example:
salt '*' file.get_sum /etc/passwd sha512
Return the id of the user that owns a given file
CLI Example:
salt '*' file.get_uid /etc/passwd
Changed in version 0.16.4: follow_symlinks option added
Return the user that owns a given file
CLI Example:
salt '*' file.get_user /etc/passwd
Changed in version 0.16.4: follow_symlinks option added
Convert the group id to the group name on this system
CLI Example:
salt '*' file.gid_to_group 0
Grep for a string in the specified file
Note
This function's return value is slated for refinement in future versions of Salt
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"
Convert the group to the gid on this system
CLI Example:
salt '*' file.group_to_gid root
Check if a file exists and is a block device.
CLI Example:
salt '*' file.is_blkdev /dev/blk
Check if a file exists and is a character device.
CLI Example:
salt '*' file.is_chrdev /dev/chr
Check if a file exists and is a FIFO.
CLI Example:
salt '*' file.is_fifo /dev/fifo
Chown a file, pass the file the desired user and group without following symlinks.
CLI Example:
salt '*' file.chown /etc/passwd root root
Create a hard link to a file
New in version 2014.1.0: (Hydrogen)
CLI Example:
salt '*' file.link /path/to/file /path/to/link
Lists the previous versions of a file backed up using Salt's file state backup system.
New in version 0.17.0.
CLI Example:
salt '*' file.list_backups /foo/bar/baz.txt
Returns the lstat attributes for the given file or dir. Does not support symbolic links.
CLI Example:
New in version 2014.1.0: (Hydrogen)
salt '*' file.lstat /path/to/file
Ensure that the directory containing this path is available.
CLI Example:
salt '*' file.makedirs /opt/code
Taken and modified from os.makedirs to set user, group and mode for each directory created.
CLI Example:
salt '*' file.makedirs_perms /opt/code
Checks the destination against what was retrieved with get_managed and makes the appropriate modifications (if necessary).
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 ''
Ensure that a directory is available.
CLI Example:
salt '*' file.mkdir /opt/jetty/context
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
Create a block device.
CLI Example:
salt '*' file.mknod_blkdev /dev/blk 8 999
Create a character device.
CLI Example:
salt '*' file.mknod_chrdev /dev/chr 180 31
Create a FIFO pipe.
CLI Example:
salt '*' file.mknod_fifo /dev/fifo
New in version 0.10.4.
Apply a patch to a file
Equivalent to:
patch <options> <originalfile> <patchfile>
CLI Example:
salt '*' file.patch /opt/file.txt /tmp/file.txt.patch
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>"
Forward slashes and single quotes will be escaped automatically in the before and after patterns.
CLI Example:
salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'
Return a list containing the contents of a directory
New in version 2014.1.0: (Hydrogen)
CLI Example:
salt '*' file.readdir /path/to/dir/
Return the path that a symlink points to
New in version 2014.1.0: (Hydrogen)
CLI Example:
salt '*' file.readlink /path/to/link
Remove the named file
CLI Example:
salt '*' file.remove /tmp/foo
Rename a file or directory
CLI Example:
salt '*' file.rename /path/to/src /path/to/dst
Replace occurances of a pattern in a file
New in version 0.17.0.
This is a pure Python implementation that wraps Python's sub().
Parameters: |
|
---|---|
Return type: | bool or str |
CLI Example:
salt '*' file.replace /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'
salt '*' file.replace /some/file 'before' 'after' flags='[MULTILINE, IGNORECASE]'
Restore a previous version of a file that was backed up using Salt's file state backup system.
New in version 0.17.0.
CLI Example:
salt '*' file.restore_backup /foo/bar/baz.txt 0
Reset the SELinux context on a given path
CLI Example:
salt '*' file.restorecon /home/user/.ssh/authorized_keys
Remove the specified directory. Fails if a directory is not empty.
New in version 2014.1.0: (Hydrogen)
CLI Example:
salt '*' file.rmdir /tmp/foo/
Search for occurances of a pattern in a file
New in version 0.17.0.
Params are identical to replace().
CLI Example:
salt '*' file.search /etc/crontab 'mymaintenance.sh'
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>"
Negate the search command (!)
New in version 0.17.0.
Forward slashes and single quotes will be escaped automatically in the before and after patterns.
CLI Example:
salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'
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.
CLI Example:
salt '*' file.contains /etc/crontab 'mymaintenance.sh'
Seek to a position on a file and write to it
New in version 2014.1.0: (Hydrogen)
CLI Example:
salt '*' file.seek_read /path/to/file 4096 0
Seek to a position on a file and write to it
New in version 2014.1.0: (Hydrogen)
CLI Example:
salt '*' file.seek_write /path/to/file 'some data' 4096
Set the mode of a file
CLI Example:
salt '*' file.set_mode /etc/passwd 0644
Set a specific SELinux label on a given path
CLI Example:
salt '*' file.set_selinux_context path <role> <type> <range>
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
Return a dict containing the stats for a given file
CLI Example:
salt '*' file.stats /etc/passwd
Perform a statvfs call against the filesystem that the file resides on
New in version 2014.1.0: (Hydrogen)
CLI Example:
salt '*' file.statvfs /path/to/file
Create a symbolic link to a file
CLI Example:
salt '*' file.symlink /path/to/file /path/to/link
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.
CLI Example:
salt '*' file.touch /var/log/emptyfile
Seek to a position on a file and write to it
New in version 2014.1.0: (Hydrogen)
CLI Example:
salt '*' file.truncate /path/to/file 512
Convert a uid to a user name
CLI Example:
salt '*' file.uid_to_user 0
Deprecated since version 0.17.0: Use replace() instead.
Uncomment specified commented lines in a file
CLI Example:
salt '*' file.uncomment /etc/hosts.deny 'ALL: PARANOID'
Convert user name to a uid
CLI Example:
salt '*' file.user_to_uid root
Current Salt release: 2014.1.6
Docs for previous releases on salt.rtfd.org.