Name

vastool — The VAS command line administration utility.

Synopsis

vastool [-v] [-s] [-q] [-h [command]] [-u username] [-w password] [-k keytab] [-d level] [-e level] {command} [command arguments]

Overview

vastool is a command line program that allows you to join a Unix host to an Active Directory Domain; access and modify information about users, groups and computers in Active Directory; and configure the VAS components. vastool is located at /opt/quest/bin/vastool, and has been designed to be script-friendly, allowing administrators to automate Active Directory management from Unix/Linux workstations.

Commands

vastool is run by specifying one or more general options and then specifying a specific sub-command which may have further options and arguments. The following is a complete list of supported vastool commands and a brief description of each command's purpose.

attrs

List an Active Directory object's attributes.

auth

Authenticate a user to a service and optionally extract Kerberos authentication data.

cache

Create cache export files for use with the quickstart join option.

configure

Modify PAM, SIA, NSS, and other configuration files.

create

Create a user, group, or computer in Active Directory.

delete

Delete users, groups, computer objects, or arbitrary objects in Active Directory.

flush

Flush the vasd cache.

group

Modify, add or remove users from Active Directory groups.

info

Get information about forest, realms, sites, and servers.

inspect

Inspect configuration settings.

isvas

Check to see if a given user is an Active Directory user.

join

Join a computer to an Active Directory domain.

kinit

Request Kerberos tickets.

kdestroy

Delete tickets from a user's credential cache.

klist

List Kerberos tickets stored in a user's credentials cache.

ktutil

View and manage entries in a Kerberos keytab.

license

View currently installed licenses.

list

List users and groups in Active Directory, along with their Unix account information.

load

Import users and groups into Active Directory from a file that follows the format of /etc/passwd or /etc/group.

merge

Merge VAS users and groups into /etc/passwd and /etc/group.

nss

Perform various nss functions.

passwd

Change your password or reset another user's password in Active Directory.

schema

Detect or report the Active Directory schema extension used by VAS.

search

Perform LDAP searches against Active Directory.

service

Manage service accounts in Active Directory.

setattrs

Modify attributes of Active Directory objects.

smartcard

Smartcard information, testing, and configuration.

status

Status infomation about system and domain.

timesync

Query or synchronize system time with Active Directory Domain Controllers.

unconfigure

Remove VAS entries from PAM, SIA, NSS, and other configuration files.

unjoin

Unjoin a computer from an Active Directory domain.

unmerge

Unmerge VAS users and groups from /etc/passwd and /etc/group.

user

Manage user specific settings on Active Directory users.

vasypd

Manage settings for VAS YP features.

Naming formats

A number of vastool commands accept an argument which describes the name of an Active Directory object such as a user, group or computer object. vastool supports a number of different formats for these objects including:

Unqualified names
For users and groups these are simply the unqualified user or group name; for computer objects this includes the unqualified NETBIOS name, and the unqualified and fully qualified DNS name of the computer object. Examples: j.doe; users; foo.bar.com.
Qualified names
These names are qualified by an "@" sign and the domain that the object belongs to. Examples: j.doe@bar.com; users@bar.com; foo.bar.com@bar.com.
Distinguished Names

These names are the full LDAP Distinguished Name of the Active Directory object and are always unambiguous.

Examples:

  • cn=Jane Doe,cn=Users,dc=bar,dc=com

  • cn=foo,cn=Computer,dc=bar,dc=com

Security Identifiers (SIDs)
These identifiers are used by Active Directory to uniquely identify certain objects (such as users, groups and computers). SIDs are of the form S-1-2-3-99999.
Security Principal Names (SPNs)

These identifiers are used by Active Directory to identify services that can be contacted via Kerberos. They are of the form:

service/[host][@domain]

If host is not specified, the default host is assumed; and if domain is not specified the default domain is used. When used with vastool they can be used to indicate a specific service account or computer account to use for authentication or searching. host/ is a convenient shorthand that always refers to the local computer object.

Directory URI Syntax

The attrs, setattrs and search commands support a -U option that allows the user to specify the URI for searching Active Directory. These URIs have the following syntax:

GC://[@domain]
Specifies a Global Catalog server for a given domain/forest. If the domain is not specified, the default forest/domain is assumed.
DC://[@domain]
Specifies a Domain Controller for the given domain. If no domain is specified it will be derived from either the default domain or the searchbase being used for the LDAP search.
LDAP://[server[:port]]
describes a specific LDAP server. If no server is given then this is the same as just specifying DC://.

Common vastool Options

The following options can be passed to all vastool commands. They must be specified before the command name.

-v

Print out the vastool version and exit.

-s

This option allows you to read passwords from stdin. The following example shows how you could use vastool from another process which had already obtained a user's password. Note that putting passwords on the command line is a serious security hole. Most scripting languages provide facilities for using the stdin pipe with a child process, which is the preferred mechanism for working with the vastool -s option.

$ vastool -u jdoe -s attrs john < $jdoe.passwd
-q

Suppress output from vastool commands.

-h [command]

If no command is specified, it shows the vastool usage and a list of available commands. If a command is specified, it shows the usage for that vastool command.

-u principal

Sets the principal name to authenticate as when the vastool command needs to access Active Directory. If the caller has root access, "host/" can be specified and vastool will authenticate as the computer object that vastool is running on.

If -u is not used, then vastool will authenticate as the calling user, and will attempt to reuse Kerberos tickets from the user's credentials cache. If -u is specified, then no existing credentials cache will be used, and new tickets obtained will not be saved to disk.

This option will most commonly be used to authenticate as an Active Directory Administrator, for example when using the create, join and setattrs commands.

-w password

This option allows you pass in a password on the command line. Please note that this may be a security hole in a production environment, as it may be possible for another user to obtain the password from the argument list by examining the process record (using ps for example). If automation is required for scripts, either a keytab or the -s option should be used to read the password from a file that is protected with appropriate permissions.

-k keytab

This option allows you to specify a Kerberos 5 keytab file to use for authentication instead of a password. This is useful for automation and provisioning, in particular with Active Directory service accounts. The -w option will override this option.

-d level

This option will set the logging output level. The following types of messages are reported at the various levels:

-d 1
Errors
-d 2
Warnings
-d 3
Informational
-d 4
Debugging
-d 5
Debugging (Network)

Each level includes messages of all levels below it. The level may also be set by using the VAS_LOG_LEVEL environment variable.

By default the output will be sent to stderr. This can be changed by setting the VAS_LOG_FILE environment

-e level

This allows you to configure the verbosity of error messages displayed by vastool. Values have the following meanings.

-e 0
No error messages.
-e 1
Errors only.
-e 2
Errors and Warnings.
-e 3
All messages (Default).

Exit Status

Unless otherwise indicated, commands will exit with zero on success and a non-zero value on failure.

vastool Commands and Arguments

The following is a detailed description of all the available vastool commands. Their usage descriptions, a detailed explanation of their purpose, how they work, and examples are included for each command.

vastool attrs

vastool attrs can be used to view attributes stored on objects in Active Directory.

vastool [vastool options] attrs [attrs options] { objectname } { attribute ...}

vastool attrs options

[-b] [-c] [-d] [-g] [-s] [-u] [-U uri]

The objectname parameter will be interpreted differently according to the following options:

-d

Interprets objectname as an LDAP distinguished name. This allows you to view the attributes of any object in Active Directory.

-g

Interprets objectname as a group name.

-s

Interprets objectname as a service principal name.

-u

Interprets objectname as a user principal name.

If no flag is specified, then vastool will attempt to guess the the type of object from the name specified. If the type of object can not be derived from the name then it will be assumed that a user is specified. See the Naming Formats section for more details.

By default, the LDAP search to get the object's attributes will be performed against a standard domain controller in the domain where the object exists. If you wish to get the object's attributes from a Global Catalog instead, use the -c option. Alternatively, you can specify the URI of the Active Directory to perform the search on. See the Directory URI Syntax section for more information.

Following is an example of getting the home directory for the user john, getting the last time the computers container was modified, and getting a list of the members of the eng group.

vastool attrs john unixHomeDirectory

vastool attrs -d "CN=computers,DC=example,DC=com" whenChanged

vastool attrs -g eng member

If you are retrieving attributes that include SIDs, the -b option will automatically convert the binary SID values into human readable string SIDs. Other binary attributes will be automatically base64 encoded so that their values are usable from the command line.

For example:

$ vastool attrs administrator objectSid

objectSid: AQUAAAAAAAUVAAAABDkwL06Izx3QaSn49AEAAA==

$ vastool attrs -b administrator objectSid

objectSid: S-1-5-21-791689476-500140110-4163463632-500

vastool auth

vastool auth can be used to authenticate users against a service. Optionally, Kerberos authentication information can be extracted and displayed. When run, the command must be run as a user that has access to the service principal's corresponding keytab file.

vastool [vastool options] auth [-p] [-s] [-S service] [-k keytab] [ groups | member group ]

When vastool auth is run, the user specified as the vastool user will be authenticated against Active Directory, then a service ticket will be requested using the client user's TGT. vastool will then validate the user's service ticket using the service identity specified with the -S option using the VAS API vas_auth() function. If no service is specified, the service identity will default to the Unix host's identity (host/).

If no command is specified, vastool will then report the result of the authentication. The vastool exit code will be 0 if the authentication was successful, and non-zero if the authentication failed for any reason, with the error trace printed to stderr.

If the groups command is specified, then vastool will print out the list of Active Directory groups listed in the Kerberos service ticket PAC that the client user is a member of. The group list will be printed out in the same format as the vastool user getgroups command.

The output format for the command follows the format used by the Unix id. The group name will be printed out in a comma-separated list where each group name will be surrounded by parentheses. The group name will be shown following a <DOMAIN>\<samAccountName> format. The -s option will cause the SID of the group to be printed out before the group name. To ease parsing of the output from scripts, the -p option will print each group on its own line without commas.

If the member command is specified, then vastool will use the PAC group information to determine if the user is a member of the specified group. If the user is a member of the specified group, the vastool exit code will be 0. If the user is not a member of the specified group, then the exit code will be 1. Any other errors will have an exit code greater than 1 with the error stack printed out.

The following examples show how to check if jdoe is a member of the admins group, and how to authenticate the jdoe user to the web/ service:

# vastool -u jdoe auth member admins

$ vastool -u jdoe auth -S web/

vastool cache

vastool cache can be used to create cache export files for use with the vastool join quickstart option.

vastool [vastool options] cache {-f filename} { [-x comma-separated list of exclude tables ] [-a] [-A] export | import }

