salt.modules.file¶

Manage information about regular files, directories, and special files on the minion, set/read user, group, mode, and data

salt.modules.file.append(path, *args)¶

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."

salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, env, template=None, contents=None)¶

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

salt.modules.file.check_hash(path, hash)¶

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.

path: A file path
hash: A string in the form <hash_type>=<hash_value>. For example: md5=e138491e9d5b97023cea823fe17bac22

CLI Example:

salt '*' file.check_hash /etc/fstab md5=<md5sum>

salt.modules.file.check_managed(name, source, source_hash, user, group, mode, template, makedirs, context, defaults, env, contents=None, **kwargs)¶

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_perms(name, ret, user, group, mode)¶

Check the permissions on files and chown if needed

CLI Example:

salt '*' file.check_perms /etc/sudoers '{}' root root 400

salt.modules.file.chgrp(path, group)¶

Change the group of a file

CLI Example:

salt '*' file.chgrp /etc/passwd root

salt.modules.file.chown(path, user, group)¶

Chown a file, pass the file the desired user and group

CLI Example:

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.

CLI Example:

salt '*' file.comment /etc/modules pcspkr

salt.modules.file.contains(path, text)¶

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'

salt.modules.file.contains_glob(path, glob)¶

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*'

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

CLI Example:

salt '*' file.contains_regex /etc/crontab

salt.modules.file.contains_regex_multiline(path, regex)¶

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'

salt.modules.file.copy(src, dst)¶

Copy a file or directory

CLI Example:

salt '*' file.copy /path/to/src /path/to/dst

salt.modules.file.delete_backup(path, backup_id)¶

Note

This function will be available 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 delete, as found using file.list_backups

CLI Example:

salt '*' file.restore_backup /foo/bar/baz.txt 0

salt.modules.file.directory_exists(path)¶

Tests to see if path is a valid directory. Returns True/False.

CLI Example:

salt '*' file.directory_exists /etc

salt.modules.file.file_exists(path)¶

Tests to see if path is a valid file. Returns True/False.

CLI Example:

salt '*' file.file_exists /etc/passwd

salt.modules.file.find(path, **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]

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

salt.modules.file.get_devmm(name)¶

Get major/minor info from a device

CLI Example:

salt '*' file.get_devmm /dev/chr

salt.modules.file.get_diff(minionfile, masterfile, env='base')¶

Return unified diff of file compared to file on master

CLI Example:

salt '*' file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc

salt.modules.file.get_gid(path, follow_symlinks=True)¶

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

salt.modules.file.get_group(path, follow_symlinks=True)¶

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

salt.modules.file.get_hash(path, form='md5', chunk_size=4096)¶

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'

CLI Example:

salt '*' file.get_hash /etc/shadow

salt.modules.file.get_managed(name, template, source, source_hash, user, group, mode, env, context, defaults, **kwargs)¶

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

salt.modules.file.get_mode(path)¶

Return the mode of a file

CLI Example:

salt '*' file.get_mode /etc/passwd

salt.modules.file.get_selinux_context(path)¶

Get an SELinux context from a given path

CLI Example:

salt '*' file.get_selinux_context /etc/hosts

salt.modules.file.get_sum(path, form='md5')¶

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

salt.modules.file.get_uid(path, follow_symlinks=True)¶

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

salt.modules.file.get_user(path, follow_symlinks=True)¶

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

salt.modules.file.gid_to_group(gid)¶

Convert the group id to the group name on this system

CLI Example:

salt '*' file.gid_to_group 0

salt.modules.file.group_to_gid(group)¶

Convert the group to the gid on this system

CLI Example:

salt '*' file.group_to_gid root

salt.modules.file.is_blkdev(name)¶

Check if a file exists and is a block device.

CLI Example:

salt '*' file.is_blkdev /dev/blk

salt.modules.file.is_chrdev(name)¶

Check if a file exists and is a character device.

CLI Example:

salt '*' file.is_chrdev /dev/chr

salt.modules.file.is_fifo(name)¶

Check if a file exists and is a FIFO.

CLI Example:

salt '*' file.is_fifo /dev/fifo

salt.modules.file.list_backups(path, limit=None)¶

Note

