Users and Groups

Commands related to user and group accounts

SYNOPSIS

package require twapi

add_account_rights ACCOUNTNAME RIGHTS ?-system SYSTEMNAME?
add_user_to_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?
add_member_to_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?
delete_global_group GROUPNAME ?-system SYSTEMNAME?
delete_local_group GROUPNAME ?-system SYSTEMNAME?
delete_user USERNAME ?-system SYSTEMNAME?
disable_user USERNAME ?-system SYSTEMNAME?
enable_user USERNAME ?-system SYSTEMNAME?
find_accounts_with_right RIGHT ?-system SYSTEMNAME? ?-name?
get_account_rights ACCOUNTNAME ?-system SYSTEMNAME?
get_global_group_info GROUPNAME ?options?
get_global_group_members GROUPNAME ?-system SYSTEMNAME?
get_global_groups ?-system SYSTEMNAME?
get_local_group_info GROUPNAME ?options?
get_local_group_members GROUPNAME ?-system SYSTEMNAME?
get_local_groups ?-system SYSTEMNAME?
get_user_account_info ACCOUNT ?-system SYSTEMNAME? ?options?
get_user_local_groups_recursive ACCOUNT ?-system SYSTEMNAME?
get_users ?-system SYSTEMNAME?
lookup_account_name name ?options?
lookup_account_sid sid ?options?
map_account_to_name ACCOUNT ?-system SYSTEMNAME?
map_account_to_sid ACCOUNT ?-system SYSTEMNAME?
new_global_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?
new_local_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?
new_user USERNAME ?options?
remove_member_from_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?
remove_account_rights ACCOUNTNAME RIGHTS ?-system SYSTEMNAME?
remove_user_from_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?
set_user_account_info account ?-system SYSTEMNAME? ?options?
set_user_comment USERNAME STRING ?-system SYSTEMNAME?
set_user_country_code USERNAME INTEGER ?-system SYSTEMNAME?
set_user_expiration USERNAME DATETIME ?-system SYSTEMNAME?
set_user_full_name USERNAME STRING ?-system SYSTEMNAME?
set_user_home_dir USERNAME PATH ?-system SYSTEMNAME?
set_user_home_dir_drive USERNAME DRIVEPATH ?-system SYSTEMNAME?
set_user_name USERNAME NEWNAME ?-system SYSTEMNAME?
set_user_password USERNAME PASSWORD ?-system SYSTEMNAME?
set_user_priv_level USERNAME PRIVLEVEL ?-system SYSTEMNAME?
set_user_profile USERNAME PATH ?-system SYSTEMNAME?
set_user_script_path USERNAME PATH ?-system SYSTEMNAME?
unlock_user USERNAME ?-system SYSTEMNAME?

DESCRIPTION

This module provides procedures related to management of user and group accounts on Windows operating systems.

Standard Options

Most commands allow the following options to be specified:

-system SYSTEMNAME Several commands, for example, looking up account names or adding users, may be carried out on a target system other than the local system. The -system option allows specification of the target system. This option defaults to the local system if unspecified.

User and Group Accounts

The command lookup_account_name, map_account_to_name, lookup_account_sid and map_account_to_sid translate between user and group account names and their SID's. The command is_valid_sid_syntax validates the syntax of an SID.

The commands get_users, get_global_groups and get_local_groups may be used to enumerate users and groups on a system.

The commands new_user and delete_user allow addition and deletion of user accounts. The commands enable_user, disable_user and unlock_user may be used to change the state of a user account. The command get_user_account_info returns various attributes and properties of a user account. These may be modified through the set_user_account_info function or alternatively, modified individually through the following set of functions: set_user_name, set_user_password, set_user_home_dir, set_user_comment, set_user_script_path, set_user_full_name, set_user_country_code, set_user_profile, set_user_home_dir_drive, set_user_priv_level, set_user_expiration.

Information about global and local groups may be retrieved through the get_global_group_info and get_local_group_info commands. New global groups may be created and deleted through the new_global_group and delete_global_group commands. The equivalent commands for local groups are new_local_group and delete_local_group. Users may be added and removed using the commands add_user_to_global_group, add_member_to_local_group, remove_user_from_global and remove_member_from_local_group. The commands get_local_group_members and get_global_group_members allow enumeration of the members of a group. get_user_local_groups_recursive returns information about the local groups in which the user account has direct or indirect membership.

The rights and privileges associated with accounts can be managed through the get_account_rights, find_accounts_with_right, add_account_rights and remove_account_rights commands.

Commands

