salt.modules.win_useradd#

Module for managing Windows Users.

Important

If you feel that Salt should be using this module to manage users on a minion, and it is using a different module (or gives an error similar to 'user.info' is not available), see here.

depends:

  • pywintypes

  • win32api

  • win32con

  • win32net

  • win32netcon

  • win32profile

  • win32security

  • win32ts

  • wmi

Note

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

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

Add a user to the minion.

Parameters:

  • name (str) -- The username for the new account.

  • password (str, optional) --

    User's password in plain text.

    Default is None.

  • fullname (str, optional) --

    The user's full name.

    Default is None.

  • description (str, optional) --

    A brief description of the user account.

    Default is None.

  • groups (str, optional) --

    A list of groups to add the user to. (see chgroups)

    Default is None.

  • home (str, optional) --

    The path to the user's home directory.

    Default is None.

  • homedrive (str, optional) --

    The drive letter to assign to the home directory. Must be the Drive Letter followed by a colon. ie: U:.

    Default is None.

  • profile (str, optional) --

    An explicit path to a profile. Can be a UNC or a folder on the system. If left blank, windows uses its default profile directory.

    Default is None.

  • logonscript (str, optional) --

    Path to a login script to run when the user logs on.

    Default is None.

Returns:

True if successful, otherwise False.

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) -- The username to add to the group

  • group (str) -- The name of the group to which to add the user

Returns:

True if successful, otherwise False.

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) -- The username for which to change the full name

  • fullname (str) -- The new value for the full name

Returns:

True if successful, otherwise False.

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) -- The username for which to change groups

  • groups (str, list) -- A single group or a list of groups to assign to the user. For multiple groups this can be a comma-delimited string or a list.

  • append (bool, optional) --

    True adds the passed groups to the user's current groups. False sets the user's groups to the passed groups only.

    Default is True.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' user.chgroups jsnuffy Administrators,Users True
salt.modules.win_useradd.chhome(name, home, **kwargs)#

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) -- The name of the user whose home directory you wish to change

  • home (str) -- The new location of the home directory

Returns:

True if successful, otherwise False.

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) -- The name of the user whose profile you wish to change

  • profile (str) -- The new location of the profile

Returns:

True if successful, otherwise False.

Return type:

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, optional) -- 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 username

Return type:

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, optional) --

    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.

    Default is False.

  • force (bool, optional) --

    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.

    Default is False.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

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

Deprecated function. Please use get_user_sid instead

CLI Example:

salt '*' user.get_user_sid jsnuffy
salt.modules.win_useradd.get_user_sid(username)#

Get the Security ID for the user

Parameters:

username (str) -- The username for which to look up the SID

Returns:

The user SID

Return type:

str

CLI Example:

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

Return the list of all info for all users

Parameters:

refresh (bool, optional) --

Refresh the cached user information. Useful when used from within a state function.

Default is False.

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

  • password_changed

  • successful_logon_attempts

  • failed_logon_attempts

  • last_logon

  • account_disabled

  • account_locked

  • expiration_date

  • password_never_expires

  • disallow_change_password

  • 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) -- The username for which to list groups

Returns:

A 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 all users on Windows

Returns:

A list of all 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) -- The username to remove from the group

  • group (str) -- The name of the group from which to remove the user

Returns:

True if successful, otherwise False.

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) -- The username to change

  • new_name (str) -- The new name for the current user

Returns:

True if successful, otherwise False.

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) -- The username for which to set the password

  • password (str) -- The new password

Returns:

True if successful, otherwise False.

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, expiration_date=None, expired=None, account_disabled=None, unlock_account=None, password_never_expires=None, disallow_change_password=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 username to update.

  • password (str, optional) --

    New user password in plain text.

    Default is None.

  • fullname (str, optional) --

    The user's full name.

    Default is None.

  • description (str, optional) --

    A brief description of the user account.

    Default is None.

  • home (str, optional) --

    The path to the user's home directory.

    Default is None.

  • homedrive (str, optional) --

    The drive letter to assign to the home directory. Must be the Drive Letter followed by a colon. ie: U:.

    Default is None.

  • logonscript (str, optional) --

    The path to the logon script.

    Default is None.

  • profile (str, optional) --

    The path to the user's profile directory.

    Default is None.

  • expiration_date (date, optional) --

    The date and time when the account expires. Can be a valid date/time string. To set to never expire pass the string 'Never'.

    Default is None.

  • expired (bool, optional) --

    Pass True to expire the account. The user will be prompted to change their password at the next logon. Pass False to mark the account as 'not expired'. You can't use this to negate the expiration if the expiration was caused by the account expiring. You'll have to change the expiration_date as well.

    Default is None.

  • account_disabled (bool, optional) --

    True disables the account. False enables the account.

    Default is None.

  • unlock_account (bool, optional) --

    True unlocks a locked user account. False is ignored.

    Default is None.

  • password_never_expires (bool, optional) --

    True sets the password to never expire. False allows the password to expire.

    Default is None.

  • disallow_change_password (bool, optional) --

    True blocks the user from changing the password. False allows the user to change the password.

    Default is None.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

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