salt.modules.win_useradd

Module for managing Windows Users

depends:
  • pywintypes
  • win32api
  • win32net
  • win32netcon
  • win32profile
  • win32security
  • win32ts

Note

This currently only works with local user accounts, not domain accounts

salt.modules.win_useradd.add(name, password=None, fullname=False, description=None, groups=None, home=None, homedrive=None, profile=None, logonscript=None)

Add a user to the minion.

Parameters:
  • name (str) -- User name
  • password (str) -- User's password in plain text.
  • fullname (str) -- The user's full name.
  • description (str) -- A brief description of the user account.
  • groups (list) -- A list of groups to add the user to.
  • home (str) -- The path to the user's home directory.
  • homedrive (str) -- The drive letter to assign to the home directory. Must be the Drive Letter followed by a colon. ie: U:
  • profile (str) -- An explicit path to a profile. Can be a UNC or a folder on the system. If left blank, windows uses it's default profile directory.
  • logonscript (str) -- Path to a login script to run when the user logs on.
Returns:

True if successful. False is unsuccessful.

Return type:

bool

CLI Example:

salt '*' user.add name password
salt.modules.win_useradd.addgroup(name, group)

Add user to a group

Parameters:
  • name (str) -- user name to add to the group
  • group (str) -- name of the group to which to add the user
Returns:

True if successful. False is unsuccessful.

Return type:

bool

CLI Example:

salt '*' user.addgroup jsnuffy 'Power Users'
salt.modules.win_useradd.chfullname(name, fullname)

Change the full name of the user

Parameters:
  • name (str) -- user name for which to change the full name
  • fullname (str) -- the new value for the full name
Returns:

True if successful. False is unsuccessful.

Return type:

bool

CLI Example:

salt '*' user.chfullname user 'First Last'
salt.modules.win_useradd.chgroups(name, groups, append=True)

Change the groups this user belongs to, add append=False to make the user a member of only the specified groups

Parameters:
  • name (str) -- user name for which to change groups
  • groups (list, str) -- a single group or a list of groups to assign to the user
  • append (bool) -- True adds the passed groups to the user's current groups False sets the user's groups to the passed groups only
Returns:

True if successful. False is unsuccessful.

Return type:

bool

CLI Example:

salt '*' user.chgroups jsnuffy Administrators,Users True
salt.modules.win_useradd.chhome(name, home, persist=False)

Change the home directory of the user, pass True for persist to move files to the new home directory if the old home directory exist.

Parameters:
  • name (str) -- name of the user whose home directory you wish to change
  • home (str) -- new location of the home directory
  • persist (bool) -- True to move the contents of the existing home directory to the new location
Returns:

True if successful. False is unsuccessful.

Return type:

bool

CLI Example:

salt '*' user.chhome foo \\fileserver\home\foo True
salt.modules.win_useradd.chprofile(name, profile)

Change the profile directory of the user

Parameters:
  • name (str) -- name of the user whose profile you wish to change
  • profile (str) -- new location of the profile
Returns:

True if successful. False is unsuccessful. :rtype: bool

CLI Example:

salt '*' user.chprofile foo \\fileserver\profiles\foo
salt.modules.win_useradd.current(sam=False)

Get the username that salt-minion is running under. If salt-minion is running as a service it should return the Local System account. If salt is running from a command prompt it should return the username that started the command prompt.

New in version 2015.5.6.

Parameters:sam (bool) --

False returns just the username without any domain notation. True returns the domain with the username in the SAM format. Ie:

domain\username

Returns:Returns False if the username cannot be returned. Otherwise returns the username.
Return type:bool str

CLI Example:

salt '*' user.current
salt.modules.win_useradd.delete(name, purge=False, force=False)

Remove a user from the minion

Parameters:
  • name (str) -- The name of the user to delete
  • purge (bool) -- Boolean value indicating that the user profile should also be removed when the user account is deleted. If set to True the profile will be removed.
  • force (bool) -- Boolean value indicating that the user account should be deleted even if the user is logged in. True will log the user out and delete user.
Returns:

True if successful

Return type:

bool

CLI Example:

salt '*' user.delete name
salt.modules.win_useradd.getUserSid(username)

Get the Security ID for the user

Parameters:username (str) -- user name for which to look up the SID
Returns:Returns the user SID
Return type:str

CLI Example:

salt '*' user.getUserSid jsnuffy
salt.modules.win_useradd.getent(refresh=False)

Return the list of all info for all users

Parameters:refresh (bool) -- Refresh the cached user information. Default is False. Useful when used from within a state function.
Returns:A dictionary containing information about all users on the system
Return type:dict

CLI Example:

salt '*' user.getent
salt.modules.win_useradd.info(name)

Return user information

Parameters:name (str) -- Username for which to display information
Returns:
A dictionary containing user information
  • fullname
  • username
  • SID
  • passwd (will always return None)
  • comment (same as description, left here for backwards compatibility)
  • description
  • active
  • logonscript
  • profile
  • home
  • homedrive
  • groups
  • gid
Return type:dict

CLI Example:

salt '*' user.info jsnuffy
salt.modules.win_useradd.list_groups(name)

Return a list of groups the named user belongs to

Parameters:name (str) -- user name for which to list groups
Returns:list of groups to which the user belongs
Return type:list

CLI Example:

salt '*' user.list_groups foo
salt.modules.win_useradd.list_users()

Return a list of users on Windows

Returns:list of users on the system
Return type:list

CLI Example:

salt '*' user.list_users
salt.modules.win_useradd.removegroup(name, group)

Remove user from a group

Parameters:
  • name (str) -- user name to remove from the group
  • group (str) -- name of the group from which to remove the user
Returns:

True if successful. False is unsuccessful.

Return type:

bool

CLI Example:

salt '*' user.removegroup jsnuffy 'Power Users'
salt.modules.win_useradd.rename(name, new_name)

Change the username for a named user

Parameters:
  • name (str) -- user name to change
  • new_name (str) -- the new name for the current user
Returns:

True if successful. False is unsuccessful.

Return type:

bool

CLI Example:

salt '*' user.rename jsnuffy jshmoe
salt.modules.win_useradd.setpassword(name, password)

Set the user's password

Parameters:
  • name (str) -- user name for which to set the password
  • password (str) -- the new password
Returns:

True if successful. False is unsuccessful.

Return type:

bool

CLI Example:

salt '*' user.setpassword jsnuffy sup3rs3cr3t
salt.modules.win_useradd.update(name, password=None, fullname=None, description=None, home=None, homedrive=None, logonscript=None, profile=None)

Updates settings for the windows user. Name is the only required parameter. Settings will only be changed if the parameter is passed a value.

New in version 2015.8.0.

Parameters:
  • name (str) -- The user name to update.
  • password (str) -- New user password in plain text.
  • fullname (str) -- The user's full name.
  • description (str) -- A brief description of the user account.
  • home (str) -- The path to the user's home directory.
  • homedrive (str) -- The drive letter to assign to the home directory. Must be the Drive Letter followed by a colon. ie: U:
  • logonscript (str) -- The path to the logon script.
  • profile (str) -- The path to the user's profile directory.
Returns:

True if successful. False is unsuccessful.

Return type:

bool

CLI Example:

salt '*' user.update bob password=secret profile=C:\Users\Bob
         home=\\server\homeshare\bob homedrive=U: