Man pages for vastool command - 4.1.1 (4267373)

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

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.

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:

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:

Common vastool Options

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

Exit Status

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

vastool attrs

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

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

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.

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

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 QAS 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 \ 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 configure

vastool configure can be used to modify your system's PAM, NSS, Directory Service, Kerberos realm, IRS, Sudo and /etc/opt/quest/vas/vas.conf configuration. This command must be run as root.

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, manual configuration of non-identity map data (i.e. netgroup), or one-time creation of Active Directory application configuration.

vastool configure ad will create the QAS application configuration in any Active Directory container specified. This global application configuration only need be created once per forest, and can exist in any location in the forest (although the default location for creation is the "Program Data" container). Before any QAS 4 clients will be able to join Active Directory, this global application configuration must be created. The application configuration is created the first time the QAS Control Center is started from any Windows workstation. The configure ad command is provided as an alternate method for creating the application from the unix command-line. (Note: the --preload-nested-memberships option has been deprecated because the default behavior for this setting has been changed to true.)

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 vas4
 group:   files vas4

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

Adding vas4 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 QAS account to be resolved to the QAS account. For more information on configuring NSS see the nss_vas(5) manual page.

vastool configure irs (AIX only) Configures the /etc/irs.conf file to enable the dynamically loaded netgroup module if /etc/opt/quest/vas/vas.conf contains netgroup-mode = NSS.

vastool configure pam will modify either /etc/pam.conf, or the files located in the /etc/pam.d directory to use the pam_vas3. 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. If the "Other" service doesn't allow access to the box, running "vastool configure pam " will not successfully configure the service "service name" for QAS authentication. For more information on configuring and customizing pam_vas, see pam_vas(5) . The -g option has been deprecated as of QAS 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.

vastool configure ds is only available on Mac systems. It will modify your Directory Service configuration to include the QAS Directory Service module.

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

In some circumstances it is useful to remove an entire section from /etc/opt/quest/vas/vas.conf. In that case the command vastool configure vas remove section can be used.

The vastool configure mit command may be used to configure the MIT KRB5 configuration file on your platform to work with QAS. This command honors -f option for selecting a file location, but if no file is specified it defaults to /etc/krb5.conf on Unix systems and /Library/Preferences/edu.mit.Kerberos on Mac systems. On Mac systems, vastool configure mit is called as part of the join.

vastool configure sudo will configure sudo to allow access control based on Active Directory groups that are not Unix-enabled. The location of the configuration file (sudoers file) will be determined automatically if visudo is in your PATH. Alternatively you can provide the path to visudo with the -V option, or the path to a sudoers file with the -f option.

See sudo_vas(8) for more information on the Sudo add-on features provided by QAS.

Examples:

          vastool configure sudo
          vastool configure sudo -V /usr/sbin/visudo
          vastool configure sudo -f /etc/sudoers
        

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.

Common vastool create Options

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 of which your computer is a member.

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.

To create a user with an alternate upn suffix,

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 QAS 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 daemon

vastool daemon starts, stops or restarts daemons (services). It uses the native daemon control interface (eg. init script).

Example usage:

vastool delete

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

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.

If the --delete-tree option is used the LDAP_SERVER_TREE_DELETE_OID will be used. This will tell Active Directory to delete the object and any children objects. Use with caution.

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 flush

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

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 QAS host keytab file. Flushing the statedir will delete all of the QAS state information. Flushing the keytab and statedir will not recreate their respective information, and should only used during uninstallation of the QAS 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.

The caching daemon maintains a cache of users and groups that could not be found when searching the directory. This cache is referred to as the negative cache. Once an item is in the negative cache no further attempts will be made to find the user/group in the directory until the negative cache entry has expired. The default negative cache lifetime is very short (10 seconds), but it can be increased to suit environmental needs. If entries need to be removed from the negative cache before their lifetime has expired, the contents of this cache can be cleared by running vastool flush negcache.

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

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 read 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 ns command will flush all name service caches: users, groups, and netgroups.

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. This option has been deprecated as of QAS 4.0.

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. There is no max password age 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.

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 QAS-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. The exit code will also indicate membership: 0 if the user is a member, 1 if the user is not a member, and 2 if the group was not found.

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 info

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