The cache command provides an export option and an import option; however, the import option is primarily for debugging purposes. The export files are ONLY designed to be used with the vastool quickstart join option. The quickstart join option allows for significantly faster joins in many environments where hundreds of machines must be joined using the same options during a VAS rollout. It is important to realize that to use a quickstart cache export file the machines must be joined in the same manner.

The vastool join quickstart option can also be useful in reducing network traffic during an inital rollout when this is important. For example, suppose you have several machines that connect to your domain controller over a saturated WAN link. The bulk of the network traffic of joining to a domain comes in the form of the inital cache load. So to avoid duplicating this network traffic for every machine you join you can instead join your first machine and then create a quickstart cache export file on this machine that can be used to load the cache information for all the other machines at this site.

The -f is the location to either save the export file, or the the path of an existing export file that you would like to import. This option is required.

The -a specifies to dump all table information in the local vas caches. There are a number of tables which are not dumped by default. These tables are generally tables that are either created at join time or they are generated from local files that may not exist on a different target system. When creating a cache export file for a quickstart join, you should NOT specify this option. This option is usually only used to assist support in diagnosing difficult problems. It essentially takes a cache snapshot of your system which can be evaluated as part of troubleshooting difficult problems. The -a does NOT include any information in the auth cache unless the -A is also specified.

The -A option will create a snapshot that includes several bits of information necessary for disconnected authentication. For example, when a machine is not able to connect to any domain controller (network or DC failure for example) the pam_vas3 module will do crypt and compare authentication against a SHA-1 password hash that was stored during a previous successful authentication attempt. If you specify the -A option, password hashes for any users which have logged into the system will be saved in the cache export file. This will result in giving these users disconnected login ability to any system which is joined using this export file even if they have never personally logged into those systems.

The -x should not normally be necessary, but it provides a way to specify a list of tables that should NOT be exported when creating a cache export file. This is a comma-separated list of table names. The exhaustive list of table names can be found in a dump generated using the -a option.

vastool configure

vastool configure can be used to modify your system's PAM, NSS, SIA, and Kerberos realm configuration. This command must be run as root.

vastool [vastool options] configure [-f file] realm { realm_name } [ server ...]

vastool [vastool options] configure [-f file] extra-realm { realm_name } { server ...}

vastool [vastool options] configure [-f file] nss

vastool [vastool options] configure [-f file] pam [ -g ] [ service ...]

vastool [vastool options] configure [-f file] pam-sc service ...

vastool [vastool options] configure [-f file] sia

vastool [vastool options] configure [-f file] vas { section } { key } { value }

vastool [vastool options] configure [-f file] vas { section } stanza { stanza-name { key1 } { value1 } { key2 } { value2 } ... { keyN } { valueN } }

NOTE: The operations performed by this command are (for the most part) performed by the vastool join command. It will not be necessary under most circumstances to run this command explicitly, with the exception of configuring smartcard authentication, or manual configuration of non-identity map data (i.e. netgroup).

vastool configure realm will modify /etc/opt/quest/vas/vas.conf to use the given realm_name as your default realm. If a list of server names is passed in, these servers will be used as the Active Directory servers for the given realm. In Active Directory terms, the realm will be the domain name of the domain this computer will be a member of. vastool configure extra-realm can also be used to configure other domains if you need to support multiple servers in your Active Directory tree. This will add information for these realms, but it will not make the new realm the default realm.

vastool configure nss will modify the passwd and group entries in the /etc/nsswitch.conf file to configure the nss_vas module as follows:

 passwd:  files vas3
 group:   files vas3

This will configure NSS to give preference to local /etc/passwd and /etc/group files over VAS when resolving identity information for users and groups. If VAS is configured to process netgroup cache information, then the netgroup entry will also be configured to use nss_vas to resolve netgroup data.

Adding vas3 to any other nss database is not supported.

If /etc/nsswitch.conf doesn't exist, vastool configure nss will create a default file with the basic entries.

It is also possible to edit /etc/nsswitch.conf manually, putting vas in front of files. This change will cause any username that has both a local account and a VAS account to be resolved to the VAS account. For more information on configuring NSS see the nss_vas(5) manual page.

vastool configure pam and vastool configure pam-sc will modify either /etc/pam.conf, or the files located in the /etc/pam.d directory to use the pam_vas3 or pam_vas_smartcard module respectively. If no service names are specified to the configure pam command, then all existing services (including the default "other" service) will be configured to use pam_vas3. The configure pam-sc command requires that you specify a service or services to be configured to use the pam_vas_smartcard module for authentication. For more information on configuring and customizing pam_vas, see pam_vas(5). The -g option has been deprecated as of VAS 3.3. The configuration behavior that was in the past specified by using the -g option is now the default PAM configuration behavior on all platforms. Specifying the -g option will have no longer have any effect upon the behavior of the configure pam command.

The following are examples of configuring the example.com realm, configuring an extra Kerberos realm with a server to use for that realm, configuring NSS to use the nss_vas module, configuring all PAM-enabled services to use the pam_vas module, and configuring the login, telnet, and ssh PAM services to use the pam_vas PAM module.

vastool configure realm example.com

vastool configure extra-realm sub.example.com server.sub.example.com

vastool configure nss

vastool configure pam

vastool configure pam login telnet sshd

vastool configure sia will modify /etc/sia/matrix.conf to use the sia_vas3 module. All existing services (authentication, session, etc.) will be configured to use siad_vas3.

vastool configure vas will modify /etc/opt/quest/vas/vas.conf to incorporate the new setting defined by the rest of the command. This is in lieu of editing /etc/opt/quest/vas/vas.conf by hand. You must have root privileges to perform this command.

The converse of this command is vastool inspect.

To add a setting to /etc/opt/quest/vas/vas.conf: vastool configure vas libdefaults forwardable true vastool configure vas vasypd stanza nismaps rpc good_rpcs netgroup netgroupjp

vastool create

vastool create can be used to create a user, group, or computer object in Active Directory. See below for common vastool create options.

vastool [vastool options] create [create options] user {name} [alternate-upn]

vastool [vastool options] create [create options] group {name} [alternate-upn]

vastool [vastool options] create [create options] computer {name} [alternate-upn]

Common vastool create Options

[-c container] [-d name] [-e] [-i info] [-g] [-i info] [-o] [-p password] [-s samAccountName] [-S] [-t groupType] [-x]

If one of user, group or computer is specified after the create command the name passed will be interpreted as being for an object of the specified type. Otherwise, vastool create will interpret the specified name, and then create different types of objects according to its format. If the name does not start with "host/", the name will be interpreted as a user name unless -g is specified, in which case it will be interpreted as a group name, and a group object will be created. Users or groups may be specified using an unqualified, qualified or distinguished name. See the Name formats section for more information.

Note that all user, group, and computer object creation can only be done in the Active Directory domain your computer is a member of.

If the name specified for the new object is not a distinguished name, then the new user, group, or computer object will be located in the appropriate default containers in Active Directory. You can create the new object anywhere in the Active Directory tree by using the -c option to specify the distinguished name (DN) of an OU or other container to create the object in.

The vastool create user/group command serves two functions. The first function creates users in Active Directory. The second (less intuitive) function Unix-enables users that already exist in Active Directory. When creating a user (or group), use -i [info] if you want to Unix-enable the user (or group). If the -i option is omitted the user will be created but will not be Unix-enabled. When using the -i the [info] string should be formatted as an entry in /etc/passwd or /etc/group.

When you want to Unix-enable an existing user (or group), use the -e option. The -i [info] is required when using the -e option. The following examples illustrate these options:

        To create a user that is Unix-enabled:
        vastool -u admin create -i "jdoe:x:1001:1000:John Doe:/home/jdoe:/bin/bash" user jdoe

        To create a user that is not Unix-enabled:
        vastool -u admin create user jdoe

        To Unix-enable a user that already exists:
        vastool -u admin create -e -i "jdoe:x:1001:1000:John Doe:/home/jdoe:/bin/bash" user jdoe
        

Note: The -e option will not create the user or group; it will only add the Unix/Linux attributes to an existing user or group. Using the -e option will override those attributes if they already exist for the user or group, so it should be used with caution. The vastool create user and vastool create group commands do not check for any potential UID or GID conflicts when using the -i option. When using the vastool create command as part of a scripted user/group provisioning process, be sure to calculate an appropriate UID or GID to use with the -i option that does not conflict with other users and groups in your Active Directory configuration.

When creating a user, you can specify the user's new password with the -p option or using stdin and the -S option. The newly created user will also be forced to change their password during their first login, unless the -x option is also specified.

The -S option allows you to read a password for the new user more securely from stdin. If you use this option, the password will not be displayed on the console by vastool create user as it usually is upon successful completion.

When creating a group, you can specify the type of Active Directory security group using the -t option. The value for the -t option must be "universal", "domain_local", or "global". By default, Global Security groups are created if -t is not used. Note that you cannot create Universal groups unless the functional level of the Active Directory forest you belong to is at least at Windows 2000 Native. Also, you cannot create distribution groups with vastool create group.

If the group you are creating requires that the samAccountName be different from the CN, use the -s option to specify the samAccountName to use. The group name supplied to vastool will be used as the group's CN.

The -d option can be used to specify the Display Name of the user being created. If -d is not used, the Display Name will default to the user name.

The vastool create computer command is used to create a computer object. If the -o option is used, then the object will just be created in Active Directory, otherwise the computer vastool is running on will be joined to the domain using the new object. If the latter approach is being used, then this command must be performed as root. Note that joining a computer to the domain is normally handled by vastool join - the create computer option is provided for advanced users. When using this command without the -o option, part of the creation process is setting the computer object's password so that vasd can authenticate to Active Directory. This key is stored in a secure file that can only be accessed by root at /etc/opt/quest/vas/host.keytab.

In both forms of the vastool create computer command, host/ can be used to select the default computer name (derived from the DNS name of the computer), or an FQDN, NETBIOS name, or a Distinguished Name may be specified for the computer object to be created.

The user you authenticate to Active Directory as must have the appropriate administrative privileges in order to create the new user, group, or computer object. Computer object creation can be delegated to other users besides Administrators. To accomplish this, the Active Directory administrator must initially create the computer object in Active Directory (for example using vastool create -o). Then, the administrator can give another user rights to reset that computer object's password. This will allow that user to reinstall VAS without the administrator. In this situation, you must use the vastool join -f command to join the computer to the domain. See vastool join for more details.

Following are two examples of user creation, two examples of group creation, and two examples of computer creation.

vastool -u admin create -c "OU=Engineering,DC=example,DC=com" user jdoe

vastool -u admin create -i "jdoe:x:1001:1000:John Doe:/home/jdoe:/bin/bash" user jdoe

vastool -u admin create group marketing

vastool -u admin create -i "marketing:x:1005:john,mary" group marketing

vastool -u admin create computer host/

