Java Desktop System Configuration Manager Release 1.1 Administration Guide

Chapter 3 Using the Command Line Interface

This chapter describes the Java Desktop System Configuration Manager Command Line Interface (CLI), which provides an alternative to the Configuration Manager graphical user interface for creating, manipulating, exporting and importing groups of configuration policies.

Overview of the Configuration Manager CLI

The CLI is used to create, manipulate, export and import and delete policy groups. These policy groups may be part of the policy group repository, or can be entity policy groups. As with the Configuration Manager GUI, the CLI allows policy groups from the policy group repository and entity policy groups to be assigned/unassigned to or from entities. The CLI allows both repository and entity policy groups to be exported and imported in XML format to or from zip files. The policy settings in such files can then be created, edited or deleted prior to importing the policy groups.

Note –

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

Navigation of entity hierarchy.
Viewing merged policy settings for entities.
Generating reports.

Working with the CLI

Invoking CLI Commands

The CLI consists of the command pgtool, which operates in single-line command mode, executing 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 corresponding to them 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 storing the entities and policy groups. The bootstrapping information required is server, port number, base distinguished name (DN), and type. This information can be specified at the command line or can be accessed in a bootstrapping file.

Accessing the Bootstrapping Information

The location of the bootstrapping file can be specified at the command line. Otherwise, the bootstrapping file installed with CLI is used. This file is installed with key names only, and should be edited by an administrator to provide the appropriate bootstrapping values.

The CLI also allows you to specify bootstrapping information at the command line. The options used to specify bootstrapping details are as follows:

--hostname=<hostname> (the name of the server hosting the storage back end)
--base=<base name> (the base entry for the storage back end)
--port=<port number> (the port number used by the storage back end)
--type=<type of back end> (e.g. LDAP)

Authentication by Username and Password

A username and password are required for each execution of a 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 and has restricted access. When the login command is used, the CLI checks to see if a .apocpass file exists in the home directory. If it does, and if the file does not have the correct permissions, i.e. 600, then the command exits with an error. If a username has been specified, then the user is prompted for a password. Otherwise the user is prompted for a username and password. This username and password is authenticated using anonymous access. If anonymous access is not supported, the user is prompted to enter an authorized DN and password. If authentication is successful, an entry is added to the .apocpass file. The key for this entry is made up of the server/port/base DN and the username.

For example, the user “jmonroe” could store a password for server cdelab1.ireland.sun.com, on port 389, with base entry o apoc using the key cdelab1.ireland.sun.com:389;o=apoc:jmonroe. The value stored is the user DN and password. In this way, the user/password pair for a number of users for this back end can be stored. Similarly, username/password pairs can be stored for other back ends. Once the login command has successfully completed, other CLI commands can be executed without the necessity of specifying a username or password.
For other commands, the CLI first checks to see if an .apocpass file exists for this user. If one 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 this host, port, base DN and username. If 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 the command creates and initializes a connection to the policymgr API, and then exits once the command has been executed. If the command exits with an errir, no changes were applied to the configuration policies.

Representing Entities

An entity is represented using the LDAP DN, for example uid=jmonroe,ou=People,o=apoc.

CLI Commands

This section describes the Configuration Manager CLI functionality.

Accessing CLI Help

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

Accessing CLI Version Information

To display version information, type pgtool --version.

Add

Assigns a policy group from the policy group repository to an entity.

Syntax

add [--username=<name>] [--scope=<user/host>] <name> <entity>

--username=<name> : the username of the administrator in the format used by the configuration repository, for example "jmonroe".

--scope=<user/host> : specifies the scope for the policy group, which can either be user or host. If not specified then defaults to the user scope.

<name> : this specifies the name of the policy group to be assigned to the entity.

<entity> : the entity name is specified in the format used by the storage back end, for example with the LDAP back end the entity is specified using a distinguished name.

Example 3–1 Adding a policy group to an entity

% pgtool add --username=jmonroe UserPolicyGroup1 cn Role1,o=staff,o=apoc

User “jmonroe” assigned the policy group “UserPolicyGroup1” to the entity “cn=Role1,o=staff,o=apoc”.

