Tcl Windows API extension

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.

Users and Groups

SYNOPSIS

DESCRIPTION

Standard Options

User and Group Accounts

Commands

COPYRIGHT

TWAPI 2.2.3 Documentation