vastool -u admin create -c "OU=Engineering,DC=example,DC=com" computer foo.bar.com

vastool delete

vastool delete can be used to delete users, groups, computers, and arbitrary objects in Active Directory.

vastool [vastool options] delete [-g] [-d] [user] {name...}

vastool [vastool options] delete [-g] [-d] [group] {name...}

vastool [vastool options] delete [-g] [-d] [computer] {name...}

vastool [vastool options] delete [-g] [-d] [dn] {name...}

vastool [vastool options] delete [-g] [-d] {name...}

If one of user, group or computer is specified after the delete command, or the -g or -h options are used, then the name passed will be interpreted as being for an object of the specified type. If dn is specified, or the -d option is used, then the object identified by that distinguished name (which may be of any type) is deleted. Otherwise, vastool delete will interpret the specified name, and choose an object to delete based on its format. See the vastool create command for more information on how this is done.

Following is one example of group deletion, one example of user deletion, two examples of computer deletion, and an example of deleting an arbitrary LDAP object.

vastool delete group eng

vastool delete user jsmith

vastool -u jdoe delete computer host/

vastool delete computer server.example.com

vastool delete dn "CN=Foo,DC=example,DC=com"

vastool flush

vastool flush can be used to clear the vasd cache. This command must be run as root.

vastool [vastool options] flush [-r] [-l] [-x] keytab

vastool [vastool options] flush [-r] [-l] [-x] statedir

vastool [vastool options] flush [-r] [-l] [-x] ccaches

vastool [vastool options] flush [-r] [-l] [-x] accounts

vastool [vastool options] flush [-r] [-l] [-x] auth

vastool [vastool options] flush [-r] [-l] [-x] srvinfo

vastool [vastool options] flush [-r] [-l] [-x] users

vastool [vastool options] flush [-r] [-l] [-x] groups

vastool [vastool options] flush [-r] [-l] [-x] netgroup

vastool [vastool options] flush pwdpolicies [domain list]

Flushing the accounts cache will remove all cached user, group and NIS Map information. This will force vasd to do complete lookups the next time it receives any requests from the NSS module. Flushing the auth cache will remove all cached user passwords. These are stored as SHA1 hashes in a secure file that is only accessible by root. Flushing the users cache will delete all cached user account information, flushing the groups cache will delete all cached group information, and flushing the netgroup cache will delete all cached netgroup information. Flushing the keytab will delete the VAS host keytab file. Flushing the statedir will delete all of the VAS state information. Flushing the keytab and statedir will not recreate their respective information, and should only used during uninstallation of the VAS client. Flushing the srvinfo cache will clear out the known servers and a new server will be picked for communication. Flushing ccaches will cause every ccache with a name/location matching the default_cc_name (or optionally if the renewal-patterns option has been specified in the /etc/opt/quest/vas/vas.conf, ccaches matching the renewal patterns will be affected), to either have all renewable tickets renewed or, if the cache contains no valid unexpired tickets, to be removed.

Flushing password policy cache information should not be necessary except on windows 2008 domains. In windows 2008 domains, the password policy cache should only be flushed using administrator privileges. The new fine grained password polices introduced in windows 2008 are stored in the system password settings container. The default ACLs on this container prevent non administrative users from reading the contents. This means that if a non administrative user flushes the password policy cache, only the default domain password policy will be reloaded (nothing else can be read). Password policies are loaded at join time using the credentials provided for joining.

If your machine was joined without admin priveleges or you are upgrading to VAS 3.3.2 for the first time, you will want to flush the password policies cache using administrative privileges. Any time you modify password policies you will also want to flush the password policy cache using appropriate pivileges.

VASD will attempt to update password policies every 6 hours using the host credentials, so an alternative to flushing password policies every time they change is to modify the ACLs in Active Directory to allow unix host objects the ability to the contents of the password settings container.

If your password policy information is out of date, the Domain controller will still enforce all password policies when tickets are requested. The only time the domain controller won't be able to enforce these policies is during a type of authentication where a ticket is not requested such as SSH key authentication. Additionally password policy information is used to generate password age information returned from the shadow interface. This shadow information can naturally be out of date if the password policy information is not up to date.

The users and groups cache will be regenerated after being flushed, unless the -r option is specified. When in workstation mode, the users that have previously logged in will be reloaded as well, unless -r is specified.

The netgroup cache will also be regenerated after being flushed, as long as the [vasd] netgroup-mode configuration option is set, otherwise the netgroup entries will be removed. The -r option does apply to netgroups, and if specified, the netgroup cache will not be rebuilt, regardless of whether it is configured or not.

If the -l option is specified, the caches are reloaded even if vasd isn't running.

If the -x option is specified in conjuction with the auth cache option, the password hashes from the authcache will only be removed if they are older than the configurable max password age. The max password age is 30 days by default. See the /etc/opt/quest/vas/vas.conf man page documentation for the password-cache-age [vas_auth] section for information on modifying the maximum password age.

If you do not specify an argument to vastool flush, then the accounts and auth arguments will be implied, and all user/group account information, NIS Map information, and cached passwords will be deleted.

vastool group

vastool group can be used to modify group membership lists and check group membership status for users.

vastool [vastool options] group [-s] [-f file] {group_name} add {name...}

vastool [vastool options] group [-s] [-f file] {group_name} del {name...}

vastool [vastool options] group [-s] [-f file] {group_name} hasmember {name...}

When modifying group membership, you must have the appropriate administrative privileges in Active Directory for that particular group in order for the add or del commands to succeed. Using the add option will add the listed users to the specified group. The del option will remove the specified users. Note that these changes will only appear on VAS-enabled Linux/Unix systems if the group and users used in the command have been Unix-enabled. The changes will occur in Active Directory regardless of whether or not the users and groups have been Unix-enabled.

The -s option will read the group members from stdin. Once all group members are entered use Control-D to end the input. The -f option will load the group members from the specified file.

Please note that if the specified users do not already exist in Active Directory, then those names will not be added or removed from the group membership list.

The hasmember option allows you to check the given Active Directory group to see if it contains the given users as members. A message will be printed to stdout for each user specified indicating whether or not they are a member of the specified group.

Following is an example of adding the jsmith user to the eng group, and removing the jsmith user from the eng group. Also shown is an example of checking to see if the jsmith user belongs to the admins group.

vastool group eng add jsmith

vastool group eng del jsmith

vastool group admins hasmember jsmith

vastool info

vastool info provides information about the system's Active Directory environment.

vastool [ vastool options] info acl

vastool [ vastool options] info adsecurity [-d domain] [-u user]

vastool [ vastool options] info domain

vastool [ vastool options] info domains

vastool [ vastool options] info domain-dn

vastool [ vastool options] info forest-root

vastool [ vastool options] info forest-root-dn

vastool [ vastool options] info id [-d dn] [-g group] [-s service] [-u user]

vastool [vastool options] info servers [-s site] [-d domain] [-t type]

vastool [ vastool options] info site

vastool [vastool options] info toconf {file}

The acl option displays the access control options currently enforced on the host including whether these are imposed by VGP (Native AD group policies) and lists rules by Allow or Deny and by user and group.

The adsecurity option will show all password policy information (password history, complexity, etc). By default all policies for all domains in the forest will be displayed unless -d domain is used to specify a specific domain. Additionally if you are running at a forest functional level that allows for multiple password policies per domain, you can see the resultant password policy for a specific user by using the -u username option.

It is important to realize that default Active Directory ACLs restrict reading of Windows 2008 fine grained password policies to administrative users; therefore, these policies will not be displayed unless administrative credentials are specified to execute the adsecurity command.

The domain option returns the name of the Active Directory domain to which the host machine is joined. If you were joined to example.com it would return example.com. The domain-dn option will return the domain in DN format, e.g. DC=example,DC=com.

The domains option lists all of the known domains for a given forest. The domains-dn will give you a list of the DN's for these domains in DC=x format.

The forest-root option returns the forest root of the domain to which you are joined. If you were joined to example.com, forest-root would return example.com. The forest-root-dn will return the DN of the Forest Root domain such as DC=example,DC=com.

The id option displays the Kerberos id and the object's distinguishedName in LDAP for an LDAP distinguished name, a group, service or user.

The site option returns the name of the Active Directory site to which this host belongs.

The servers option will show all of the available servers for a given domain, including which are in the Unix host's Active Directory site. You can also use -s to specify a specific a site to list servers for, -d to specify a specific domain to list servers for, or -t to specify a specific type of server (GC, DC, PDC).

The toconf option will export a list of servers for each known Active Directory domain to a file that can be used as a krb5.conf file. The [realms] section will be filled out with the known Active Directory domains with the known Domain Controllers sorted by site. This can be useful for integrating with other Kerberos applications that are not aware of the Active Directory site configuration.

Following are examples of how to use vastool info to list global catalog servers of a specific site, for user vsmith and to get a list of servers for a krb5.conf file.

vastool info servers -s London -t GC

vastool info id -u vsmith

vastool info toconf /tmp/krb5-servers

vastool inspect

vastool inspect returns the value of a configuration file setting.

vastool [ vastool options] inspect { section } { setting }

This command is oriented toward settings in /etc/opt/quest/vas/vas.conf. Argument section indicates an existing section in that file while setting indicates the name of a configuration option keyword. What is returned to the console by this command is particularly interesting for the writing of scripts.

vastool inspect libdefaults default_realm

vastool inspect libdefaults ticket_lifetime

vastool inspect libvas use-dns-srv

vastool isvas

vastool isvas can be used to check if a given user is an Active Directory user. This is very useful for scripting.

vastool [vastool options] isvas [-f] {[user] | [group]} {name}

This command will simply try to look up the given user or group in the vasd cache. If the user/group is from the local system (ie. in /etc/passwd or /etc/group), then the exit code will be 2. If the user/group is in Active Directory, then the exit code will be 0. If the user/group is not local or from Active Directory, then the exit code will be 3. If the user/group is in both Active Directory and the local files, then the exit code will be 4. If some internal error occurs, then the return code will be 1.

The -f is used to force a cache update before checking the user or group. This will ensure that any new users that were added recently will be available.

Following are examples of checking to see if the jsmith user is an Active Directory user; checking if the root user is an Active Directory user; and checking whether the eng group is in Active Directory. The first command's exit code will be 0 if jsmith is in Active Directory, and the second command will return 2 since root is a local account.

vastool isvas user jsmith

vastool isvas user root

vastool isvas group eng

vastool join

vastool join is a convenient command that performs all of the necessary steps to configure the VAS client on a computer and join it to an Active Directory domain. It sets up the /etc/opt/quest/vas/vas.conf configuration file, creates a computer object in Active Directory, and configures PAM and NSS. This command must be run as root.