Create

The create command creates a new, empty policy group.

Syntax

create [--username=<name>] [--name=<policy group name>] [--scope=<user/host>] [--entity=<entity name>] [--priority=<priority integer>]

--username=<name> : the username of the administrator in the format used by the configuration repository, for example “jmonroe”.

--name=<policy group name> : this specifies the name for the policy group. If a policy group with this name and this scope already exists at this level then the command exits with an error. This option may not be used with the --entity option as entity policy groups have restricted default names.

--scope=<user/host> : specifies the scope for the policy group, which can either be user or host. If not specified then defaults to the user scope.

--entity=<entity name> : the entity where the policy group is created. If this option is not specified then the policy group is part of the policy group repository. This option may not be used with the --name option as entity policy groups have restricted default names.

--priority=<priority integer> : an integer (>=1) specifying the priority of the policy group. This option may not be used with the --entity option as entity policy groups have default priorities that may not be changed. If the priority specified is the same as that of an existing policy group of this scope at this layer then the command exits with an error. If the priority is not specified, then one is assigned.

Example 3–2 Creating a new policy group

% pgtool create --username=jmonroe --scope=host --name=NewHostGroup1

Creates a new policy group called “NewHostGroup1” whose scope is “host”.

Delete

Deletes a policy group.

Syntax

delete [--username=<name>] [--name=<policy group name>] [--scope=<user/host>] [--entity=<entity name>]

--username=<name> : the username of the administrator in the format used by the configuration repository, for example "jmonroe".

--name=<policy group name> : this specifies the name of the policy group to be deleted. This option is not used with the --entity option as entity policy groups have restricted default names. If the policy group does not exist or if it cannot be uniquely identified then the command exits with an error.

--scope=<user/host> : specifies the scope for the policy group, which can either be user or host. If not specified then defaults to the user scope.

--entity=<entity name> : the entity where the policy group is stored. If this option is not specified then the policy group is part of the policy group repository. This option is not used with the --name option, since entity policy groups have restricted default names.

Example 3–3 Deleting a policy group

% pgtool delete --username=jmonroe --scope=host --name=renamedNewHostGroup1

Deleted the “renamedNewHostGroup1” policy group.

Export

Exports a policy group in zip file format to the specified target. The policy group may be from the policy group repository or it may be an entity policy group.

Syntax

export [--username=<name>] [--name=<policy group name>] [--scope=<user/host>] [--entity=<entity name>] <target>

--username=<name> : the username of the administrator in the format used by the configuration repository, for example “jmonroe”.

--name=<policy group name> : specifies the name for the policy group. This option is not used with the --entity option as entity policy groups have restricted default names. There may be two policy groups in the policy group repository with the same name, one with user scope, the other with host scope. If the scope is not specified then it defaults to the user scope.

--scope=<user/host> : specifies the scope for the policy group. This can be either user or host. If the scope is not specified then the default is user.

--entity=<entity name> : the entity where the policy group is stored. This option may not be used with the --name option, since entity policy groups have restricted default names. If this option is not specified then the policy group is part of the policy group repository. The entity name is specified in the format used by the storage back end, for example with the LDAP back end the entity is specified using a distinguished name.

<target> : the path and file name where the zip file is to be stored. If no filename is given then it defaults to /tmp/<policy group name>.zip. If the target is not writeable, then the command exits with an error.

Example 3–4 Exporting a policy group

% pgtool export --scope=host --name=HostPolicyGroup1 --username=jmonroe /tmp/newdir

Exported “HostPolicyGroup1” to HostPolicyGroup1.zip, which was created in new directory /tmp/newdir.

Import

Imports a policy group stored in zip file format from the specified source. The policy group may be imported to the policy group repository or to an entity.

Syntax

import [--username=<name>] [--name=<policy group name>] [--scope=<user/host>] [--entity=<entity name>] [--priority=<priority integer>] <source>

--username=<name> : the username of the administrator in the format used by the configuration repository, for example “jmonroe”.