add_account_rights ACCOUNTNAME RIGHTS ?-system SYSTEMNAME?
Adds the privileges and account rights listed in RIGHTS to the account specified by ACCOUNTNAME. The option -system may be used to specify a system as described in Standard Options.

RIGHTS is a list of privileges and account rights. Refer to Authorization constants in the Windows SDK for valid values. Note: you must use the string form of the privilege or right, for example, SeBatchLogon, not SE_BATCH_LOGON_NAME.

add_user_to_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?
Adds the user account specified by USERNAME to the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

add_member_to_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?
Adds the account specified by ACCOUNTNAME to the local group GROUPNAME. ACCOUNTNAME may be either a user name or a global group and may include a domain in the form domainname\username.

The option -system may be used to specify a system as described in Standard Options.

Example: Add a user to a local group

delete_global_group GROUPNAME ?-system SYSTEMNAME?
Deletes a global group GROUPNAME. Also, deletes any rights associated with the account in the LSA rights database. The option -system may be used to specify a system as described in Standard Options.

delete_local_group GROUPNAME ?-system SYSTEMNAME?
Deletes a local group GROUPNAME. Also, deletes any rights associated with the account in the LSA rights database. The option -system may be used to specify a system as described in Standard Options.

Example: Delete a local group

delete_user USERNAME ?-system SYSTEMNAME?
Delete the specified user account. Also, deletes any rights associated with the account in the LSA rights database. The option -system may be used to specify a system as described in Standard Options.

Example: Delete a user account

disable_user USERNAME ?-system SYSTEMNAME?
Disables a user account. The option -system may be used to specify a system as described in Standard Options.

enable_user USERNAME ?-system SYSTEMNAME?
Enables a user account. The option -system may be used to specify a system as described in Standard Options.

find_accounts_with_right RIGHT ?-system SYSTEMNAME? ?-name?
Returns a list of all accounts (user and group) that hold the right or privilege specified by RIGHT. The returned list contains the SID's of the account unless the -name option is specified in which case the account names are returned instead.

Refer to Authorization constants in the Windows SDK for valid values for RIGHT. Note: you must use the string form of the privilege or right, for example, SeBatchLogon, not SE_BATCH_LOGON_NAME.

The option -system may be used to specify a system as described in Standard Options.

get_account_rights ACCOUNTNAME ?-system SYSTEMNAME?
Returns the list of rights and privileges for the user or group specified by ACCOUNTNAME. This only includes those directly belonging to the account, and does not include the ones inherited from membership in groups.

The option -system may be used to specify a system as described in Standard Options.

get_global_group_info GROUPNAME ?options?
Retrieves information about the specified global group. The actual information returned depends on the specified options and is returned as a list of the form "option value...". The following options may be specified:

-all Returns all data items.
-comment Returns the comment associated with the group account.
-name Returns the name of the group.
-sid Returns the SID for the group.
-members Returns the members of the group.


get_global_group_members GROUPNAME ?-system SYSTEMNAME?
Returns a list of user accounts that are members of the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

get_global_groups ?-system SYSTEMNAME?
Returns the list of global groups on the system. See Standard Options for description of the -system option.

Example: List the users in a group

get_local_group_info GROUPNAME ?options?
Retrieves information about the specified local group. The actual information returned depends on the specified options and is returned as a list of the form "option value...". The following options may be specified:

-all Returns all data items.
-comment Returns the comment associated with the group account.
-name Returns the name of the group.
-sid Returns the SID for the group.
-members Returns the members of the group.


get_local_group_members GROUPNAME ?-system SYSTEMNAME?
Returns a list of user accounts that are members of the local group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

Example: List the users in a group

get_local_groups ?-system SYSTEMNAME?
Returns the list of local groups on the system. See Standard Options for description of the -system option.

get_user_account_info ACCOUNT ?-system SYSTEMNAME? ?options?
Returns attributes and properties of a user account as a list of the form "option1 value1 ...". ACCOUNT specifies the user account for which the information is to be retrieved. The option -system may be used to specify the system from whose context the account lookup should be performed.

The data returned depends on which of the following options are specified:

-all Returns all data items.
-comment Returns the comment associated with the user account.
-password_expired Returns a value of 1 if the account password has expired, and 0 otherwise.
-full_name Returns the full name of the user.
-parms Returns an application specific string.
-sid Returns the SID of the user.
-units_per_week Returns an integer indicating the number of equal time units into which a week is divided (see -logon_hours).
-primary_group_id Returns the the RID (relative id component of a SID) of the primary global group for the account.
-global_groups Returns the global groups of which the account is a member.
-local_groups Returns the local groups of which the account is a member. This includes only groups of which the account is directly a member and does not include indirect membership through a global group which is itself a member of a local group. See get_user_local_groups_recursive for a command that will recursively include groups.
-status Returns one of the values disabled, enabled or locked.
-logon_server Returns the name of the server to which logon requests are sent.
-country_code Returns an integer country/region value for the user's preferred language.
-home_dir Returns the full path to the user's home directory.
-password_age Returns the number of seconds since the password was last changed for the account.
-home_dir_drive Returns the drive letter assigned to the user's home directory.
-num_logons Returns the number of times the user has logged on. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried (using the -system option) separately. A value of -1 indicates the number is unknown.
-acct_expires Returns the time in GMT when the account is set to expire. This value may also be never or unknown.
-last_logon Returns the time in GMT when the user last logged in. This value may also be never or unknown. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).
-last_logoff Returns the time in GMT when the user last logged off. This value may also be never or unknown. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).
-user_id Returns RID component of the user's SID.
-usr_comment Returns the user comment for the account.
-bad_pw_count Returns the number of login attempts for that account that failed because of a bad password. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).
-code_page Returns an integer corresponding to the code page for the user's preferred language.
-logon_hours Returns a bit string of 1's and 0's corresponding to each hour in the week that the user is allowed to log on. Note the week starts based on GMT time, not local time.
-workstations Returns a comma-separated list of upto eight workstations from which the user can log in.
-name Returns the name of the account.
-script_path Returns the full path to the user's logon script.
-priv Returns one of the values admin, user or guest corresponding to the privilege level for the account.
-profile Returns the full path to the user's profile.
-max_storage Returns the maximum amount of disk space the user is allowed to use.


Example: List the group membership for a user

Example: Show user account settings

get_user_local_groups_recursive ACCOUNT ?-system SYSTEMNAME?
Returns the local groups in which the given user account is a member either directly or indirectly by belonging to a global group which is a member of a local group. This differs from the -local_groups option of the get_user_account_info command.

The option -system may be used to specify a system as described in Standard Options.

get_users ?-system SYSTEMNAME?
Returns the list of user accounts on the system. Note the returned list includes only accounts defined on the system, not all accounts that are known to the system. See Standard Options for description of the -system option.

Example: List the user accounts on a system

lookup_account_name name ?options?
name specifies the name of the account and may be fully qualified in the form domain\name.

If no options are specified, this command returns the SID for the account. If one or more options are specified, returns a flat list of the form "option1 value1 ...". The following options may be specified:

-all Returns all values.
-sid Returns the SID for the account.
-domain Returns the domain in which the account was found.
-system Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.
-type Returns the account type. This may be one of user, group (domain group), domain, alias (system local group), logonid, wellknowngroup, deletedaccount, invalid, unknown, or computer. The logonid type is returned for SID's that identify a logon session.


lookup_account_sid sid ?options?
Argument sid specifies the SID of the account. If no options are specified, this command returns the name for the account. If one or more options are specified, the command returns a flat list of the form "option1 value1 ...". The following options may be specified:

-all Returns all values.
-name Returns the name for the account.
-domain Returns the domain in which the account was found.
-system Specifies the name of the system on which the account is to be looked up. If unspecified, the local system is used.
-type Returns the account type. This may be one of user, group (domain group), domain, alias (system local group), wellknowngroup, deletedaccount, invalid, unknown, or computer.


map_account_to_name ACCOUNT ?-system SYSTEMNAME?
Returns the name for an account. If ACCOUNT is a valid account name, it is returned as is. Otherwise, it is assumed to be a SID and the corresponding account name is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.

map_account_to_sid ACCOUNT ?-system SYSTEMNAME?
Returns the SID corresponding to an account. If ACCOUNT is a SID, it is returned as is. Otherwise, it is assumed to be an account name and the corresponding SID is returned. An exception is raised if neither of these is true. The option -system may be used to specify a system as described in Standard Options.

new_global_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?
Creates a global group GROUPNAME. The option -comment allows a comment to be associated with the group. The option -system may be used to specify a system as described in Standard Options.

new_local_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?
Creates a local group GROUPNAME. The option -comment allows a comment to be associated with the group. The option -system may be used to specify a system as described in Standard Options.

Example: Create a local group

new_user USERNAME ?options?
Creates a new user account. The following options may be specified to set the account properties:

-system SYSTEMNAME Indicates the system on which to create the account.
-comment STRING Sets the comment associated with the account.
-home_dir PATH Sets the account's home directory path.
-script_path PATH Sets the path to the logon script for the account.
-priv PRIVLEVEL Sets the privilege level for the account. PRIVLEVEL should be one of the values admin, user or guest. If unspecified, this defaults to user.
-password STRING Sets the password for the account.


Example: Create a new user account

remove_member_from_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME?
Removes the user account or global group specified by ACCOUNTNAME from the local group GROUPNAME. ACCOUNTNAME may be a domain account in the form domainname\username.

The option -system may be used to specify a system as described in Standard Options.

Example: Remove a user from a local group

remove_account_rights ACCOUNTNAME RIGHTS ?-system SYSTEMNAME?
Removes the privileges and account rights listed in RIGHTS from the account specified by ACCOUNTNAME. The option -system may be used to specify a system as described in Standard Options.

RIGHTS is a list of privileges and account rights. Refer to Authorization constants in the Windows SDK for valid values. Note: you must use the string form of the privilege, for example, SeBatchLogon, not SE_BATCH_LOGON_NAME.

remove_user_from_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?
Removes the user account specified by USERNAME from the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

set_user_account_info account ?-system SYSTEMNAME? ?options?
Sets attributes and properties of a user account. account specifies the user account for which the information is to be retrieved. The option -system may be used to specify the system from whose context the account lookup should be performed. The following options may be specified to set various properties of the account:

-comment STRING Sets the comment associated with the account.
-full_name STRING Sets the full name of the user.
-country_code INTEGER Sets the country code associated with the user account.
-home_dir PATH Sets the account's home directory path.
-home_dir_drive Sets the account's home directory drive.
-acct_expires DATETIME Sets the time at which the account will expire. DATETIME may be specified in any format accepted by the clock scan command, or may be the string never to indicate that the account should never expire.
-name STRING Sets the name field containing the name of the account.
-script_path PATH Sets the path to the logon script for the account.
-priv PRIVLEVEL Sets the privilege level for the account. PRIVLEVEL should be one of the values admin, user or guest.
-profile PATH Sets the path to the account's profile.


set_user_comment USERNAME STRING ?-system SYSTEMNAME?
Sets the comment associated with the specified user account to STRING The option -system may be used to specify a system as described in Standard Options.

set_user_country_code USERNAME INTEGER ?-system SYSTEMNAME?
Sets the country code for the specified user account. The option -system may be used to specify a system as described in Standard Options.

set_user_expiration USERNAME DATETIME ?-system SYSTEMNAME?
Sets the time at which the specified user account expires. DATETIME may be specified in any format accepted by the clock scan command, or may be the string never to indicate that the account should never expire. The option -system may be used to specify a system as described in Standard Options.

set_user_full_name USERNAME STRING ?-system SYSTEMNAME?
Sets the full name for the specified user to STRING. The option -system may be used to specify a system as described in Standard Options.

set_user_home_dir USERNAME PATH ?-system SYSTEMNAME?
Sets the home directory for the specified user account to PATH. The option -system may be used to specify a system as described in Standard Options.

set_user_home_dir_drive USERNAME DRIVEPATH ?-system SYSTEMNAME?
Sets the home directory drive for the specified user account. The option -system may be used to specify a system as described in Standard Options.

set_user_name USERNAME NEWNAME ?-system SYSTEMNAME?
Modifies the name of the specified user account to NEWNAME. The option -system may be used to specify a system as described in Standard Options.

set_user_password USERNAME PASSWORD ?-system SYSTEMNAME?
Sets the password of the specified user account to PASSWORD. The option -system may be used to specify a system as described in Standard Options.

set_user_priv_level USERNAME PRIVLEVEL ?-system SYSTEMNAME?
Sets the privilege level of the specified user account to PRIVLEVEL. PRIVLEVEL should be one of the values admin, user or guest. The option -system may be used to specify a system as described in Standard Options.

set_user_profile USERNAME PATH ?-system SYSTEMNAME?
Sets the location of the profile of the specified user account to PATH. The option -system may be used to specify a system as described in Standard Options.

set_user_script_path USERNAME PATH ?-system SYSTEMNAME?
Sets the path to the login script for the specified user account. The option -system may be used to specify a system as described in Standard Options.

unlock_user USERNAME ?-system SYSTEMNAME?
Unlocks a user account that has been locked out. The option -system may be used to specify a system as described in Standard Options.

COPYRIGHT

Copyright © 2004-2006, Ashok P. Nadkarni