vastool [vastool options] join [-c container] [-f] [-g search_path] [-l] [-U] [-G] [-I cache export filename] [-n computer_name] [-p UPM_search_path] [-r domain_list] [-u search_path] [-s siteName] [-w] [-z preflight_report_path] [--skip-config] [--preload-nested-memberships] [--site-only-usn] [--no-timesync] {domain_name} [server...]

vastool join will internally call vastool configure realm to configure the domain, vastool create to create a computer object in Active Directory for the computer, vastool configure pam to configure the PAM subsystem, vastool configure nss to configure the NSS subsystem, and vgptool apply to license VAS using any existing group policy objects. The vasd client daemon will then be started. During the client daemon's start up, the user and group caches will be flushed. When --preload-nested-memberships is specified, nested group membership information will be processed. This will incur a noticable performance hit due to the nature of the queries for this information. For more information on each of these steps, see their respective sections in this document. The --skip-config option allows you to skip the automatic system configuration of the PAM, NSS, and LAM subsystems on their respective platforms. When --skip-config is specified, vastool will not modify any non-VAS system configuration files. The administrator is then responsible for ensuring that the system configuration files are correctly modified to use the VAS components. The --site-only-usn option restricts USN updates to site-only servers. By default two in-site and two out of site servers are selected for redundency. This should be used when non-site servers are unavailable, for example blocked by a firewall.

The vastool join command must be run as root, and you must authenticate as an Active Directory user with permissions to join the computer to the domain using the -u option. During the initial join, this user name must be user's actual Kerberos principal name, which is usually samAccountName@domain, or just samAccountName if the user belongs to the same domain the machine is joining. You cannot use a user's CN or userPrincipalName (if different from the samAccountName and domain the user belongs to) to authenticate, as the necessary information to map the user's CN or userPrincipalName to the actual Kerberos principal name is not available yet. Note that Kerberos requires that all participants have their clocks synchronized. If the initial authentication to Active Directory fails due to a clock skew error, vastool join will automatically sync the system time if there is not an ntp client already running. To prevent time syncing from happening automatically in this error case, use the --no-timesync option. If --no-timesync is specified, then time syncing from both vastool and vasd will be disabled.

The -c option will allow you to specify a container where your new computer object will be created. If that is not specified, then the computer object will be created in the default computers container. The -n option allows you to specify a different name for the computer object than that which vastool would usually generate from your hostname. The computer name specified with the -n option should be either the fully qualified DNS name or the NETBIOS name for the computer object.

The -U and -G options make vasd load users and groups from the Global Catalog. All Unix-enabled users and groups in the forest will be loaded, regardless of location and domain. See the man page on /etc/opt/quest/vas/vas.conf for more information on the attributes required to be extended to the Global Catalog for these options to function correctly, and how these setting work with the other cache loading settings.

The -I option forces the join command to load users and groups from a cache export file instead of from the network. This sort of load can speed up join times significantly if you have large numbers of user or groups that must be loaded during your initial join. This option is most often useful when doing large initial deployments. To create the cache export file you should join one machine and run the vastool cache export command. The machine from which the cache is exported should be joined using the same options as the target machine. The only exception being that the site of the target machine may be different than the target of the source machine.

Following the options, you must specify your Active Directory domain, which will act as your Kerberos realm. The servers for this domain will be automatically detected through DNS and LDAP lookups. Alternatively, you may specify the servers to use, by listing them after the Active Directory domain. These servers will be preferred over the ones that vastool automatically detects.

If a computer object already exists in the directory for the computer name you are trying to use, an error will be reported. To override the existing computer object, use the -f option. In this case, the computer object's authentication key will be reset. Any other systems authenticating as that computer object will no longer be able to authenticate after the authentication key is reset. For this reason you should exercise care to ensure that the computer object you are overriding is not currently in use.

The vastool join -f command allows users to to perform delegated joins using pre-existing Active Directory computer objects. This is done by an Administrator creating the computer object using either the -o to vastool create computer or the Active Directory Users and Computers snap-in for the MMC console. The Administrator can then delegate join permissions to a specific user using Active Directory Users and Computers. The only permission that is strictly required is the Reset Password permission, however it strongly recommended that the Validated write to DNS host name and Validated write to service principal name permissions be granted. Further extending permissions to All Validated Writes or Write All Properties will enable additional functionality such as setting the userPrincipalName, operatingSystem and operatingSystemVersion properties of the computer object. Alternatively, these properties may be set by an Administrator using the vastool setattrs command.

Furthermore, it is possible to use the default password on a computer object to allow it to "join itself" without granting additional permissions. To do this the Administrator should create the computer object and then perform the Reset Account action. This will set the default password of the computer object to the lowercase form of the NETBIOS/SAM Account Name (without the trailing $). This can be used to perform a delegated join in the following way:

vastool -u host/myhostname.example.com -w myhostname join -f example.com

However, this approach is not generally recommended as it creates a window of opportunity for an attacker to join an illegitimate computer to the domain using this object.

At join time vastool searches Active Directory for Unix-enabled users and groups from the base of the domain you are joined. The results of this search are then cached locally and used as a persistent cache of user and group information to limit the amount of necessary LDAP network traffic for normal system operation. If you want a different set or subset of users/groups loaded into the local cache, you can specify a search path to vastool on the join command line. Specifying the -u option forces VAS to load users from a given search path. Specifying the -g option will have the same effect for groups. These search paths must specify a container object somewhere within your Active Directory forest. Any applicable objects beneath the specified container (or any of its sub containers) will then be discovered and cached. Some examples of valid search paths include

CN=users,DC=Example,DC=com

OU=groups,DC=Example,DC=com

OU=somecontainer,DC=Example,DC=com

DC=Example,DC=Com

This last example would be the default search path if you were joining the example.com domain.

You can instruct vastool to search for users and groups in Unix Personality Management (UPM) mode at join time by specifying the primary UPM search path using the -p on the join command line. UPM mode restricts users and groups to the search-path given. It also recognizes Unix user and group personalities as valid user and group objects. The -p supersedes the -u and -g settings. If the supplied UPM search path doesn't exist, the join command will fail. For more information on UPM see uptool(1).

VAS also provides a "workstation-mode" (-w) where the user/group information is loaded into the cache when a specific named request for that user/group occurs.

vastool also supports a -r option. If you are configuring your host to allow cross domain login using only the simple name, you must specify a domain search order for resolving simple names. This can be specified at join time using the -r join option. This option expects a comma-separated list of domains for resolving simple names. The default domain (the domain the host is joined to) MUST be included in this list. For more information about cross domain login with simple name see the VAS Administration Guide.

If VGP (Vintela Group Policy) is installed on the host, vastool will use vgptool to apply all configured Group Policy settings after the join is successful. This may include automatic licensing of VAS. You can disable this behavior by using the -l option, which also prevents the VGP daemon from being loaded. For more information about using VGP with VAS, see the VAS Solutions Guide.

A host's site information is determined by its subnet membership and is configured in Active Directory. This information is discovered at join time. The site configuration of a host is extremely important, especially in large environments. The site a machine is a member of determines the domain controllers it will communicate with on a regular basis. If there is no subnet configured in Active Directory or the subnet configuration in Active Directory is not ideal, authentication operations may take much longer than necessary. Replication issues might also be seen. In situations like this the ideal solution would be to fine tune the subnet configuration in Active Directory. In the event that this cannot be immediately done, you can manually specify the site a machine should be a member of using the -s option to join.

The -z preflight_report_pathname is used from scripts based on or using vastool join. It causes vastool join to look for and consume information left in a report by the preflight utility. If the path to the report is "default", vastool will look for the report on the default path and name which is /tmp/vas-preflight.xml. Note to script writers: this can serve to automate a vastool join operation greatly, however, it cannot obviate interaction arising during authentication. Note also that any vastool or vastool join options and arguments also passed will override anything preflight has to say.

The following is an example of vastool join using all of the defaults; vastool join with a name other than its hostname into a non default container in an environment where DNS is not properly configured; and vastool join -f to perform a delegated join.

vastool -u admin join example.com

vastool -u admin join -c "OU=Testlab,DC=example,DC=com" -n test_server example.com

vastool -u admin join -f example.com

vastool kinit

vastool kinit can be used to obtain Kerberos tickets.

vastool [vastool options] kinit [-R] [-S service_principal] [client_principal]

If no arguments are specified, then the Kerberos TGT is obtained for the currently logged in user if it is not in the user's ticket cache. The client principal to use for authentication may also be specified after the vastool kinit options, or by using the vastool -u option. You cannot specify the client principal using both the -u and the last argument. If using the client_principal argument, the retrieved TGT will be stored in the current user's credential cache. If -u is used then the credential will not be cached, and this usage is useful for authenticating a user without having to store a ticket on the file system.

If the -S option is specified, then a service ticket will be retrieved on behalf of the client for the specified service. As for retrieving a TGT the client can be specified via an additional argument or by using the -u option. If neither of these are specified, the current user is used. The semantics for caching of the service ticket are also similar; the ticket is cached unless the -u is used. The user will be prompted for a password if a service ticket is requested for a client which has not previously retrieved a TGT with kinit.

The vastool -u client kinit command can be used to debug problems with Kerberos authentication. For example, to test if the computer vastool is running on is joined to the domain properly, you may run as root:

vastool -u host/ kinit

Using the vastool -s option, you can use the vastool kinit command as an authentication API from scripts and other programs which do not use PAM or the VAS API. This can be done by running:

vastool -u jdoe -s kinit

and then writing jdoe's password to stdin of the vastool process. The exit code of the vastool process will be 0 on a successful authentication, and non-zero if authentication failed.

The -R option renews all the TGTs in the cache, and then retrieves new service tickets for these updated TGTs. For TGTs to be successfully renewed they must not be expired, they must have been requested as "renewable" tickets, and the renew lifetime must not have elapsed. You can configure VAS to request renewable TGTs by setting the renew_lifetime option in the libdefaults section of /etc/opt/quest/vas/vas.conf.

vastool kdestroy

vastool kdestroy will destroy all of the tickets that are in the calling user's Kerberos ticket cache.

vastool [vastool options] kdestroy

A user's Kerberos ticket cache is a file owned by the user with permissions of 0600 that will be either at $HOME/.krb5cc or in /tmp/krb5cc_{user's UID}. Normally, the user's Kerberos TGT is stored there along with any other tickets that have been obtained. These tickets can all be cleared with vastool kdestroy.

vastool klist

vastool klist can be used to list all of the tickets currently in a Kerberos ticket cache.

vastool klist [-v] [-c cache]

