Working with the CLI

Invoking CLI Commands

The CLI consists of the command pgtool, which operates in a single-line command mode that executes one command at a time. pgtool contains a number of sub-commands, options and operands, which are described in Command Summary. The options can be specified using either a full or a short keyword. In the following commands descriptions, the full keywords are used, but the shortcuts that correspond to the commands can be found in Table 3–2.

Bootstrapping Information Required by the CLI

Bootstrapping information is required in order to locate and interrogate the datastore containing the elements and profiles. The bootstrapping information that is required is server, port number, base distinguished name (DN) and username of the administrator. This information can be specified at the command line or in a bootstrapping file.

Bootstrapping file

The boostrapping information can be read from a properties file. The location of this file can be specified in the command line by the --file option.

--file=<bootstrap file> : fully qualified path to a bootstrapping file. The default file is $HOME/pgtool.properties.

Example: --file=/var/opt/apoc/cli.properties.

The format of the file is described in the Appendix A, Configuration Parameters, in Sun Desktop Manager 1.0 Installation Guide.

Bootstrapping options

The bootstrapping can be specified at the command line using the --url and --username options.

--url=<url> : the URL identifying the datastore. The URL format is ldap://<hostname>:<port>/<base name> with <hostname> the name of the server (default is localhost), <port> the port number on the server (default is 389) and <base name> the distinguished name of the base entry.

Example: --url=ldap://server1.sun.com:399/o=apoc.

--username=<username> : the username of the administrator in the format used by the storage back end. The administrator is then prompted for a password. If this option is not used, and the administrator has not used the pgtool login sub-command, then the administrator is prompted to enter a username and password.

Example: --username=“jmonroe”.

Authentication by Username and Password

A username and password are required for each execution of a command.

Authentication by login command

The CLI provides a login command to allow username/password pairs to be stored in a credentials file in the administrator's home directory. This file is named .apocpass. The .apocpass file has restricted access.

If authentication is successful, a username/password pair entry is added to the .apocpass file. The key for this pair is made up of the server/port/base DN and the username so that username/password pairs can be stored for other back ends in the same file.

Once the login command has successfully completed, other CLI commands can be executed without the necessity of specifying a username or password.

For more details on how to use the login command, see Login.

Authentication for the other commands

For other commands, the CLI first checks to see if an .apocpass file exists for the current user.

If the file does not exist, the user is prompted for a username and password. If this username and password is successfully authenticated, the command is executed.

If the credentials file does exist and a username has been specified at the command line, the CLI looks for an entry for the host, port, base DN and username. If an entry exists, the stored user DN and password is used to execute the command, otherwise the user is prompted for a password.

If a username is not specified at the command line, the .apocpass file is searched for keys using the host/port and base DN combination. If there is a unique entry for this combination, the stored user DN and password is used to execute the command. If the entry is not unique, the user is prompted for a username. If this matches an entry, the stored user DN and password is used to execute the command. If this does not match, then the user is prompted for a password.

Where the user is prompted for a password, an entry from the .apocpass file for this host/port/baseDN combination is used to authenticate the username and password. If such an entry does not exist, anonymous access is used for the authentication.

Running a Command

Each use of a command creates and initializes a connection to the datastore and then exits once the command has been executed. If the command exits with an error, no changes were applied to the configuration profiles.

Representing Elements

An element is represented using the LDAP full Distinguished Name (DN).

Example: uid=jmonroe,ou=People,o=apoc.