Manage information about files on the minion, set/read user, group data, modify the ACL of files/directories
depends: |
|
---|
salt.modules.win_file.
WindowsError
¶salt.modules.win_file.
check_perms
(path, ret=None, owner=None, grant_perms=None, deny_perms=None, inheritance=True)¶Set owner and permissions for each directory created. Used mostly by the state system.
Parameters: |
|
---|---|
Returns: | A dictionary of changes made to the object |
Return type: | |
Raises: |
|
CLI Example:
# To grant the 'Users' group 'read & execute' permissions.
salt '*' file.check_perms C:\Temp\ Administrators "{'Users': {'perms': 'read_execute'}}"
# Locally using salt call
salt-call file.check_perms C:\Temp\ Administrators "{'Users': {'perms': 'read_execute', 'applies_to': 'this_folder_only'}}"
# Specify advanced attributes with a list
salt '*' file.check_perms C:\Temp\ Administrators "{'jsnuffy': {'perms': ['read_attributes', 'read_ea'], 'applies_to': 'files_only'}}"
salt.modules.win_file.
chgrp
(path, group)¶Change the group of a file
Under Windows, this will do nothing.
While a file in Windows does have a 'primary group', this rarely used attribute generally has no bearing on permissions unless intentionally configured and is only used to support Unix compatibility features (e.g. Services For Unix, NFS services).
Salt, therefore, remaps this function to do nothing while still being compatible with Unix behavior. When managing Windows systems, this function is superfluous and will generate an info level log entry if used directly.
If you do actually want to set the 'primary group' of a file, use file
.chpgrp
.
To set group permissions use file.set_perms
Parameters: | |
---|---|
Returns: | None |
CLI Example:
salt '*' file.chpgrp c:\temp\test.txt administrators
salt.modules.win_file.
chown
(path, user, group=None, pgroup=None, follow_symlinks=True)¶Chown a file, pass the file the desired user and group
Under Windows, the group parameter will be ignored.
This is because while files in Windows do have a 'primary group' property, this is rarely used. It generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services).
If you do want to change the 'primary group' property and understand the implications, pass the Windows only parameter, pgroup, instead.
Parameters: |
|
---|---|
Returns: | True if successful, otherwise error |
Return type: |
CLI Example:
salt '*' file.chown c:\temp\test.txt myusername
salt '*' file.chown c:\temp\test.txt myusername pgroup=Administrators
salt '*' file.chown c:\temp\test.txt myusername "pgroup='None'"
salt.modules.win_file.
chpgrp
(path, group)¶Change the group of a file
Under Windows, this will set the rarely used primary group of a file. This generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services).
Ensure you know what you are doing before using this function.
Parameters: | |
---|---|
Returns: | True if successful, otherwise error |
Return type: |
CLI Example:
salt '*' file.chpgrp c:\temp\test.txt Administrators
salt '*' file.chpgrp c:\temp\test.txt "'None'"
salt.modules.win_file.
get_attributes
(path)¶Return a dictionary object with the Windows file attributes for a file.
Parameters: | path (str) -- The path to the file or directory |
---|---|
Returns: | A dictionary of file attributes |
Return type: | dict |
CLI Example:
salt '*' file.get_attributes c:\temp\a.txt
salt.modules.win_file.
get_gid
(path, follow_symlinks=True)¶Return the id of the group that owns a given file
Under Windows, this will return the uid of the file.
While a file in Windows does have a 'primary group', this rarely used attribute generally has no bearing on permissions unless intentionally configured and is only used to support Unix compatibility features (e.g. Services For Unix, NFS services).
Salt, therefore, remaps this function to provide functionality that somewhat resembles Unix behavior for API compatibility reasons. When managing Windows systems, this function is superfluous and will generate an info level log entry if used directly.
If you do actually want to access the 'primary group' of a file, use file.get_pgid.
Parameters: | |
---|---|
Returns: | The gid of the owner |
Return type: |
CLI Example:
salt '*' file.get_gid c:\temp\test.txt
salt.modules.win_file.
get_group
(path, follow_symlinks=True)¶Return the group that owns a given file
Under Windows, this will return the user (owner) of the file.
While a file in Windows does have a 'primary group', this rarely used attribute generally has no bearing on permissions unless intentionally configured and is only used to support Unix compatibility features (e.g. Services For Unix, NFS services).
Salt, therefore, remaps this function to provide functionality that somewhat resembles Unix behavior for API compatibility reasons. When managing Windows systems, this function is superfluous and will generate an info level log entry if used directly.
If you do actually want to access the 'primary group' of a file, use file.get_pgroup.
Parameters: | |
---|---|
Returns: | The name of the owner |
Return type: |
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 None because Windows' doesn't have a mode like Linux
Parameters: | path (str) -- The path to the file or directory |
---|---|
Returns: | None |
CLI Example:
salt '*' file.get_mode /etc/passwd
salt.modules.win_file.
get_pgid
(path, follow_symlinks=True)¶Return the id of the primary group that owns a given file (Windows only)
This function will return the rarely used primary group of a file. This generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services).
Ensure you know what you are doing before using this function.
Parameters: | |
---|---|
Returns: | The gid of the primary group |
Return type: |
CLI Example:
salt '*' file.get_pgid c:\temp\test.txt
salt.modules.win_file.
get_pgroup
(path, follow_symlinks=True)¶Return the name of the primary group that owns a given file (Windows only)
This function will return the rarely used primary group of a file. This generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services).
Ensure you know what you are doing before using this function.
The return value may be 'None', e.g. if the user is not on a domain. This is a valid group - do not confuse this with the Salt/Python value of None which means no value was returned. To be certain, use the get_pgid function which will return the SID, including for the system 'None' group.
Parameters: | |
---|---|
Returns: | The name of the primary group |
Return type: |
CLI Example:
salt '*' file.get_pgroup c:\temp\test.txt
salt.modules.win_file.
get_uid
(path, follow_symlinks=True)¶Return the id of the user that owns a given file
Symlinks are followed by default to mimic Unix behavior. Specify follow_symlinks=False to turn off this behavior.
Parameters: | |
---|---|
Returns: | The uid of the owner |
Return type: |
CLI Example:
salt '*' file.get_uid c:\temp\test.txt
salt '*' file.get_uid c:\temp\test.txt follow_symlinks=False
salt.modules.win_file.
get_user
(path, follow_symlinks=True)¶Return the user that owns a given file
Symlinks are followed by default to mimic Unix behavior. Specify follow_symlinks=False to turn off this behavior.
Parameters: | |
---|---|
Returns: | The name of the owner |
Return type: |
CLI Example:
salt '*' file.get_user c:\temp\test.txt
salt '*' file.get_user c:\temp\test.txt follow_symlinks=False
salt.modules.win_file.
gid_to_group
(gid)¶Convert the group id to the group name on this system
Under Windows, because groups are just another ACL entity, this function behaves the same as uid_to_user.
For maintaining Windows systems, this function is superfluous and only exists for API compatibility with Unix. Use the uid_to_user function instead; an info level log entry will be generated if this function is used directly.
Parameters: | gid (str) -- The gid of the group |
---|---|
Returns: | The name of the group |
Return type: | str |
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
Under Windows, because groups are just another ACL entity, this function behaves the same as user_to_uid, except if None is given, '' is returned.
For maintaining Windows systems, this function is superfluous and only exists for API compatibility with Unix. Use the user_to_uid function instead; an info level log entry will be generated if this function is used directly.
Parameters: | group (str) -- The name of the group |
---|---|
Returns: | The gid of the group |
Return type: | str |
CLI Example:
salt '*' file.group_to_gid administrators
salt.modules.win_file.
is_link
(path)¶Check if the path is a symlink
This is only supported on Windows Vista or later.
Inline with Unix behavior, this function will raise an error if the path is not a symlink, however, the error raised will be a SaltInvocationError, not an OSError.
Parameters: | path (str) -- The path to a file or directory |
---|---|
Returns: | True if path is a symlink, otherwise False |
Return type: | bool |
CLI Example:
salt '*' file.is_link /path/to/link
salt.modules.win_file.
lchown
(path, user, group=None, pgroup=None)¶Chown a file, pass the file the desired user and group without following any symlinks.
Under Windows, the group parameter will be ignored.
This is because while files in Windows do have a 'primary group' property, this is rarely used. It generally has no bearing on permissions unless intentionally configured and is most commonly used to provide Unix compatibility (e.g. Services For Unix, NFS services).
If you do want to change the 'primary group' property and understand the implications, pass the Windows only parameter, pgroup, instead.
To set the primary group to 'None', it must be specified in quotes. Otherwise Salt will interpret it as the Python value of None and no primary group changes will occur. See the example below.
Parameters: | |
---|---|
Returns: | True if successful, otherwise error |
Return type: |
CLI Example:
salt '*' file.lchown c:\temp\test.txt myusername
salt '*' file.lchown c:\temp\test.txt myusername pgroup=Administrators
salt '*' file.lchown c:\temp\test.txt myusername "pgroup='None'"
salt.modules.win_file.
makedirs_
(path, owner=None, grant_perms=None, deny_perms=None, inheritance=True)¶Ensure that the parent directory containing this path is available.
Parameters: |
|
---|
Note
The path must end with a trailing slash otherwise the directory(s) will
be created up to the parent directory. For example if path is
C:\temp\test
, then it would be treated as C:\temp\
but if
the path ends with a trailing slash like C:\temp\test\
, then it
would be treated as C:\temp\test\
.
Returns: | True if successful |
---|---|
Return type: | bool |
Raises: | CommandExecutionError -- If unsuccessful |
CLI Example:
# To grant the 'Users' group 'read & execute' permissions.
salt '*' file.makedirs C:\Temp\ Administrators "{'Users': {'perms': 'read_execute'}}"
# Locally using salt call
salt-call file.makedirs C:\Temp\ Administrators "{'Users': {'perms': 'read_execute', 'applies_to': 'this_folder_only'}}"
# Specify advanced attributes with a list
salt '*' file.makedirs C:\Temp\ Administrators "{'jsnuffy': {'perms': ['read_attributes', 'read_ea'], 'applies_to': 'this_folder_only'}}"
salt.modules.win_file.
makedirs_perms
(path, owner=None, grant_perms=None, deny_perms=None, inheritance=True)¶Set owner and permissions for each directory created.
Parameters: |
|
---|---|
Returns: | True if successful, otherwise raises an error |
Return type: |
CLI Example:
# To grant the 'Users' group 'read & execute' permissions.
salt '*' file.makedirs_perms C:\Temp\ Administrators "{'Users': {'perms': 'read_execute'}}"
# Locally using salt call
salt-call file.makedirs_perms C:\Temp\ Administrators "{'Users': {'perms': 'read_execute', 'applies_to': 'this_folder_only'}}"
# Specify advanced attributes with a list
salt '*' file.makedirs_perms C:\Temp\ Administrators "{'jsnuffy': {'perms': ['read_attributes', 'read_ea'], 'applies_to': 'this_folder_files'}}"
salt.modules.win_file.
mkdir
(path, owner=None, grant_perms=None, deny_perms=None, inheritance=True)¶Ensure that the directory is available and permissions are set.
Parameters: |
|
---|---|
Returns: | True if successful |
Return type: | |
Raises: |
|
CLI Example:
# To grant the 'Users' group 'read & execute' permissions.
salt '*' file.mkdir C:\Temp\ Administrators "{'Users': {'perms': 'read_execute'}}"
# Locally using salt call
salt-call file.mkdir C:\Temp\ Administrators "{'Users': {'perms': 'read_execute', 'applies_to': 'this_folder_only'}}"
# Specify advanced attributes with a list
salt '*' file.mkdir C:\Temp\ Administrators "{'jsnuffy': {'perms': ['read_attributes', 'read_ea'], 'applies_to': 'this_folder_only'}}"
salt.modules.win_file.
readlink
(path)¶Return the path that a symlink points to
This is only supported on Windows Vista or later.
Inline with Unix behavior, this function will raise an error if the path is not a symlink, however, the error raised will be a SaltInvocationError, not an OSError.
Parameters: | path (str) -- The path to the symlink |
---|---|
Returns: | The path that the symlink points to |
Return type: | str |
CLI Example:
salt '*' file.readlink /path/to/link
salt.modules.win_file.
remove
(path, force=False)¶Remove the named file or directory
Parameters: | |
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt '*' file.remove C:\Temp
salt.modules.win_file.
set_attributes
(path, archive=None, hidden=None, normal=None, notIndexed=None, readonly=None, system=None, temporary=None)¶Set file attributes for a file. Note that the normal attribute means that all others are false. So setting it will clear all others.
Parameters: |
|
---|---|
Returns: | True if successful, otherwise False |
Return type: |
CLI Example:
salt '*' file.set_attributes c:\temp\a.txt normal=True
salt '*' file.set_attributes c:\temp\a.txt readonly=True hidden=True
salt.modules.win_file.
set_mode
(path, mode)¶Set the mode of a file
This just calls get_mode, which returns None because we don't use mode on Windows
Parameters: |
|
---|---|
Returns: | None |
CLI Example:
salt '*' file.set_mode /etc/passwd 0644
salt.modules.win_file.
set_perms
(path, grant_perms=None, deny_perms=None, inheritance=True)¶Set permissions for the given path
Parameters: |
|
---|---|
Returns: | True if successful, otherwise raise an error |
Return type: |
CLI Example:
# To grant the 'Users' group 'read & execute' permissions.
salt '*' file.set_perms C:\Temp\ "{'Users': {'perms': 'read_execute'}}"
# Locally using salt call
salt-call file.set_perms C:\Temp\ "{'Users': {'perms': 'read_execute', 'applies_to': 'this_folder_only'}}"
# Specify advanced attributes with a list
salt '*' file.set_perms C:\Temp\ "{'jsnuffy': {'perms': ['read_attributes', 'read_ea'], 'applies_to': 'this_folder_only'}}"
salt.modules.win_file.
stats
(path, hash_type='sha256', follow_symlinks=True)¶Return a dict containing the stats about a given file
Under Windows, gid will equal uid and group will equal user.
While a file in Windows does have a 'primary group', this rarely used attribute generally has no bearing on permissions unless intentionally configured and is only used to support Unix compatibility features (e.g. Services For Unix, NFS services).
Salt, therefore, remaps these properties to keep some kind of compatibility with Unix behavior. If the 'primary group' is required, it can be accessed in the pgroup and pgid properties.
Parameters: | |
---|---|
Returns: | A dictionary of file/directory stats |
Return type: |
CLI Example:
salt '*' file.stats /etc/passwd
salt.modules.win_file.
symlink
(src, link)¶Create a symbolic link to a file
This is only supported with Windows Vista or later and must be executed by a user with the SeCreateSymbolicLink privilege.
The behavior of this function matches the Unix equivalent, with one exception - invalid symlinks cannot be created. The source path must exist. If it doesn't, an error will be raised.
Parameters: | |
---|---|
Returns: | True if successful, otherwise False |
Return type: |
CLI Example:
salt '*' file.symlink /path/to/file /path/to/link