If the -c option is not specified, then the tickets in the user's ticket cache are printed to stdout. Otherwise the ticket cache specified with the -c option will be used. They will show the name of the service each ticket is for, the time the ticket was issued, and the time the ticket will expire. The ticket cache will be stored as a file owned by the user with permissions of 0600 at $HOME/.krb5cc or in /tmp/krb5cc_{user's UID}.

The -v will list details for each ticket.

The following examples show the output of klist with and without the -v flag:

 $ vastool klist
 Credentials cache: FILE:/tmp/krb5cc_1000
         Principal: jdoe@EXAMPLE.COM

   Issued           Expires          Principal
 Dec 15 23:50:47  Dec 16 09:50:34  krbtgt/EXAMPLE.COM@EXAMPLE.COM
 Dec 15 23:50:59  Dec 16 09:50:34  ldap/win2k3.example.com@EXAMPLE.COM

 $ vastool klist -v
 Credentials cache: FILE:/tmp/krb5cc_1000
         Principal: jdoe@EXAMPLE.COM
     Cache version: 4

 Server: krbtgt/EXAMPLE.COM@EXAMPLE.COM
 Ticket etype: arcfour-hmac-md5, kvno 2
 Auth time:  Dec 15 23:50:47 2005
 End time:   Dec 16 09:50:34 2005
 Renew till: Dec 16 00:07:14 2005
 Ticket flags: renewable, initial, pre-authenticated
 Addresses: IPv4:192.168.27.142, IPv4:192.168.0.12

 Server: ldap/win2k3.example.com@EXAMPLE.COM
 Ticket etype: arcfour-hmac-md5, kvno 2
 Auth time:  Dec 15 23:50:47 2005
 Start time: Dec 15 23:50:59 2005
 End time:   Dec 16 09:50:34 2005
 Ticket flags: pre-authenticated
 Addresses: IPv4:192.168.27.142, IPv4:192.168.0.12

vastool ktutil

vastool ktutil can be used to list, alias, or remove keys in a Kerberos keytab file.

vastool ktutil [-k keytab] [-v] alias principal alias

vastool ktutil [-k keytab] [-v] list --keys --timestamp

vastool ktutil [-k keytab] [-v] remove [-p principal] | [-V kvno] | [-e enc_type]

The -v option will show more verbose information depending on the option specified. If the -k is not specified, then the default keytab will be used.

vastool ktutil alias creates an alias of the specified principal key. This is helpful for samba integration where you need to use the same key with more than one principal name.

vastool ktutil list will print information about the current keys in the keytab to stdout. The --keys option will print the keys next to each keytab entry. --timestamp prints out the date of when the key was created.

vastool ktutil remove will remove a key from the keytab. You must either use -p to specify the principal, -V for the kvno, or -e for the encryption type when removing a key.

vastool license

vastool license will display information about installed license keys and will display the total number of users in use and users that have been licensed.

vastool [vastool options] license [-q] [-i] [-s]

vastool license -q can be used to look up the installed license information. It will report how many users the installed license is valid for and how many users are currently in use.

vastool license -i will print out detailed information about each installed license key.

vastool license -s reports if the version of VAS is a site based license.

vastool list

vastool list can be used to list the users and groups that are stored in Active Directory. See below for common vastool list options.

vastool [vastool options] list [list options] users

vastool [vastool options] list [list options] users-allowed

vastool [vastool options] list [list options] users-denied

vastool [vastool options] list [list options] user {username}

vastool [vastool options] list [list options] groups

vastool [vastool options] list [list options] group {groupname}

Common vastool list Options

[-a] [-c] [-f] [-l] [-n] [-p] [-s] [-t]

By default, vastool list will not directly use LDAP, but will use vasd to lookup the group and user accounts. This allows vastool list to take advantage of vasd's information cache.The -l option will force vastool list to use LDAP directly and bypass the vasd cache.

The -a option will list all the users or groups in Active Directory, not just the Unix-enabled ones. This does not automatically enable the -loption. When -a is used, the non Unix-enabled users and groups will have empty fields in the Unix information lines. Non Unix-enabled groups are only cached when users log in, so when running vastool list -a groups the output will sometimes not correspond directly with the contents of Active Directory. Only those groups that were updated and cached as a result of a user login event will be available. All groups will be available when doing a direct listing over LDAP.

The -f option will force vasd to update its cache immediately, without respecting the vasd update-interval setting. The -c will force data to be read from the cache without respecting the vasd update-interval setting. (See the vasd man page for more information about update-interval.

The -c option will cause the list to read only from the cache. No IPC that would cause the cache to be updated will be sent. All information returned will be as the data currently resides in the cache.

The -n option will print the userAccountControl when doing a user list.

The -o option will use override information when performing the command.

The -p option will print the primaryGroupID when doing a user list.

The -s option will print the objectSid when doing a group list.

The -t option will print the primaryGroupToken when doing a user list.

vastool list user and vastool list group will only list information about the Unix user/group specified.

vastool list users-allowed and vastool list users-denied will list users that are denied or allowed access to the Unix host according to the rules found in users.allow and users.deny. The -l can not be used with the vastool list users-allowed or vastool list users-denied commands. See the pam_vas man page for information on users.allow and users.deny.

The following examples list all Unix-enabled groups, list all Unix-enabled users, list all Unix-enabled users (bypassing cache), list only users that are allowed to log in.

vastool list groups

vastool list users

vastool list -l users

vastool list users-allowed

vastool load

vastool load can be used to import existing users and groups. See below for vastool load options.

vastool [vastool options] load [load options] users

vastool [vastool options] load [load options] groups

vastool load Options

[-f file] [-c container] [-p password] [-s samaccpre] [-t grouptype] [-l] [-x] [-e] [-r]

vastool load will read from a file if the -f option is specified, otherwise it will read from stdin. The input must follow the format of /etc/passwd if loading users. If loading groups the input must be formatted like /etc/group. You can load the users or groups into any Active Directory container using the -c option. Otherwise, they will be created in the default users container. Control-D will finish the input.

Please note that existing passwords cannot be imported into Active Directory. If -p is used to specify a password when loading users, all of the new users will have their passwords set to the specified password. Otherwise, a random password made up of alphanumeric characters will be generated for each user. These generated passwords will be stored in a file the administrator can use to notify the new user's what their password is. Unless the -x option was specified, the newly created users will be forced to change their password during their first login. Passwords cannot be set for groups, and the -p option is ignored when loading groups.

Any errors will be logged to stderr unless the -l option is used; then errors will be logged to a file whose location will be printed out. It is very important to ensure that the UIDs and GIDs specified for the users and groups being imported do not conflict with existing users and groups already in Active Directory. The import process does not check for conflicts before creating the new users and groups.

When importing groups that have members, those members need to be created first. For example, for the following group entry: group1:x:1400:user1,user2,user3, you should first import user1, user2, and user3. Otherwise, when the group object is created in Active Directory none of the members will be stored in the group. This is due to the fact that group membership lists in Active Directory are stored as lists of distinguished names, and those DNs cannot be looked up if the group members do not already exist.

Once the load is complete, the vasd user or group cache will automatically be updated to get the newly create users or groups. This can be disabled with the -r option.

There may be situations where you already have Active Directory accounts for the Unix/Linux users and groups you are importing. In this situation you will want to use the -e option. This will cause vastool to set the Unix/Linux attributes for existing users and groups that are being imported. Note that this will not create users or groups; they must already exist in Active Directory. An error will be reported for each user or group that is in the list being imported that does not already have an account in Active Directory. User passwords are not reset when using the -e option.

The following is an example of importing a file of users into a specific Active Directory container, and setting all of their default passwords to "change.me".

vastool load -f /tmp/newusers.txt -p change.me -c OU=eng,DC=example,DC=com users

Note that after migrating Unix users and groups into Active Directory, you will need to remove those user accounts from the local /etc/passwd and /etc/shadow files, and remove the group accounts from /etc/group on every Unix machine where they were previously.

vastool merge

vastool merge

vastool [vastool options] merge [-h] users

vastool [vastool options] merge [-h] user {username}

vastool [vastool options] merge [-h] groups

vastool [vastool options] merge [-h] group {groupname}

vastool merge can be used to merge Active Directory users and groups into the local /etc/passwd and /etc/group files. This should usually only be done on systems that do not support NSS and PAM, but is available on all platforms. This command must be run as root.

vastool merge users will merge Active Directory user accounts into /etc/passwd. vastool merge user will merge only the given user into /etc/passwd. vastool merge groups will merge Active Directory groups into /etc/group. If no option is specified to vastool merge, then both Active Directory users and groups will be merged into /etc/passwd and /etc/group respectively.

vastool merge will ask vasd to update the vasd passwd cache or the vasd group cache, then merge the Active Directory users or groups into the existing passwd and group files. Merging will not occur if the vasd cache has not been updated since the last merge; this is determined by comparing the timestamps between the local account files and the vasd cache files. To force the merge to occur, use the -f option.

The -h option will change the merge behavior so that only users who have host access will be merged. This will check the settings in the VAS users.allow and users.deny file, and only users who are denied access will not be merged. The -h applies to both vastool merge users and vastool merge user.

Account merging is not necessary for operating systems that support PAM and NSS. This functionality is provided to allow for account synchronization on platforms that do not allow you to use NSS and PAM. Also, account merging is done automatically by the VAS login utility when users attempt to log in; in this case you will not need to run vastool merge manually.

It is not possible to synchronize users' passwords using vastool merge. Only their user account information will be stored in /etc/passwd. For this reason, you must use the applications bundled with the VAS client software to allow the Active Directory users access to the operating system where PAM is not supported.

Following are examples of merging the Active Directory user accounts, and of merging the Active Directory groups.

vastool merge users

vastool merge user bsmith

vastool merge groups

vastool passwd

vastool passwd can be used to change your password, or to reset another user's password if you have enough administrative privileges.

vastool [vastool options] passwd [-k filename] [-x] [-r] [-o] [-c] [-e] [user_name]

On some platforms, such as some Linux distributions and Solaris 8/9, the system passwd change utility does not work correctly when the vas NSS module is listed in /etc/nsswitch.conf. VAS users will not be able to change their passwords using the system passwd command. vastool passwd can be used by VAS users as a workaround.

If no user name is specified, then the calling user's (or the user specified with the -u vastool option) password will be changed. If a user name is specified on the command line after the vastool passwd command, then vastool passwd will attempt to set the specified user's password. To set (or reset) passwords you must have administrative rights. vastool passwd changes passwords in Active Directory using the Kerberos change password protocol.

Note that these two modes of password changing are fundamentally different. When changing a password, you must authenticate as the user whose password is being changed. When setting another user's password, you must authenticate as an administrative user that has privileges to reset that user's password. Changing passwords requires knowledge of the user's current password; setting passwords does not.

The following is an example of the calling user changing their own password:

$ vastool passwd

The following is an example of the calling user changing the bsmith user's password (Note that the calling user must know bsmith's current password):