This function will be available 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.makedirs(path, user=None, group=None, mode=None)¶

Ensure that the directory containing this path is available.

CLI Example:

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.

CLI Example:

salt '*' file.makedirs_perms /opt/code

salt.modules.file.manage_file(name, sfn, ret, source, source_sum, user, group, mode, env, backup, template=None, show_diff=True, contents=None)¶

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 ''

salt.modules.file.mkdir(dir_path, user=None, group=None, mode=None)¶

Ensure that a directory is available.

CLI Example:

salt '*' file.mkdir /opt/jetty/context

salt.modules.file.mknod(name, ntype, major=0, minor=0, user=None, group=None, mode='0600')¶

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_blkdev(name, major, minor, user=None, group=None, mode='0660')¶

Create a block device.

CLI Example:

salt '*' file.mknod_blkdev /dev/blk 8 999

salt.modules.file.mknod_chrdev(name, major, minor, user=None, group=None, mode='0660')¶

Create a character device.

CLI Example:

salt '*' file.mknod_chrdev /dev/chr 180 31

salt.modules.file.mknod_fifo(name, user=None, group=None, mode='0660')¶

Create a FIFO pipe.

CLI Example:

salt '*' file.mknod_fifo /dev/fifo

salt.modules.file.patch(originalfile, patchfile, options='', dry_run=False)¶

New in version 0.10.4.

Apply a patch to a file

Equivalent to:

patch <options> <originalfile> <patchfile>

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.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)

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 and after patterns.

CLI Example:

salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'

salt.modules.file.remove(path)¶

Remove the named file

CLI Example:

salt '*' file.remove /tmp/foo

salt.modules.file.rename(src, dst)¶

Rename a file or directory

CLI Example:

salt '*' file.rename /path/to/src /path/to/dst

salt.modules.file.replace(path, pattern, repl, count=0, flags=0, bufsize=1, backup='.bak', dry_run=False, search_only=False, show_changes=True)¶

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:

path -- Filesystem path to the file to be edited
pattern -- The PCRE search
repl -- The replacement text
count -- Maximum number of pattern occurrences to be replaced
flags (list or int) -- A list of flags defined in Module Contents. Each list item should be a string that will correlate to the human-friendly flag name. E.g., ['IGNORECASE', 'MULTILINE']. Note: multiline searches must specify file as the bufsize argument below.
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. Note: multiline searches must specify file buffering.
backup -- The file extension to use for a backup of the file before editing. Set to False to skip making a backup.
dry_run -- Don't make any edits to the file
search_only -- Just search for the pattern; ignore the replacement; stop on the first match
show_changes -- Output a unified diff of the old file and the new file. If False return a boolean if any changes were made. 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.

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]'

salt.modules.file.restore_backup(path, backup_id)¶

Note

This function will be available 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.restorecon(path, recursive=False)¶

Reset the SELinux context on a given path

CLI Example:

salt '*' file.restorecon /home/user/.ssh/authorized_keys

salt.modules.file.search(path, pattern, flags=0, bufsize=1)¶

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'

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

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-insensitve 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 and after patterns.

CLI Example:

salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'

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.

CLI Example:

salt '*' file.contains /etc/crontab 'mymaintenance.sh'

salt.modules.file.set_mode(path, mode)¶

Set the mode of a file

CLI Example:

salt '*' file.set_mode /etc/passwd 0644

salt.modules.file.set_selinux_context(path, user=None, role=None, type=None, range=None)¶

Set a specific SELinux label on a given path

CLI Example:

salt '*' file.set_selinux_context path <role> <type> <range>

salt.modules.file.source_list(source, source_hash, env)¶

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.stats(path, hash_type='md5', follow_symlink=False)¶

Return a dict containing the stats for a given file

CLI Example:

salt '*' file.stats /etc/passwd

salt.modules.file.symlink(src, link)¶

Create a symbolic link to a file

CLI Example:

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

CLI Example:

salt '*' file.touch /var/log/emptyfile

salt.modules.file.uid_to_user(uid)¶

Convert a uid to a user name

CLI Example:

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

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.user_to_uid(user)¶

Convert user name to a uid

CLI Example:

salt '*' file.user_to_uid root