The acl option displays the access control options currently enforced on the host including whether these are imposed by QAS Group Policy (Native AD group policies) and lists rules by Allow or Deny and by user and group. If the -f flag is specified then all group rules will be unrolled. This can be slow.

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 cldap option will cldap ping ( port 389 UDP ) the specified server, and return the information in the response. This command can be used with a domain name if that name resolves to the IP of a Domain Controller.

The domain option returns the name of the Active Directory domain that is configured as the host machine's default realm. If QAS is configured to join example.com, the domain option 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 filelocks option checks the database files for locks that could cause issue.

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 ipv6 option indicates whether IPv6 is supported on the local system. IPv6 support is disabled when the operating system's IPv6 implementation is deficient. vastool info ipv6 exits 0 if IPv6 is supported, or 1 if it is not.

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). If the -b is used the query will bypass querying vasd for the information.

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 inspect

vastool inspect returns the value of a configuration file 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 isvas

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

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 join

vastool join performs all of the necessary steps to configure the QAS 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 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 QAS 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. 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-QAS system configuration files. The administrator is then responsible for ensuring that the system configuration files are correctly modified to use the QAS components. The --site-only-servers option restricts all LDAP searches to domain controllers within the joining machine's site. If a site server cannot be found, the search will fail instead of failing over to searching for a server from another site (the default behavior) This should be used when non-site servers would be unavailable anyway, 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 --autogen-posix-attrs option will configure vasd to automatically generate posix attributes for non-Unix enabled Active Directory Users and Groups. The attributes are stored locally on the host, not in Active Directory. The algorithm used to generate the UID and GID is based on the GUID of the Active Directory object and will be the same across different hosts, unless a conflict was detected on a particular machine. Identities with an existing Enterprise Identity (stored in Active Directory) will retain their Enterprise Identity values. However, entities who receive an Enterprise Identity after attributes have been auto-generated will retain the auto-generated attributes until manually migrated by the administrator. See the man page on /etc/opt/quest/vas/vas.conf for settings that affect the local generation of specific attributes.

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. However, when you specify servers, vastool will only use the servers you specify and will not detect any others.

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

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 QAS 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) .

QAS 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-forest 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. This sets cross-forest-domains. For more information about cross-forest login with simple name see the QAS Administration Guide.

If Quest Authentication Services 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 QAS. You can disable this behavior by using the -l option, which also prevents the QAS Group Policy daemon from being loaded. For more information about using QAS Group Policy with QAS, see the QAS 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 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 kinit

vastool kinit can be used to obtain Kerberos tickets.

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:

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 QAS API. This can be done by running:

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

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.

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.

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 license -d will update QAS licenses from Active Directory.

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 QAS is a site based license.

The add command allows for the addition of a license into the QAS Active Directory application configuration. Once a license is added to the application configuration all other clients joined to the domain will pick the license up either at join time, or within a 24 hour window if already joined. Additionally, the add command adds the license locally, ensuring the local client is licensed even if the adding user has no rights to modify the application configuration on the Active Directory side.

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.

Common vastool list Options

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 -l option. 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 -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 -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 -g option will print objectGUIDs associated with this object in the form :

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.

The -u option will trigger a group membership unroll before doing a group 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 vastool list negcache command will list all users and groups that the caching daemon has in its negative cache. Entries are put in the negative cache when they are requested but not found in the directory. They remain in the negative cache for a configurable period of time before any further directory lookups will be attempted.

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 load

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

vastool load Options

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. The -s option specifies a prefix for the SAMAccountNames of the group being created.

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

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

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 QAS users.allow and users.deny file, and only users who are allowed access will 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 QAS 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 QAS 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 nss

vastool nss can be used to acquire user, group, and password information using vastool.

The -d option by-passes the NSS layer and directly queries vasd. It only returns QAS users.

vastool otp

vastool otp can be used to manage the configuration of two-factor authentication using Defender one-time passwords. This command must be run as root.

The vastool otp configure command sets up the configuration necessary to enable one-time password authentication. vastool otp configure pam adds the Defender PAM module to the system PAM configuration. vastool otp configure trace also adds the Defender PAM module to the system PAM configuration with the addition of a trace file for debugging. When a service is specified to vastool otp configure pam, the Defender PAM module is only added to the system PAM configuration for that specific service.

The vastool otp configure radius command modifies /etc/defender.conf and /etc/pam_radius_acl.conf based on the information defined in a Defender Access Node in Active Directory. The Defender Access Node to use is determined by matching your host's IP address to the IP address and subnet defined on the Defender Access Node. When configured using this command the shared secret in /etc/defender.conf is obfuscated. The entries in /etc/pam_radius_acl.conf are based on the members of Defender Access Node. For more information, refer to the Defender product documentation.