$ vastool -u bsmith passwd

The -x option is used to indicate that the user must change their password at their next login. When -x is specified, vastool will modify the user's userAccountControl attribute after modifying the password to notify Active Directory that the user must change their password before their next authentication.

The -k option can be used to change the password of a service account created with vastool service create and update the associated keytab. You must specify the full path to the service account's keytab as the filename.

The -r option will set the password to a random value. Note that if vastool cannot derive a keytab for the target principal, it will exit out to prevent user's from accidentally setting their passwords to unknown random values. You should use the -r option when modifying the password for computer objects or service accounts for security reasons. For example, you can reset the computer object's password with the following:

# vastool -u admin passwd -r host/

The -o option will output the new password to stdout. Use of the -o option is useful when used with -r to allow the caller to see the random password value.

The -c option allows you to set a user's cached password. This is useful for scenarios when a machine is operating in disconnected mode, and a user inadvertently locks themselves out due to the default password policy that VAS uses when in disconnected mode. Administrators can temporarily enable access for that user until VAS reenters connected mode. vastool will not ask for any authentication information when using -c since Active Directory will not be contacted. No other options (-r, -k, and -x) are valid when -c is used. Administrators can reset a user's cached password by running the following command with root access:

# vastool passwd -c jdoe

The -e option forces creation of DES keys in the keytab. This useful for older (server-side) applications that use a legacy Kerberos implementation that do not support RC4 encryption. The following examples show how the "administrator" user would generate DES keys in the host.keytab when setting the password for the computer account.

# vastool -u administrator passwd -e -r host/

The following example shows the calling user resetting the bsmith user's password. Note that the calling user does not need to know bsmith's password, but must authenticate as the calling user's identity, and must have administrative rights to set bsmith's password.

$ vastool passwd bsmith

It is possible to use vastool passwd in a non-interactive mode by using the -s vastool option. This will cause all password prompts to be satisfied by reading from stdin. This allows web applications, scripts, and other applications to use vastool passwd for users. The application must get the necessary information from the user and then supply that information to the stdin of the vastool passwd command. If changing a user's password this should be the old password, and the new password entered twice; if setting a user's password then the input is simply the new password repeated twice. Each input should be separated by a newline.

The following example shows the correct options to change the bsmith user's password and supply the necessary information to the stdin of the process.

 $ vastool -u bsmith -s passwd <<EOF
 myoldpassword
 mynewpassword
 mynewpassword
 EOF

The process should then write bsmith's current password, the new password, and the new password again to the stdin of the command.

One important note is that when using the pam_vas PAM module with disconnected authentication enabled, then vastool passwd will not be able to sync up the user credential cache with the new password for the user since it will not have root access on the system. On systems where the passwd utility correctly works, the user's changed password will be synced up correctly in the user credential cache.

vastool schema

vastool schema can be used to detect if there are any schema extensions in Active Directory that support the storage of Unix account information, cache detected schema information, and show the schema configuration that VAS is using.

vastool [vastool options] schema [-h hostname] {list | detect | cache}

vastool schema detect will detect the preferred Active Directory schema. The currently supported schema extensions are the Windows 2003 R2 extensions, VAS/RFC2307 extensions, as well as the SFU 3.0 extensions. The schema extensions are preferred in the above order. You can manually configure what domain controller to search for schema information using the -h to provide a hostname of a domain controller to search.

vastool schema list will list the schema extensions currently being used by VAS

vastool schema cache will detect the preferred schema extension available in Active Directory, as per schema detect, and will then cache this list locally for use.

If you wish to configure a schema extension manually that VAS should use, see the vasd man page for information on configuring which attributes to use in /etc/opt/quest/vas/vas.conf.

vastool search

vastool search can be used to perform secure LDAP searches against Active Directory using raw LDAP search filters while requesting any set of attributes.

vastool [vastool options] search [-a] [-b base] [-h hostname] [-p port] [-q] [-s scope] [-U uri] {filter} [attribute...]

You can perform an anonymous LDAP search by using the -a option. Note that anonymous binds for searching Active Directory may be disabled by the Active Directory administrators for security reasons. In this case, the -a option will cause all the search to fail. Also, when using anonymous searches all data returned by the search will not be encrypted. This option should be used only when doing searches for public information.

You can specify the search base for the LDAP search with option -b. If no base is specified and no URI syntax is used, then the joined domain is followed. If a URI is specified, but no @domain portion is present, then for a URI beginning with DC:// or GC://, the default realm is used. If beginning with LDAP://, the realm of the authenticating principal is used instead.

The LDAP search scope can be modified with the -s option. You can specify either base (returns whether the object exists), one (returns the attributes of an object), or sub (searches a subtree) as the scope. The default scope is sub. Note that when searching against a Global Catalog, you can search the entire forest by setting the search base to "", otherwise the default search base of the domain you are joined to will be used.

You can specify the server to search against either by specifying the directory uri with the -U option, or by using the -h and -p to specify the host and port of the server to use for searching. When searching against a global catalog be sure to set the search port to 3268, as that is the standard Global Catalog port.

You must supply an LDAP search filter that specifies what kind of search to perform, and an optional list of attributes to return. If no attributes are specified or the wildcard "*" is given, all the attributes of the matching objects are returned. A detailed description of LDAP search filter syntax is beyond the scope of this document. For more information see RFC2254.

By default, the output of the search will go to stdout and will consist of a line for the object's DN, followed by a line with each attribute requested. Each line will begin with the attribute's name. If more than one object matches the LDAP search, then each set of results will be separated by an empty line. You can modify this output with the -q option, which will skip the printing out of the attribute names, and the sets of results will not be separated by empty lines. This is very useful when generating lists of DNs to use with vastool setattrs.

The following example will search for all computer objects and print out the DN and hostname of each one.

vastool search "(objectCategory=computer)" dnsHostName/

The following example will list the DNs of all users who have their Unix accounts disabled.

vastool search -q "(loginShell=/bin/false)"/

vastool service

vastool service can be used to create and delete service accounts in Active Directory. An Active Directory service account is a user account which is intended to be used by services running on Unix hosts. When a service account is created, a random password is generated for the account and a Kerberos keytab is created for the service.

vastool [vastool options] service create [-c container] [-k keytab] {name} [spn...]

vastool [vastool options] service delete [-k keytab] {name}

vastool [vastool options] service list {name}

Each service account has a User Principal Name (UPN), and an optional set of Service Principal Names (SPNs). The UPN is typically named service/host@domain, where service matches the type of service running - for example, http/ or ftp/. The keytab file created for the service will be named service.keytab and will be created in the VAS configuration directory at /etc/opt/quest/vas. The default permissions on the keytab file will be 0600 and the file will be owned by root. You should update the ownership of the file so that the corresponding service has the rights to read from the keytab file.

To create a service account, you must run vastool service create name as root, where name is the service account name. By default, the service account will be created in the default computers container. You can override this location by using the -c option to specify an alternate OU to create the service account in. If you specify service/ as the principal name, then the hostname of the machine vastool is being run on will be used to build a complete service principal name. You must supply the username and password of an Active Directory user that has permissions to create users. You can add an optional list of other servicePrincipalName's to the account. Note that these servicePrincipalName's define aliases for the ticket name that can be requested for the service, but they cannot be used as a client name to authenticate as the service itself.

An example of creating a service account for an SQL server is:

vastool -u admin service create sql/

To delete a service account, run vastool service delete name. The account in Active Directory will be deleted, and the keytab file for the service will be deleted. For example, to delete the sql service account, run:

vastool -u admin service delete sql/

You can list the service principals associated with a Service account with vastool service list service. To list the principals associated with the sql service account, do the following:

vastool -u admin service list sql/

vastool setattrs

vastool setattrs allows you to modify the attributes of Active Directory objects, users, and groups directly. You can clear attributes, set multi-valued attributes, and set single-valued attributes. Set below for vastool setattrs options.

vastool [vastool options] setattrs [setattrs options] { arguments ...}

vastool setattrs Options

[-g] [-d] [-s] [-u] [-f] [-m] [-r] [-i] [-U uri]

The first four options deal with how the object name is interpreted. The -s option will interpret the object name as a service principal name, or a user principal name. The -g will interpret the object name as a group name. The -d will interpret the object name as a distinguished name (DN). The -u will interpret the object name as a user name. Finally, the -f will interpret the object name as a filename, that contains one DN per line. In this case, the specified command will be run against every DN in the file.

The arguments list takes on a different format depending on the -m, -r, and -i options. These options are exclusive, and cannot be used simultaneously. When using -m to modify multi-valued attributes, the attribute list will take the form of {attribute} [value]..., where the first value is the attribute name and the following arguments are values for that attribute. You can only modify one attribute at a time when using -m.

When using -r to remove attributes from an LDAP object, the argument list will take the form of {attribute}..., where it is a list of attribute names to remove. The removal operation is done with one LDAP modify call, so if any of the attribute removals fail, the entire operation fails.

If neither -r or -m is specified, then the attributes specified will be treated as single-valued attributes. The argument list will take the form of [{attribute} {value}]..., unless the -i option is specified. In this case, the attribute value will be read from stdin, and only the first attribute in the arguments list will be handled. This allows you to set string attributes with multi line values, like the vintela-nisMapData attribute for the VAS NIS components.

The following is an example of setting a user's servicePrincipalName, removing the membership list of a group, and setting the contents of a VAS NIS Map object from an external file:

vastool setattrs jdoe servicePrincipalname vas/jdoe

vastool setattrs -r -g testGroup member

vastool setattrs -i -d "cn=hosts,ou=vas,dc=example,dc=com" vintela-nisMapFormat < /nisdata/hosts

vastool smartcard

vastool smartcard can be used for configuring, inspecting, and testing smartcard integration with VAS. Note that many vastool smartcard operations will not be available unless the VAS smartcard plugin has been installed.

vastool [vastool options] smartcard [-l library] [-s slot] [-p PIN] [-u UPN] {info | test | pin | configure | unconfigure | trusted-certs }

The vastool smartcard can obtain certain information from the VAS configuration file, which is typically found at /etc/opt/quest/vas/vas.conf.

The configuration file is divided into sections, with each section containing a number of attributes.

In the [pkcs11] section, the following attributes may be read:

1. pkcs11-lib: the value of this attribute specifies the location of the PKCS#11 library which vassmartcard shall use in its operation.

This may be overridden by using the -l to specify the location of an alternate PKCS#11 library. Note that some vastool smartcard commands shall also allow the PKCS#11 library to be specified as an argument.

