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

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

  Added 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: