Sun Desktop Manager 1.0 Administration Guide

Chapter 3 Using the Command Line Interface

This chapter provides information about the Sun Desktop Manager command line interface.

Overview of the Desktop Manager CLI

The CLI is used to create, manipulate, export, import and delete configuration profiles. As with the Desktop Manager GUI, the CLI allows the following actions:

Profiles can be assigned and unassigned to or from elements.
Profiles can be exported and imported in XML format to or from zip files. The profile settings in these zip files can then be created, edited or deleted prior to importing the profiles.

Note –

The CLI does not provide the equivalent of the GUI functionality for the following functions:

Navigation of element hierarchy.
Viewing merged profile settings for elements.
Generating reports.
Access to file based or hybrid back end, provides access to LDAP back end only.

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.

CLI Commands

This section describes the sub-commands of Desktop Manager CLI functionality.

Note –

For backward compatibility reasons, the CLI uses the --entity option to specify what is now called an “element” in the Desktop Manager user interface. The terms are interchangeable. There is no --element option.

Help

To obtain a list of all available CLI commands, type pgtool --help.

Version Information

To display version information, type pgtool --version.

Add

Assigns a profile to an element.

Syntax

add [--scope=<user|host>] [--entity=<entity>] <profile name> <target entity>

--scope=<user|host> : the scope for the profile, which can be either user or host. If not specified, then defaults to the user scope.

--entity=<entity> : the element where the profile is located. If not specified, then defaults to root organization or domain element, depending on the --scope option.

<profile name> : the name of the profile to be assigned to the element. If no profile or more than one profile with this name and this scope can be found at this layer, then the command exits with an error.

<target entity> : the element to which the profile is assigned.

Example 3–1 Adding a profile to an element

% pgtool add UserProfile1 cn=Role1,o=staff,o=apoc

The profile “UserProfile1” located in root organization was assigned to the element “cn=Role1,o=staff,o=apoc”.

Create

Creates a new, empty profile.

Syntax

create [--name=<profile name>] [--scope=<user|host>] [--entity=<entity>] [--priority=<priority>]

--name=<profile name> : the name of the profile to be created. If a profile with this name and this scope already exists at this layer, then the command exits with an error. If not specified, then the command defaults to the first profile name available in the series, for example, “NewProfile”, “NewProfile2”, “NewProfile3”, ...

--scope=<user|host> : the scope for the profile, which can be either user or host. If not specified, then the command defaults to the user scope.

--entity=<entity> : the element where the profile is created. If not specified, then the command defaults to root organization or domain element, depending on the --scope option.

--priority=<priority> : a strictly positive integer specifying the priority of the profile. If the priority specified is the same as that of an existing profile of this scope at this layer, then the priority option is ignored. If not specified, then the created profile will have the highest priority at this layer.

Example 3–2 Creating a new profile

% pgtool create --scope=host --name=NewHostProfile1

Creates a new profile called “NewHostProfile1” in the domain root and whose scope is “host”.

Delete

Deletes a profile.

Syntax

delete --name=<profile name> [--scope=<user|host>] [--entity=<entity>]

--name=<profile name> : the name of the profile to be deleted. This option is mandatory. If no profile or more than one profile with this name and this scope can be found at this layer, then the command exits with an error.

--scope=<user|host> : the scope for the profile, which can be either user or host. If not specified, then defaults to the user scope.

--entity=<entity> : the element where the profile is located. If not specified, then defaults to root organization or domain element, depending on the --scope option.

Example 3–3 Deleting a profile

% pgtool delete --scope=host --name=renamedNewHostProfile1

Deleted the “renamedNewHostProfile1” profile located in root domain.

Export

Exports the profiles contained in a profile to the specified target, using a zip file format.

Syntax

export --name=<profile name> [--scope=<user|host>] [--entity=<entity>] <target>

--name=<profile name> : the name of the profile to export. This option is mandatory. If no profile or more than one profile with this name and this scope can be found at this layer, then the command exits with an error.

--scope=<user|host> : the scope for the profile, which can be either user or host. If not specified, then defaults to the user scope.

--entity=<entity> : the element where the profile is located. If not specified, then defaults to root organization or domain element, depending on the --scope option.

<target> : the full path to the zip file where the profile is to be exported. If the path does not specify any filename, then the filename defaults to <profile name>.zip. If the target is not writable, then the command exits with an error.

Example 3–4 Exporting a profile

% pgtool export --scope=host --name=HostProfile1 /tmp/newdir

Exported “HostProfile1” (located in root domain) to HostProfile1.zip, which was created in new directory /tmp/newdir.

Import

Imports a profile stored in zip file format from the specified source. The source contains the profiles to be imported into the profile.

Syntax

import [--name=<profile name>] [--scope=<user|host>] [--entity=<entity>] [--priority=<priority>] <source>

--name=<profile name> : the name of the profile to be imported. If not specified, then defaults to the name of the .zip source file. If a profile of this name and scope already exists at this layer, then it is overwritten.

--scope=<user|host> : the scope for the profile, which can be either user or host. If not specified, then defaults to the user scope.

--entity=<entity> : the element where the profile is located. If not specified, then defaults to root organization or domain element, depending on the --scope option.

--priority=<priority> : a strictly positive integer specifying the priority of the profile. If the priority specified is the same as that of an existing profile of this scope at this layer, then this option is ignored. If not specified, then the imported profile will have the highest priority at this layer.

<source> : the full path to the zip file containing the profiles to import.

Example 3–5 Importing a profile

% pgtool import --scope=host --name=NewHostProfile1 --priority=7 /tmp/HostProfile1.zip

Profile with name “NewHostProfile1”, scope “host”, priority “7” and located in root domain, was imported from HostProfile1.zip.

List

Lists all profiles or element/profile assignments.

If neither --name option nor --entity option is specified, then all the user or host profiles are listed, depending on the --scope option.

If the --name option is specified, then all the elements assigned to this profile are listed.

If the --entity option is specified, then all the profiles assigned to the element specified are listed.

Syntax

list [--scope=<user|host>] [--entity=<entity>] [--name =<profile name>]

--scope=<user|host> : the scope for the profile, which can be either user or host. If not specified, then defaults to the user scope.

--entity=<entity> : the element where the profile is located, if the --name option is specified. Otherwise, the element to which profiles to be listed are assigned. If not specified in the former case, then defaults to the root organization or domain element, depending on the --scope option.

--name=<profile name> : the name of the profile whose assigned elements are to be listed. If no profile or more than one profile with this name and this scope can be found at this layer, then the command exits with an error.

Example 3–6 Listing assignments

% pgtool list

Lists the profiles assigned to root organization.

% pgtool list --scope=host --name=HostProfile1

Lists elements assigned to profile “HostProfile1” located in root domain.

Login

Stores the username and password for the datastore back end after a successful authentication to this datastore. This username and password can then be used in future invocations of pgtool.

The credentials are stored in a file named .apocpass in the administrator's home directory. If this file already exists and it does not have the correct permissions, then the command exits with an error.

If a username is specified, the administrator is prompted for a password, otherwise the administrator is prompted for a username and a password. The username and password are authenticated using anonymous access to the datastore. If anonymous access is not supported, then the administrator is prompted to enter an authorized username and a password. If authentication by the authorized username fails, then the command exits with an error.

Once authenticated, the username/password pair entry is stored in the administrator's .apocpass file using a key made up of a combination of the host/port/base DN and the username so that username/password pairs can be stored for other back ends in the same file.

The bootstrapping information can be specified in the command using the --file option to indicated the file where this information is found, or using the --url option to directly specify this information. For more information about boostrapping, see Bootstrapping Information Required by the CLI

If bootstrapping information is not available or the credentials file cannot be created, then the command exits with an error.

If the credentials file is successfully created, then it is not necessary to specify username and password for subsequent pgtool commands using this storage back end. The username and password details stored in the credentials file are used.

Syntax

login [--username=<username>] [--file=<bootstrap file>] [--url=<url>]

--username=<username> : the username of the administrator in the format used by the storage back end, for example “jmonroe”.

--file=<bootstrap file> : fully qualified path to a bootstrapping file. The default file is $HOME/pgtool.properties. This option is not compatible with the --url option.

Example 3–7 Login

% pgtool login --username=jmonroe [Enter the correct password when prompted]

A file called ~/.apocpass created with entry for “jmonroe” and “password”, file has permissions 600. The information about the back end to connect to is found in the default boostrapping file ~/pgtool.properties

Modify

Changes the priority of a profile.

Syntax

modify [--scope=<user|host>] [--entity=<entity>] <profile name> <priority>

--scope=<user|host> : the scope for the profile, which can be either user or host. If not specified, then defaults to the user scope.

--entity=<entity> : the element where the profile is located. If not specified, then defaults to root organization or domain element, depending on the --scope option.

<profile name> : the name of the profile to change priority to. If no profile or more than one profile with this name and this scope can be found at this layer, then the command exits with an error.

<priority> : a strictly positive integer specifying the priority of the profile. If the priority specified is the same as that of an existing profile of this scope at this layer, then the command exits with an error.

Example 3–8 Changing the priority of a profile

% pgtool modify UserProfile1 15

Changed the priority of “UserProfile1”, located in root organization, to 15.

Remove

Unassigns a profile from an element.

Syntax

remove [--scope=<user|host>] [--entity=<entity>] <profile name> <target entity>

--scope=<user|host> : the scope for the profile, which can be either user or host. If not specified, then defaults to the user scope.

--entity=<entity> : the element where the profile is located. If not specified, then defaults to root organization or domain element, depending on the --scope option.

<profile name> : the name of the profile to unassign from the target element.

<target entity>: the element to from which to unassign the profile.

Example 3–9 Unassigning a profile from an element

% pgtool remove UserProfile1 cn=Role1,o=staff,o=apoc

The profile “UserProfile1” located in root organization was unassigned from the element “cn=Role1,o=staff,o=apoc”.

Rename

Renames a profile.

Syntax

rename [--scope=<user|host>] [--entity=<entity>] <profile name> <newname>

--scope=<user|host> : the scope for the profile, which can be either user or host. If not specified, then defaults to the user scope.

--entity=<entity> : the element where the profile is located. If not specified, then defaults to root organization or domain element, depending on the --scope option.

<profile name> : the current name of the profile to rename.

<newname> : the new name for the profile. If a profile of this name and scope already exists at the same layer, then the command exits with an error.

Example 3–10 Renaming a profile

% pgtool rename NewUserProfile2 renamedNewUserProfile2

Renamed “NewUserProfile2” located in root organization to “renamedNewUserProfile2”.

Command Summary

Table 3–1 Commands


Command	Description
`add`	Assigns a profile to an element.
`create`	Creates a new, empty profile.
`delete`	Deletes a profile.
`export`	Exports the profiles contained in a profile to the specified target, using a zip file format.
`import`	Imports a profile stored in zip file format from the specified source. The source contains the profiles to be imported into the profile.
`list`	Lists all the profiles or the profiles assigned to an element or the elements a profile has been assigned to.
`login`	Stores the username and password for this datastore back end in a file in the administrator's home directory. This username and password can then be used in future invocations of `pgtool`.
`modify`	Changes the priority of a profile.
`remove`	Unassigns a profile from an element.
`rename`	Renames a profile.

Table 3–2 Options


Option	Description
`-b <base name>, --base=<base name>`, DEPRECATED	The root entry of the storage back end. The format for this base entry is determined by the storage back end used. For example, an LDAP storage back end with a root entry of o=apoc: `--base o=apoc`. DEPRECATED: use the `--url` option instead
`-e <entity>, --entity=<entity>`	Represents a user, role, organization, host or domain element. The entry format for the element is determined by the storage back end used. For example, an LDAP storage back end with a user “jmonroe”: `-e uid=jmonroe,ou=People,o=Staff,o=apoc`.
`-f <file>, --file=<file>`	The fully qualified path to the file detailing the bootstrapping information to be used in the execution of this command. For example: `-f /var/opt/apoc/cli.properties`.
`-h <hostname>, --hostname=<hostname>`, DEPRECATED	The name of the host for the storage back end. For example: `--host=server1.sun.com`. DEPRECATED: use the `--url` option instead
`-i <priority>, --priority=<priority>`	A strictly positive integer specifying the priority of the profile. For example: `-i 12`.
`-l <url>, --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. For example: `--url=ldap://server1.sun.com:399/o=apoc`.
`-m <name>, --name=<name>`	The name of the profile. For example: `--name=UserProfile1`.
`-p <port>, --port=<port>`, DEPRECATED	The port number for the storage back end. For example: `-p 399`. DEPRECATED: use the `--url` option instead
`-s <scope>, --scope=<scope>`	the scope for the profile, which can be either user or host. If not specified, then defaults to the user scope. For example: `--scope=host`.
`-t <type>, --type=<type>`, DEPRECATED	The type of storage back end. This defaults to LDAP. For example: `-t LDAP`. DEPRECATED: use the `--url` option instead
`-u <username>, --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. For example: `--username=jmonroe`.
`-?, --help`	Displays the help information
`-V, --version`	Displays the version information.