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.
--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 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”.
- © 2010, Oracle Corporation and/or its affiliates