The vastool otp unconfigure pam command removes the Defender PAM module from the system PAM configuration. When a service is specified to vastool otp unconfigure pam, the Defender PAM module is only removed from the system PAM configuration for that specific service.

The vastool otp unconfigure radius command removes the configuration in /etc/defender.conf and /etc/pam_radius_acl.conf.

vastool passwd

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

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. QAS users will not be able to change their passwords using the system passwd command. vastool passwd can be used by QAS 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:

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

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 -p option is used to direct the password change to the PDC.

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

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 QAS uses when in disconnected mode. Administrators can temporarily enable access for that user until QAS 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:

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.

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.

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.

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 is used to detect/cache/modify the schema set that is being used by QAS to store unix identity information (unix home directories, UID and GID numbers, etc.) in the directory.

vastool schema detect will detect/re-detect the unix identity schema that is configured in the QAS application configuration.

vastool schema list will list the schema extensions currently being used by QAS.

vastool schema cache will detect/re-detect the unix identity schema that is configured in the QAS application configuration container in the forest you are currently joined to, as per schema detect, and will then cache this schema information for local use.

vastool schema configure will modify the global QAS application configuration, and by so doing it will affect all unix clients joined to this forest. This command currently allows you to globally set the use of either R2 standard attributes for storing unix identity information (UIDNumber, GIDNumber, etc) or a schemaless method. Any more granular schema modification than this must take place from a Windows workstation with QAS Control Center installed.

All of these schema commands operate on the joined forest or domain. It makes sense in some situations to run one or more of these commands prior to join (for example configuring schema information prior to join). When running a schema command prior to joining a domain, the -d option is required to specify what domain to perform the schema operation upon.

Some schema attributes can be specified on a per machine basis by modifying local settings in in /etc/opt/quest/vas/vas.conf file. See the vasd man page for more information.

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.

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 the search to fail. All data returned from anonymous searches are returned unencrypted. 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 -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 RFC 4515 and 4517.

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 printing the attribute names, and the sets of results will not be separated by empty lines. This is 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.

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

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.

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 QAS 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 permission 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. You can specify the service account's name with the -n option, otherwise it will be generated automatically based on the host & service names.

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.

The -a option enables the use of AES encryption in Kerberos tickets for the service. This should only be used if all clients and servers (including Domain Controllers) support AES encryption — generally Windows Vista and Windows 2008 or later.

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

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:

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 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 setattrs Options

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 QAS 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 QAS NIS Map object from an external file:

vastool smartcard

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

The vastool smartcard can obtain certain information from the QAS 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 QAS smartcard 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 QAS 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 QAS smartcard environment.

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

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

- vastool smartcard unconfigure may be used to unconfigure (or restore) the QAS smartcard enviro

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 list of groups a user belongs to, including nested group membership. You can either disable the Windows account, or disable the account for Unix user. You may only Unix-enable an account with the vastool user command if it has been previously Unix-enabled using the QAS 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 /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 QAS 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 QAS YP server (daemon).

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

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

vastool [vastool options] vasypd delmaps [ all | mapname... ]

vastool [vastool options] vasypd readmaps

Use the vastool vasypd getmaps utility to configure NIS maps in a nismaps stanza. (See the [vasypd] section of the vas.conf man page, located in /etc/opt/quest/vas/vas.conf, for more information.)

When a nismaps stanza exists, only the RFC2307 NIS maps in the stanza are displayed with NIS commands.

Use the vastool vasypd getmaps option with -a to add maps to the nismaps stanza.

Use getmaps -b, to search an optional searchbase for NIS maps.

Use the vastool vasypd addmaps to add a specific NIS map (or maps) to the stanza.

Use the addmaps -b to specify a searchbase from which to look for the NIS maps in Active Directory.

Use the vastool vasypd delmaps command to delete either a specified NIS map (or maps) or all NIS maps listed in the nismaps stanza. Deleting all NIS maps erases the stanza itself.

The readmaps option lists the NIS maps defined in vas.conf.

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

vastool -u admin-user vasypd getmaps

vastool -u admin-user vasypd delmaps netgroup rpc hosts

vastool -u admin-user vasypd addmaps -b searchbase