salt.modules.win_file

Manage information about files on the minion, set/read user, group data

depends:

• win32api
• win32con
• win32security
• ntsecuritycon

salt.modules.win_file.append(path, *args)

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

New in version 0.9.5.

salt.modules.win_file.chgrp(path, group)

Change the group of a file

CLI Example:

salt '*' file.chgrp c:\temp\test.txt administrators

salt.modules.win_file.chown(path, user, group)

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

CLI Example:

salt '*' file.chown c:\temp\test.txt myusername administrators

salt.modules.win_file.comment(path, regex, char='#', backup='.bak')

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

New in version 0.9.5.

salt.modules.win_file.contains(path, text, limit='')

Return True if the file at path contains text

CLI Example:

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

New in version 0.9.5.

salt.modules.win_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.win_file.get_gid(path)

Return the id of the group that owns a given file

CLI Example:

salt '*' file.get_gid c:\temp\test.txt

salt.modules.win_file.get_group(path)

Return the group that owns a given file

CLI Example:

salt '*' file.get_group c:\temp\test.txt

salt.modules.win_file.get_mode(path)

Return the mode of a file

Right now we're just returning 777 because Windows' doesn't have a mode like Linux

CLI Example:

salt '*' file.get_mode /etc/passwd

salt.modules.win_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.win_file.get_uid(path)

Return the id of the user that owns a given file

CLI Example:

salt '*' file.get_uid c:\temp\test.txt

salt.modules.win_file.get_user(path)

Return the user that owns a given file

CLI Example:

salt '*' file.get_user c:\temp\test.txt

salt.modules.win_file.gid_to_group(gid)

Convert the group id to the group name on this system

CLI Example:

salt '*' file.gid_to_group S-1-5-21-626487655-2533044672-482107328-1010

salt.modules.win_file.group_to_gid(group)

Convert the group to the gid on this system

CLI Example:

salt '*' file.group_to_gid administrators

salt.modules.win_file.sed(path, before, after, limit='', backup='.bak', options='-r -e', flags='g')

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

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'

New in version 0.9.5.

salt.modules.win_file.touch(name, atime=None, mtime=None)

Just like 'nix's "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

New in version 0.9.5.

salt.modules.win_file.uid_to_user(uid)

Convert a uid to a user name

CLI Example:

salt '*' file.uid_to_user S-1-5-21-626487655-2533044672-482107328-1010

salt.modules.win_file.uncomment(path, regex, char='#', backup='.bak')

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; if a single whitespace character follows the comment it will also be removed

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'

New in version 0.9.5.

salt.modules.win_file.user_to_uid(user)

Convert user name to a uid

CLI Example:

salt '*' file.user_to_uid myusername