If the -l option is not specified, or the PKCS#11 library is not supplied as an argument, the VAS configuration file must exist and the pkcs11-lib attribute MUST be present.

2. pkcs11-slot: the value of this attribute specifies the ID of the slot to be used. A PKCS#11 slot typically represents a physical reader attached to the device. A slot ID is an integer value.

The value to be used depends on the underlying PKCS#11 library. Some PKCS#11 libraries shall specify the first reader with a slot ID of 0, while other PKCS#11 libraries shall specify the first reader with a slot ID of 1.

Specifying the slot ID is optional. If the pkcs11-slot attribute is not present in the configuration, then vastool smartcard shall use first available slot. In general, a slot ID should not be specified unless there are multiple readers attached and a specific reader is required.

The pkcs11-slot attribute may be overridden using the -s option. Note that some vastool smartcard commands shall also allow the slot ID to be specified as an argument.

If a smartcard operation requires a PIN, a prompt shall be emitted to the standard output requesting a PIN, and the PIN value shall be read from the standard input. The -p option may be used to specify the PIN on the command line explicitly so that prompting is not required.

The following smartcard commands are available, and are explained in greater detail in the following sections:

- vastool smartcard info may be used to obtain information about the VAS smartcard environment.

- vastool smartcard test may be used to test the VAS smartcard environment.

- vastool smartcard configure may be used to configure the VAS smartcard environment.

- vastool smartcard unconfigure may be used to unconfigure (or restore) the VAS smartcard environment.

- vastool smartcard trusted-certs may be used to manage the trusted certificate store used for verifying smartcard logins.

vastool smartcard info

vastool smartcard info can be used to obtain information about the smartcard environment. It allows for inspection of the VAS smartcard configuration, of a PKCS#11 library and slots, of the smartcard itself, and the user information on a smartcard.

vastool [vastool options]
smartcard [smartcard options]
info { config | library [path] | slot [num] | slots | card | user [UPN] | users | all }

vastool smartcard info config will display information about the current PKCS#11 settings in the VAS configuration file.

vastool smartcard info library will display information about the configured PKCS#11 library. Information about a different PKCS#11 library may be obtained by specifying the path on the command line (via the path argument or via the -l option).

Example: display information about the configured PKCS#11 library

vastool smartcard info library

The following example demonstrates how to examine the configured PKCS#11 library:

vastool smartcard info library

The following example demonstrates how to examine a specific PKCS#11 library:

vastool smartcard info library /opt/quest/lib/libvaspkcs11impl.so

vastool smartcard info slot will display information about the configured PKCS#11 slot. Information about a different PKCS#11 slot may be displayed by specifying the slot ID on the command line (via the num argument or via the -s option).

The following example demonstrates how to examine the configured PKCS#11 slot:

vastool smartcard info slot

The following example demonstrates how to examine a specific PKCS#11 slot:

vastool smartcard info slot 2

vastool smartcard info slots will display information about all known slots.

vastool smartcard info card will display information about a smartcard inserted in a PKCS#11 slot.

vastool smartcard info user will display information about the user identity (if any) on the smartcard. A user is represented by the presence of a private key and its matching X.509 certificate. The X.509 certificate must contain an extension which represents a universal principal name (UPN).

The information displayed includes the UPN of the user identity, the distinguished name of the subject and issuer on the user's X.509 certificate, the validity period of the user's X.509 certificate, and the signature and key algorithms used in the X.509 certificate.

By default, information about the first user identity found on the card shall be displayed. Use the UPN argument, or the -u option, to display information about a specific user identity.

The following example demonstrates how to examine the default user identity on the card:

vastool smartcard info user

The following examples demonstrate how to examine a specific user identity on the card:

vastool smartcard info user barry@foo.bar

vastool smartcard -u barry@foo.bar info user

vastool smartcard info users will display information about all known user identities (if any) on the card.

vastool smartcard info all will display all known information about the VAS smartcard environment, including the VAS PKCS#11 configuration, the PKCS#11 library, the known PKCS#11 slots, and (if a card is present) card and user information.

vastool smartcard test

vastool smartcard test can be used to test the VAS smartcard environment. It allows for testing of the VAS smartcard configuration, of a PKCS#11 library, of the card inserted in a PKCS#11 slot, and of the user(s) on a card.

vastool [vastool options]
smartcard [smartcard options]
test { config | library [path] | card | user [UPN] | login [UPN] | all }

vastool smartcard test config will test that the VAS PKCS#11 configuration in /etc/opt/quest/vas/vas.conf is valid. The following tests are performed:

- verify that a PKCS#11 library has been specified

NOTE: No verification is made that a PKCS#11 slot has been specified, since this setting is optional

vastool smartcard test library tests that a PKCS#11 library is suitable for use by VAS. The following tests are performed:

- verify that the PKCS#11 library may be dynamically loaded;

- verify that the PKCS#11 library contains the necessary functions;

- verify that the PKCS#11 library implements a supported version of the PKCS#11 standard;

- verify that the PKCS#11 library may be initialized

By default, the configured PKCS#11 library shall be tested. A different PKCS#11 library may be tested by specifying the path argument, or by using the -l option.

vastool smartcard test card tests that a card is suitable for use by VAS. The following tests are performed:

- verify that a card is present in the slot;

- verify that the card supports the required cryptographic mechanisms;

- verify that the card contains at least one user identity

vastool smartcard test user tests that a user identity on a card is suitable for use by VAS. The following tests are performed:

- verify that the user identity can generate a signature using the private key;

- verify that the user identity can verify a signature using the X.509 certificate

Note that the card must be inserted in the slot before this test can occur.

By default, information shall be displayed about the first user found on the card. If the card contains more than user, a particular user may be identified using the UPN argument, or by specifying the -u option.

Note that a PIN may be required to perform this test. The PIN may be specified explicitly using the -p option. If a PIN is required and the -p has not been specified, then the user shall be prompted for the PIN.

The following example demonstrates how to test the default user on the card (note that a prompt shall be emitted for the PIN, if required):

vastool smartcard test user

The following example demonstrates how to test a specific user on the card, and how to specify a PIN:

vastool smartcard -p 1234 test user barry@foo.bar

vastool smartcard test login tests that a user can perform a login using the card, by performing a PKINIT operation against the configured KDC for the domain to obtain a Kerberos ticket.

By default, a login shall be attempted for the first user found on the card. If the card contains more than user, a particular user may be specified using the UPN argument, or by specifying the -u option.

Note that a PIN may be required to perform the login. The PIN may be specified explicitly using the -p option. If a PIN is required and the -p has not been specified, then the user shall be prompted for the PIN.

The following example demonstrates how to perform a login for the default user, specifying the PIN explicitly:

vastool smartcard -p 1234 test login

vastool smartcard test all will perform all tests (config, library, card, user) consecutively. If the card is not present in the slot, then the card and user tests shall be skipped.

vastool smartcard configure

The vastool smartcard configure command may be used to configure the VAS smartcard environment, by adding PKCS#11 settings to /etc/opt/quest/vas/vas.conf; by enabling smartcard support for specified PAM modules; and by adding actions for various smartcard events.

vastool [vastool options]
smartcard [smartcard options]
configure { pkcs11 { lib path | slot num } | pam {service} }

vastool smartcard configure pkcs11 may be used to configure PKCS#11 support in VAS. Two settings may be configured: the location of the PKCS#11 library, and the slot which is to be used.

The PKCS#11 library is a dynamic library supplied by a vendor of the smartcards to be used in VAS, and is installed separately. To enable smartcard support in VAS, the location of the PKCS#11 library must be specified. This is done by specifying the lib argument with the path to the PKCS#11 library.

The following example demonstrates how to configure VAS to use a PKCS#11 library:

vastool smartcard configure pkcs11 lib /usr/lib/libpkcs11.so

By default, VAS will use the first available PKCS#11 slot for its PKCS#11 operations. However, a specific slot may be specified if required. This is typically only useful when there are two or more smartcard readers attached to the host, and only one reader should be used.

The following example demonstrates how to configure VAS to use a specific PKCS#11 slot:

vastool smartcard configure pkcs11 slot 1

The command vastool smartcard info config may be used to verify that the VAS PKCS#11 configuration has been updated successfully.

The command vastool smartcard test config may be used to verify that the VAS PKCS#11 configuration contains all required settings.

The commands vastool smartcard test library and vastool smartcard test slot may be used to verify that the configured PKCS#11 library and slot, respectively, are suitable for use in VAS.

vastool smartcard configure pam may be used to install the VAS smartcard-enabled PAM module for a specific service. It is recommended that only local services (such as desktop managers, screensavers, etc) should be configured for smartcard support.

The following example demonstrates how to configure the gdm service to use the VAS smartcard PAM module:

vastool smartcard configure pam gdm

vastool smartcard unconfigure

The vastool smartcard unconfigure command may be used to unconfigure (or restore) the VAS smartcard environment, by removing PKCS#11 settings from /etc/opt/quest/vas/vas.conf; by removing smartcard support for PAM modules; and by removing actions for various smartcard events.

vastool [vastool options]
smartcard [smartcard options]
unconfigure { pkcs11 { lib | slot} | pam {service} }

vastool smartcard unconfigure pkcs11 may be used to remove some or all PKCS#11 settings from VAS, by modifying /etc/opt/quest/vas/vas.conf.

If no arguments are specified, all PKCS#11 settings are removed from /etc/opt/quest/vas/vas.conf. If the lib argument is provided, the location of the PKCS#11 library is removed. If the slot argument is specified, the ID of the PKCS#11 slot to be used by VAS is removed.

The command vastool smartcard info config may be used to verify that the VAS PKCS#11 configuration settings have been updated successfully.

vastool smartcard unconfigure pam may be used to remove the VAS smartcard PAM module from all services, or from a specific service.

The following example demonstrates how to remove the VAS smartcard module from all services:

vastool smartcard unconfigure pam

The following example demonstrates how to remove the VAS smartcard module from the gdm service only:

vastool smartcard unconfigure pam gdm

vastool smartcard trusted-certs

vastool smartcard trusted-certs can be used to manage the store of trusted certificates that it is used to verify smartcard logins.

vastool [vastool options]
smartcard [smartcard options]
trusted-certs { update [-f] }

vastool smartcard trusted-certs update will update the trusted-certificates from the NtAuth container in Active Directory. If the -f option is used then the trusted-certificate store will be flushed, before an update. Otherwise the certificates will only be updated if the store is empty, or if the interval configured by the trusted-certs-update-interval in vasd has elapsed (default 8 hours).

vastool status

vastool status verifies information in configuration files, in most cases, validating it for correctness.

vastool [ vastool options] status [-v]

vastool [ vastool options] status [-v] authconf [service...]