--name=<policy group name> : this specifies the name for the policy group. This option is not used with the --entity option as entity policy groups have restricted default names. Two policy groups with the same name and the same scope may not exist at the same location. If no policy group name is specified then it defaults to the name of the .zip file. If a policy group of this name and scope already exists in the policy group repository it is overwritten.

--scope=<user/host> : specifies the scope for the policy group. This can be either user or host. If the scope is not specified then the default is user.

--entity=<entity name> : the entity where the policy group is stored. If this option is not specified then the policy group is part of the policy group repository. The option may not be used with the -name option as entity policy groups have restricted default names. The entity name is specified in the format used by the storage back end, for example with the LDAP back end, the entity is specified using a distinguished name.

--priority=<priority integer> : an integer (>=1) specifying the priority of the policy group in the policy group repository. This option may not be used with the --entity option as entity policy groups have default priorities that may not be changed. If the priority specified is the same as that of an existing policy group of this scope in the repository then the command exits with an error. If the priority is not specified, then one is assigned.

<source> : the path and file name where the zip file is to be stored.

Example 3–5 Importing a policy group

% pgtool import --scope=host --name=NewHostPolicyGroup1 --username=jmonroe --priority=7 /tmp/HostPolicyGroup1.zip

Policy group with name “NewHostPolicyGroup1”, scope “host”, and priority “7” imported from HostPolicyGroup1.zip.

List

If no options are specified, then all the policy groups in the policy group repository are listed. If two storage back ends have been specified, then all the policy groups in the policy group repository of the user back end storage are listed. Depending on the options specified, list can also list all policy groups assigned to an entity, or the entities that use a particular policy group. When a policy group is listed, details such as name, scope, priority, and entity, if appropriate, are also listed. Entities are listed by their distinguished names.

Syntax

list [--username=<name>] [--scope=<user/host>] [--entity=<entity name>][--name =<policy group name>]

--username=<name> : the username of the administrator in the format used by the configuration repository, for example “jmonroe”.

--scope=<user/host> : if this option alone is specified then all the policy groups of the specified scope from the policy group repository is listed. If not specified then defaults to the user scope. If used with the -entity option, then all the policy groups of this scope assigned to the entity are listed. If used with the -name option, then all the entities that use the specified policy group of the specified scope are listed.

--entity=<entity name> : lists the policy groups that are assigned to an entity.

--name=<policy group name> : lists the entities that use the specified policy group.

Example 3–6 Listing policy groups in the repository

% pgtool list --username=jmonroe

Lists global policy groups for administrator “jmonroe”.

% pgtool list --username=jmonroe --name=UserPolicyGroup1

Lists entities using policy group “UserPolicyGroup1”.

Login

Stores the username and password for the 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.

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 entered, the administrator is prompted for a password, otherwise the administrator is prompted for a username and a password. The username and password is 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 user/password pairs are stored in the administrator's .apocpass file. The password is stored using a key made up of a combination of host/port/base bootstrapping information and the username. The bootstrapping file may be specified as an option argument, otherwise the bootstrapping information may be specified using the other options above. If neither methods are used, then the bootstrapping information is obtained from the default bootstrapping file installed with the pgtool. 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=<name>] [--file=<bootsrap file>] [--hostname=<hostname>] [--port=<portnumber>] [--base=<base name>] [--type=<type of back end>]

--username=<name> : the username of the administrator in the format used by the configuration repository, for example "jmonroe".

--file=<bootstrap file> : fully qualified path to a bootstrapping file.

--hostname=<hostname> : name of the host for the required storage back end. This is used instead of corresponding information supplied by the bootstrapping file.

--port=<port number> : port number used by this storage back end.

--base=<base name> : base for this storage back end, e.g. baseDN for an LDAP back end.

--type=<type of back end> : defaults to LDAP.

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

Modify

Changes the priority of a policy group in the policy group repository.

Syntax

modify [--username=<name>] [--scope=<user/host>] <name> <priority>

--username=<name> : the username of the administrator in the format used by the configuration repository, for example "jmonroe".

--scope=<user/host> : specifies the scope for the policy group, which can either be user or host. If not specified then defaults to the user scope.

<name> : specifies the name for the policy group.

<priority> : an integer (>=1) specifying the priority of the policy group. If the priority specified is the same as that of an existing policy group of this scope in the policy group repository, then the command fails.

Example 3–8 Changing the priority of a policy group

% pgtool modify --username=jmonroe UserPolicyGroup1 15

Changed the priority of “UserPolicyGroup1” to 15.

Remove

Removes a policy group from an entity.

Syntax

remove [--username=<name>] [--scope=<user/host>] <name> <entity>

--username=<name> : the username of the administrator in the format used by the configuration repository, for example "jmonroe".

--scope=<user/host> : specifies the scope for the policy group, which can either be user or host. If not specified then defaults to user.

<name> : this specifies the name of the policy group in the policy group repository that is assigned to the entity.

<entity>: the name for this entity.

Example 3–9 Removing a policy group from an entity

% pgtool remove --username=jmonroe UserPolicyGroup1 cn=Role1,o=staff,o=apoc

User “jmonroe” removed the policy group “UserPolicyGroup1” from the entity “cn=Role1,o=staff,o=apoc”.

Rename

Renames a policy group in the policy group repository.

Syntax

rename [--username=<name>] [--scope=<user/host>] <name> <newname>

--username=<name> : the username of the administrator in the format used by the configuration repository, for example "jmonroe".

--scope=<user/host> : specifies the scope for the existing policy group, which can either be user or host. If not specified then defaults to the user scope.

<name> : this specifies the current name of the policy group in the policy group repository.

<newname> : new name for the policy group. If a policy group of this name and scope already exists in the policy group repository than the command exits with an error.

Example 3–10 Renaming a policy group

% pgtool rename --username=jmonroe NewUserGroup2 renamedNewUserGroup2

Renames “NewUserGroup2” to “renamedNewUserGroup2”.

Command Summary

Table 3–1 Commands


Command	Description
`add`	Assigns a policy group from the policy group repository to an entity.
`create`	Creates a new, empty policy group.
`delete`	Deletes a policy group.
`export`	Exports a policy group in zip file format to the specified target.
`import`	Imports a policy group stored in zip file format from the specified source.
`list`	Lists the policy groups in the policy group repository, or lists the policy groups assigned to an entity, or lists the entities to which a specified policy group has.
`login`	Stores the username and password for this datastore back end in a file in the user's home directory. This username and password can then be used in future invocations of pgtool.
`modify`	Changes the priority of a policy group in the policy group repository.
`remove`	Unassigns a policy group from an entity.
`rename`	Renames a policy group in the policy group repository.

Table 3–2 Options


Option	Description
`-b <base name>, --base=<base name>`	Specifies 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`.
`-e <entity>, --entity=<entity>`	Specifies the entity representing a user, role, organization, host or domain. The entry format for the entity 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>`	Specifies a fully qualified file detailing the bootstrapping information to be used in the execution of this command. For example: `-f /tmp/policymgr.cfg`
`-h <hostname>, --hostname=<hostname>`	Specifies the name of the host for the storage back end. For example: `--host=server1.sun.com`
`-i <priority>, --priority=<priority>`	Specifies a positive integer denoting the priority of a policy group. For example: `-i 12`
`-m <name>, --name=<name>`	Specifies the name of the policy group. For example: `--name=UserPolicyGroup1`
`-p <port>, --port=<port>`	Specifies the port number for the storage back end. For example: `-p 399`
`-s <scope>, --scope=<scope>`	Specifies the scope of the policy group. The scope is either user or host; the default is user. For example: `--scope=host`
`-t <type>, --type=<type>`	Specifies the type of storage back end. This defaults to LDAP. For example: `-t LDAP`
`-u <username>, --username=<username>`	Specifies the username for an administrator of the storage back end. The user is then prompted for a password. If this option is not used, and the user has not used the `pgtool login` sub-command, then the user is prompted to enter a username and password. For example: `--username=jmonroe`
`-?, --help`	Displays this help and exit.
`-V, --version`	Displays the version and exit.