vastool [ vastool options] status [-v] nsconf

vastool [ vastool options] status [-v] vasconf

vastool [ vastool options] status dc [-p|-u|-a] [-v]

vastool [ vastool options] status [-v] allow

vastool [ vastool options] status [-v] deny

vastool [ vastool options] status [-v] override {users|groups}

vastool status (with no arguments) will run the series of verification commands documented here.

In verbose mode, information on the nature of findings and failures is printed to the console.

vastool status authconf will examine the appropriate configuration files on the host for the specified service or list of services that govern authentication actions including PAM, LAM, and SIA. In particular, the relevant files are examined to determine if they have been annotated for VAS use.

If no service or list of services is specified for vastool status authconf, all configuration files appropriate to the platfom will be analyzed.

vastool status dc will provide status information about known domain controllers in the forest. If the -d domain option is not used, all DC's in the forest will be checked. -p will perform a MSCLDAP ping. -u will perform a generic authenticated ldap search. -a will perform an anonymous ldap search, however, post 2000 Active Directory DC's do not allow any anonymous search and this ability is often disabled in most environments. If no options are specified, all tests will be performed.

vastool status nsconf will examine the configuration files on the host that govern name service functionality, (e.g., /etc/nsswitch.conf.) In particular, the relevant file is examined to determine if it has been annotated for VAS use.

vastool status allow and vastool status deny examine files /etc/opt/quest/vas/users.allow and /etc/opt/quest/vas/users.deny respectively to determine whether there are incorrect entries. It will test whether a listed domain, user principal name, group name, or container exists as noted in the file.

vastool status override group and vastool status override user examine files /etc/opt/quest/vas/group-override and /etc/opt/quest/vas/users-override respectively to determine whether there are incorrect entries. It will test whether a listed name or group exists (in your Active Directory domain). It validates the numeric contents, uids and gids, as numbers-only, but it cannot determine if they are accurate.

vastool status vasconf examines the /etc/opt/quest/vas/vas.conf file to determine, for every section it recognizes, whether the settings are known and have accurate values (like boolean true/false, numeric, domain names, etc.). Most complex values (right-hand values) like strings, lists and stanzas are not examined.

As VAS ignores sections and settings in /etc/opt/quest/vas/vas.conf it does not recognize, these are harmless. To get a list of these, run this tool with the -v option.

vastool status vasconf will not warn of "missing" sections or settings needed by VAS tools and daemons.

The following is examples of invoking the vastool status:

vastool status authconf

vastool -u administrator status -v vasconf

vastool -u administrator status

vastool timesync

vastool timesync can be used to query the time on the Active Directory server and synchronize the system clock with the Active Directory server. In order to set the system clock this command must be run as root.

vastool [vastool options] timesync [-d domain] [-q] [-s server]

Running vastool timesync without any arguments will automatically use the Active Directory server that was configured using the vastool join or the vastool configure realm command. If the -d option is used, then vastool timesync will query a server in the specified domain. If -s is used, then vastool timesync will sync with the specified server.

Use the -q option to query the servers time without setting the system clock.

vastool unconfigure

vastool unconfigure can be used to remove the VAS configuration from the NSS and PAM subsystems. This command must be run as root.

vastool [vastool options] unconfigure

vastool [vastool options] unconfigure nss

vastool [vastool options] unconfigure pam [service...]

Running vastool unconfigure nss will remove the vas settings in /etc/nsswitch.conf. Running vastool unconfigure pam without specifying any service names will remove the VAS configuration from all PAM-enabled services. If service names are specified, only those specified services will have their VAS configuration removed.

Running vastool unconfigure with no arguments will unconfigure both the NSS configuration and all PAM-enabled services from using VAS.

The following are examples of removing the VAS configuration from /etc/nsswitch.conf, disabling VAS authentication from the ssh server, and disabling VAS authentication for all PAM-enabled services.

vastool unconfigure nss

vastool unconfigure pam sshd

vastool unconfigure pam

vastool unjoin

vastool unjoin is a convenient command that wraps all of the steps to remove your computer object from Active Directory and to remove the VAS configuration from the NSS and PAM subsystems in one step. This command must be run as root.

vastool [vastool options] unjoin [-f] [-l] [-n computer_name] [--skip-config]

vastool unjoin will first remove the NSS and PAM configurations with vastool unconfigure. It will then prompt you for your administrative password in order to delete the computer object for your machine in Active Directory. As part of this process, vasd will be stopped. The automatic modification of the system configuration files can be disabled with the --skip-config option. When --skip-config is specified, the system configuration files for PAM, NSS, and LAM will not be modified to remove any VAS specific entries.

The -f option will force the system to perform its unjoin process if the computer object does not exist in Active Directory.

The -l option will perform an unjoin on the system but leave the computer object in Active Directory.

If you used the -n option in the vastool join process, then you need to specify that same name that you used in the join in the vastool unjoin process.

The following are examples of unjoining the machine where the computer object is named after the system hostname, and unjoining the machine when the computer object name does not match the hostname.

vastool -u admin unjoin

vastool -u admin unjoin -n computer_name

vastool unmerge

vastool unmerge can be used to remove Active Directory users and groups from /etc/passwd and /etc/group. This should only be done on systems that do not support NSS and PAM. This command must be run as root.

vastool [vastool options] unmerge {users | groups}

vastool unmerge users will remove all Active Directory user accounts from /etc/passwd. vastool unmerge groups will remove all Active Directory groups from /etc/group. If no option is specified to vastool unmerge, then both the Active Directory users and groups will be removed.

Following is an example of removing Active Directory user accounts, and an example of removing the Active Directory groups.

vastool unmerge users

vastool unmerge groups

vastool user

The vastool user command allows you to enable or disable user accounts in Active Directory, verify certain access scenarios typically done during user logins, and obtain the complete of groups a user belongs to, including nested group membership. You can either disable the Windows account, or disable the account for Unix users. You may only Unix-enable an account with the vastool user command if it has been previously Unix-enabled using the VAS MMC snap-in.

vastool [vastool options] user [-d] enable username

vastool [vastool options] user [-d] disable username

vastool [vastool options] user [-d] checkaccess username

vastool [vastool options] user [-d] checkconflict username getgroups [-l] [-p] [-s] [username]

vastool [vastool options] user checklogin [-s service]

The -d option specifies that the username should be interpreted as an LDAP Distinguished Name.

The enable and disable commands will modify a user's userAccountControl flags to enable/disable them. It does not modify the user's Unix account settings.

The checkaccess command will evaluate whether or not the given user has access to the current host. It uses the same logic that pam_vas uses during user logins. Its exit code will be 0 if the user has access, and 1 otherwise.

The checkconflict command will check if the given user has any UID conflicts using the same logic as pam_vas. If the user has a UID conflict, the exit code will be 1. If there is no UID conflict for the given user, the exit code will be 0.

The checklogin command will perform an actual auth process to test authentication for a user. If the -s service option is not specified, the the standard system login service will be used. If a user is denied due to any access control rules, this information will be returned from the checklogin command.

The getgroups command will show the Active Directory groups a user is a member of. Note that the list of groups are not limited to Unix-enabled groups. By default, vastool will return back the group information from the local cache. The -l option will change this behavior so that vastool will directly use LDAP searches to resolve this group membership by using the tokenGroups attribute and mapping the resulting SID's. Note that the tokenGroups attribute only includes the groups that are usable in the domain that the user belongs to.

The output format for the command follows the format used by the Unix id. The group name will be printed out in a comma-separated list where each group name will be surrounded by parentheses. The group name will be shown following a <DOMAIN>/<samAccountName> format. The -s option will cause the SID of the group to be printed out before the group name. To ease parsing of the output from scripts, the -p option will print each group on its own line without commas.

Following is an example of disabling a user's account, getting a user's group membership with the tokenGroups attribute, and getting a user's group membership from the VAS cache:

vastool -u admin-user user disable jdoe

vastool user getgroups -l jdoe

vastool user getgroups jdoe

vastool vasypd

The vastool vasypd command allows you to manage settings for the VAS YP server (daemon).

vastool [vastool options] vasypd getmaps [ -l] [ -a] [ -b searchbase] [ toconf]

vastool [vastool options] vasypd addmaps [ -b searchbase] {mapname...}

vastool [vastool options] vasypd delmaps all

vastool [vastool options] vasypd delmaps {mapname...}

The -l option will force vastool vasypd to use LDAP directly and bypass the vasd cache.

You can specify a container by its distinguished name (DN) in Active Directory in which to perform the search.

Via -b and -l, the getmaps command searches Active Directory for NIS maps and writes any found to the console. If the toconf argument follows, the map or maps will also be written to a nismaps stanza under section [vasypd] in /etc/opt/quest/vas/vas.conf.

Note: option -b is meaningless if the maps are being got from /etc/opt/quest/vas/vas.conf. If it is not accompanied by -l, a warning will issue and the searchbase will have the appearance of being ignored.

The utility of the vastool vasypd getmaps is to prepare for using a nismaps stanza (see man page for vas.conf;, section [vasypd]) by displaying existing maps from Active Directory and, optionally, writing them to /etc/opt/quest/vas/vas.conf. As using a nismaps stanza goes to the exclusion of any maps, listing the maps helps ensure that none needed might be forgotten.

getmaps option -a in combination with toconf will add more maps, presumably from a different source, to the nismaps stanza. Any maps with duplicate names will not be added, a note to this effect posted on the console, and they will only be added once those maps are deleted from /etc/opt/quest/vas/vas.conf.

Once there are maps in the nismaps stanza, more may be added at any time using vastool vasypd addmaps. If an attempt to add a map under a name already represented in the stanza is made, a warning to that effect will appear. The map may be deleted, if desired, then re-added successfully.

There may be duplicate map specifications in the stanza after the command with option toconf. The unwanted ones must be removed via vastool vasypd delmaps (or by hand), otherwise, the first one listed will be used to the exclusion of subsequent ones.

The delmaps command deletes either all NIS maps listed in the nismaps stanza (and erases the stanza itself) under section [vasypd] in /etc/opt/quest/vas/vas.conf, or it deletes the specified map or maps.

The addmaps -b defines the searchbase of where to start looking for the nismaps in the LDAP directory (i.e. AD).

Following are examples of getting NIS maps into and removing certain ones from /etc/opt/quest/vas/vas.conf.

vastool -u admin-user vasypd getmaps -l toconf

vastool -u admin-user vasypd delmaps netgroup rpc hosts

vastool -u admin-user vasypd addmaps -b searchbase toconf

See Also

pam_vas(5), vasd(1), nss_vas(5), uptool(1), vas.conf(5)

Authors

Copyright 2008 Quest Software, Inc. All Rights Reserved