|
| Sun ONE Portal Server 6.0 Administrator's Guide |
Chapter 12 Command-Line Utilities
The Sun™ ONE Portal Server product provides a set of command-line utilities in addition to its graphical user interface.
The command-line utilities are listed in Table 12-1 and pertain to administrative tasks only. This two column table lists the commands in the first column and a brief description in the second column.
Also available is the command-line interface amadmin for iPlanet™ Directory Server Access Management Edition administration. The primary purpose of the amadmin tool is to help an administrator perform batch administrative tasks on the Directory Server, for example, create, register, and activate new services; and create, delete, and read (get) organizations, people containers, groups, roles, and users. For more information, see the iPlanet Directory Server Access Management Edition 5.1 Programmer's Guide.
dpadmin
Description
The dpadmin command enables display profile objects to be retrieved, added, modified, and removed from a display profile document by using the subcommands. All interactions with display profile objects must be in their native XML format. The dpadmin command can operate on a single display profile document only.
The dpadmin command requires:
- A subcommand (see "Subcommands").
- A user distinguished name and password to access the directory server.
- A target display profile document.
- A distinguished name to identify the LDAP node or --global (-g) option for the global level display profile document.
Syntax
This section describes the dpadmin command syntax. You cannot mix long-named options with short ones in one command line.
Short-Named Format
$ dpadmin list|modify|add|remove [command-specific options] -u uid
-w password {-g|-d dn} [-l locale] [-r] [-b] [-h] [file]$ dpadmin batch [-c] -f batch-script-filename [-l locale] [-b] [-h]
Long-Named Format
$ dpadmin list|modify|add|remove [command-specific options] --runasdn uid --password password {--global|--dn dn} [--locale locale] [--dryrun] [--verbose] [--help] [file]
$ dpadmin --version
$ dpadmin batch [--continue] --file batch-script-filename [--locale locale] [--verbose] [--help]
Subcommands
The dpadmin command takes these subcommands:
list
Description
This subcommand retrieves the specified display profile node object from the specified display profile document. If no display profile node object is specified, the entire display profile document is retrieved. The display profile object is displayed in its native XML format on standard out.
The list subcommand takes these options:
- Administrator's distinguished name and password for accessing the LDAP database by using the -u or --runasdn and -w or --password options respectively. These options are required.
- Display profile node object to display defined by the -g or --global option for the global level node, or -d or --dn option with a specific non-global level node specified. The -g or -d option is required. In the absence of the command-specific -n or --name option, the -d or --dn option displays the entire display profile document. The -g or --global option displays the entire root display profile document.
- Name of the display profile node object to display by using the -n or --name option.
- The -r or --dryrun option. This option runs a dryrun or test of the subcommand. Subcommands run with -r or --dryrun option report the error or success of the subcommand to sysout but do not make the subcommand changes to LDAP.
Syntax
$ dpadmin list -u|--runasdn uid -w|--password password {(-g|--global)|(-d|--dn dn)} [-n|--name name] [-r|--dryrun]
$ dpadmin list -h|--help
Options
Table 12-2, which describes what options are supported, contains two columns: the first column lists the possible options, arguments or operands for the list subcommand; the second column gives a brief description.
Examples
Example 1
$ dpadmin list -n TemplateTableContainer -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
This example gets the TemplateTableContainer object from the o=sesta.com organization node and prints it to standard out.
Example 2
$ dpadmin list -n mailcheck -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -g
This example goes to the global level only to get thet mailcheck object and if found, prints it to standard out.
Example 3
$ dpadmin list -n TemplateTableContainer/Bookmark2 -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
This example gets the channel named Bookmark2 located in the container TemplateTableContainer and prints it to standard out.
modify
Description
This subcommand changes the value of an existing display profile object. It reads data for the object from standard input or from the file specified as an argument to the command.
This XML data always requires a proper XML header as well as a set of names that uniquely defines which display profile object is to be modified. An example of proper XML header is:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
The semantics of the modify subcommand vary depending on the type of the display profile object being modified. When the combine option is specified, the new elements (like properties) in the display profile object are combined with the existing ones rather than replacing them. The variations of the modify subcommand are as follows:
- Display Profile—An entire display profile document can be changed to the new object value specified by using a file. When the combine option is specified, every display profile object in the display profile document is recursively combined. See the information below for how combine works for each display profile object.
- Channel or Container—A channel or container can be changed to the new object value. When modifying a channel or container, if the parent option is:
- Specified, the specified parent container is searched for a channel or container that matches the name of the new display profile object. If it is found, it is replaced by the new display profile object.
- Absent, the root display profile object is assumed to be the parent container. So the root is searched for a channel or container that matches the name of the new display profile object. If it is found, it is replaced with the new display profile object.
When the combine option is specified, the existing properties, available, and selected objects are combined with the new display profile objects.
- Properties—A display profile object's properties can be changed to the new value. The parent option is required to modify a display profile object's properties. A display profile node object (either channel or container) or display profile provider object that matches the specified name is searched for under the specified parent. If found, the object's properties object is replaced by the new display profile object. When the combine option is specified, the existing properties are combined with the new display profile object.
- Available or Selected—The Available or Selected list in a container can be replaced with the new display profile object. The parent option is required to modify display profile objects of this type. A display profile container that matches the parent name is searched for. Then the Selected or Available object is replaced by the new display profile object. When the combine option is specified, the existing Selected or Available object is combined with the new display profile object.
- String, Boolean, Integer, Collection, or Locale—A String, Boolean, Integer, Collection, or Locale property in a display profile object can be replaced by new display profile object property.
If the parent option is specified, the display profile node (either a channel or container) or display profile provider (in that order) that matches the specified name is searched for. If found, a property that matches the name of the new property is searched for. If found, the property in the display profile object is replaced by new display profile object property.
If the parent option is absent, then the display profile root node is used and the property is inserted at the root node.
When the combine option is specified, the existing Collection or Locale object is combined with the new display profile object. The combine option is not supported for atomic display profile properties such as String, Boolean, and Integer.
The atomic display profile properties such as String, Boolean, and Integer need not be named. If unnamed, the name is assumed to be equal to the string representation of the value. For example, the following two display profile integer objects are equal:
<Integer value="3"/>
<Integer name="3" value="4"/>
- Provider—An existing display profile provider object can be replaced with the display profile provider of the same name. A display profile provider object that matches the name of the new display profile provider object is searched for under the root display profile node. If present, the new display profile provider object is inserted under the root display profile object, replacing the existing display profile provider of the same name. Because providers can only exist under the root node (the root node is an implicit container), the parent option must not be specified.
The modify subcommand takes these options:
- Administrator's distinguished name and password for accessing the LDAP database by using the -u or --runasdn and -w or --password options respectively. These options are required.
- Display profile node object to modify defined by the -g or --global option for the global level node, or -d or --dn option with a specific non-global level node specified. The -g or -d option is required.
- Name of the file where the XML input is included by using the file argument. This argument is optional. When not used, XML input is expected from standard input.
- Fully qualified name of the parent of the display profile object to be modified by using the -p or --parent option.
- The -r or --dryrun option. This option runs a dryrun or test of the subcommand. Subcommands run with -r or --dryrun option report the error or success of the subcommand to sysout but do not make the subcommand changes to LDAP.
- The -m or --combine option. This option performs a merge of display profile objects.
Syntax
$ dpadmin modify -u|--runasdn uid -w|--password password {(-g|--global)|(-d|--dn dn)} [-p|--parent parent] [-r|--dryrun] [-m|--combine] file|<<EOF
$ dpadmin modify -h|--help
The data that is supplied to the dpadmin modify command is either from a file or from standard input (an XML fragment that follows the command).
Options
Table 12-3, which describes what options are supported, contains two columns: the first column lists the possible options, arguments or operands for the modify subcommand; the second column gives a brief description.
Examples
Example 1
$ dpadmin modify -p TemplateTableContainer -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp" <<EOF
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Channel name="NewNews" provider="newsprovider">
<Properties>
<String name="title" value="News Channel"/>
<String name="description" value="This channel is all about news"/>
</Properties>
</Channel>
EOF
This example modifies (replaces) the channel named NewNews in the container TemplateTableContainer with value specified as XML text on standard input.
Example 2
$ dpadmin modify -p TemplateTableContainer/NewNews -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp" farble.xml
This example replaces the property named in the file farble.xml with the new object in farble.xml file, where farble.xml contains:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<String name="welcome" value="Hi, welcome to farble land!!!!"/>
Example 3
$ dpadmin list -n TemplateTableContainer -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
...
<Collection name="news">
<Collection name="bar">
<String name="msg" value="hi"/>
</Collection>
</Collection>
...
$ dpadmin modify -p TemplateTableContainer -u "uid=amAdmin,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp" -m <<EOF
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Collection name="news">
<Collection name="bar">
<String name="msg2" value="woo hoo"/>
</Collection>
</Collection>
EOF
$ dpadmin list -n TemplateTableContainer -u "uid=amAdmin,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
...
<Collection name="news">
<Collection name="bar">
<String name="msg" value="hi"/>
<String name="msg2" value="woo hoo"/>
</Collection>
</Collection>
...
In this example, using the combine option, a new property named msg2 is added to the collection named bar. Note that the existing property, msg still remains in the result.
Example 4
$ dpadmin list -n test -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
<Container name="test" provider="testprovider">
<Properties>
<String name="title" value="test"/>
</Properties>
<Available/>
<Selected/>
<Channels>
<Channel name="test1" provider="test1provider">
<Properties>
<Collection name="news">
<String name="msg1" value="blah"/>
<Collection name="bar">
<String name="msg2" value="hi"/>
</Collection>
</Collection>
</Properties>
</Channel>
</Channels>
</Container>
$ dpadmin modify -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp" -m <<EOF
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Container name="test" provider="testprovider">
<Properties>
<String name="title" value="Test Container"/>
</Properties>
<Available>
<Reference value="test1"/>
</Available>
<Selected>
<Reference value="test1"/>
</Selected>
<Channels>
<Channel name="test1" provider="test1provider">
<Properties>
<Collection name="news">
<String name="msg1" value="123"/>
<Collection name="bar">
<String name="msg3" value="123/>
</Collection>
</Collection>
</Properties>
</Channel>
</Channels>
</Container>
EOF
$ dpadmin list -n test -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
<Container name="test" provider="testprovider">
<Properties>
<String name="title" value="Test Container"/>
</Properties>
<Available>
<Reference value="test1"/>
</Available>
<Selected>
<Reference value="test1"/>
</Selected>
<Channels>
<Channel name="test1" provider="test1provider">
<Properties>
<Collection name="news">
<String name="msg1" value="123"/>
<Collection name="bar">
<String name="msg2" value="hi"/>
<String name="msg3" value="123"/>
</Collection>
</Collection>
</Properties>
</Channel>
</Channels>
</Container>
In this example, the values of title and msg1 are replaced with the new values. Available and Selected have both had a Reference value added. The news collection has added msg3. This example shows that the -m or combine option with the modify subcommand can be used to combine and replace as necessary.
add
Description
This subcommand adds a new display profile object to the display profile. This subcommand requires that the object to be added does not exist in the display profile. The add subcommand reads data for the new object from standard input or from the file specified as an argument to the command. Data for the new object must be XML and conform the Sun ONE Portal Server display profile DTD.
This XML data always requires a proper XML header as well as a set of names that uniquely defines which display profile object is to be modified. An example of proper XML header is:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
Note Appendix B contains the display profile DTD.
The semantics of the add subcommand vary depending on the type of the display profile object being added. That is:
- Display profile—An entire display profile document can be added to the specified LDAP node. If the document already exists at the node, then an error is reported. The parent option must not be specified when adding a new display profile document.
- Channel or container—A channel or container can be added. If the parent option is present, the parent display profile object is located for the given name and under that parent container, the specified channel or container is added. If the parent option is absent, the parent display profile object is assumed to be the root display profile object, so under root the specified channel or container object is added.
- Properties—Because a properties bundle is required for all display profile nodes and display profile provider objects, they already exist and cannot be added. Use the modify subcommand.
- Available or selected—Because available and selected objects are required for a display profile container, they already exist and cannot be added. Use the modify subcommand.
- String, Boolean, Integer, Collection, or Locale—The display profile object String, Boolean, Integer, Collection, or Locale properties can be added. The parent option must be specified to add display profile object properties of this type. Under the specified parent, a display profile node object (either a channel or container) or display profile provider is searched for (in that order) that matches the name. If found, the given display profile property is added to the display profile node object or display profile provider object.
The atomic display profile properties such as String, Boolean, and Integer need not be named. If unnamed, the name is assumed to be equal to the string representation of the value.
- Provider—A display profile provider is inserted under the root node. Because providers can only exist under the root node, do not use the parent option. If an object of the same name already exists, then an error is reported.
The add subcommand takes these options:
- Administrator's distinguished name and password for accessing the LDAP database (the -u or --runasdn and -w or --password options respectively). These options are required.
- Display profile document to add or the display profile document where the object must be added (the -d or --dn option). The display profile object to add defined by the -g or --global option for the global level node. The -g or -d option is required.
- Name of the file where the XML input is included (the file argument).
- Fully qualified name of the parent of the display profile node object to add or add to (the -p or --parent option).
- The -r or --dryrun option. This option runs a dryrun or test of the subcommand. Subcommands run with -r or --dryrun option report the error or success of the subcommand to sysout but do not make the subcommand changes to LDAP.
Syntax
$ dpadmin add -u|--runasdn uid -w|--password password {(-g|--global)|(-d|--dn dn)} [-p|--parent parent] [-r|--dryrun] file|<<EOF
$ dpadmin add -h|--help
The data supplied to the dpadmin add command is either from a file or from standard input (an XML fragment that follows the command).
Options
Table 12-4, which describes what options are supported, contains two columns: the first column lists the possible options, arguments or operands for the add subcommand; the second column gives a brief description.
Example
$ dpadmin add -p SampleTabPanelContainer/Postal -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp" <<EOF
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Collection name="zipCodes">
<Integer value="98012"/>
<Integer value="98036"/>
<Integer value="94025"/>
<Integer value="95112"/>
</Collection>
EOF
In this example, the command adds the collection property named zipCodes specified on standard input to the channel named Postal in the container named SampleTabPanelContainer.
remove
Description
This subcommand removes an existing display profile object from the display profile. If the object to be removed does not exist in the specified display profile document, an error is reported. This subcommand takes type, parent, and name options.
The type option specifies the type of display profile object to remove. The parent option specifies the fully qualified name of the parent display profile object to remove the display profile object from. The parent display profile object type varies depending on the type of display profile object being removed. The name option specifies the name of the object to remove.
The semantics of the parent and name options vary depending on the type of display profile object being removed. Table 12-5 contains two columns: the first column lists the possible values for the type options; the second column gives a brief description of exactly what is removed.
The remove subcommand takes these options:
- Administrator's distinguished name and password for accessing the LDAP database by using the -u or --runasdn and -w or --password options respectively. These options are required.
- Name of the display profile node object to remove by using the -n or --name option. This option is required except when type=root.
- Display profile document node in the LDAP database where the display profile document containing the object to be removed exists by using the -d (--dn) or -g (--global) option. Either the -d (--dn) or -g (--global) option is required.
- Type of display profile node object to remove by using the -t or --type option. This option is required.
- Fully qualified name of the parent of the display profile node object to remove by using the -p or --parent option.
- The -r or --dryrun option. This option runs a dryrun or test of the subcommand. Subcommands run with -r or --dryrun option report the error or success of the subcommand to sysout but do not make the subcommand changes to LDAP.
Syntax
$ dpadmin remove -u|--runasdn uid -w|--password password {(-g|--global)|(-d|--dn dn)} [-n|--name name] [-p|--parent parent][-r|--dryrun] -t|--type type
$ dpadmin remove -h|--help
Options
Table 12-6, which describes what options are supported, contains two columns: the first column lists the possible options, arguments or operands for the remove subcommand; the second column gives a brief description.
Examples
Example 1
$ dpadmin remove -t property -p Bookmarks -n locations -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
This example, the command removes the property named locations from the channel or container named Bookmarks.
Example 2
$ dpadmin remove -t provider -n "test1" -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -g
Remove the provider test1 from the global display profile
Example 3
$ dpadmin remove --type channel --parent TemplateTableContainer --name "Test" --runasdn "uid=amAdmin,ou=people,o=sesta.com,o=isp" --password joshua --dn "o=sesta.com,o=isp"
This example removes the channel named Test that is in the parent container named TemplateTableContainer.
Example 4
$ dpadmin list -n X -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
<Container name="X" ...>
<Channels>
<Container name="Y" ...>
<Channels>
<Channel name="z" .../>
</Channels>
</Container>
</Channels>
</Container>
To remove channel z, you can execute any of the following commands:
$ dpadmin remove -t channel -p X -n Y/z -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
$ dpadmin remove -t channel -p X/Y -n z -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
$ dpadmin remove -t channel -n X/Y/z -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -d "o=sesta.com,o=isp"
batch
Description
The batch subcommand enables the processing of multiple display profile commands in an optimized fashion. The subcommands are listed in a batch script file (required) and executed consecutively. If an error occurs, the default is to report the error and exit. The -c or --continue option denotes continuous processing mode. In this mode, if an error occurs, it is reported and dpadmin continues with the next subcommand.
The command batch scripts must be text (ASCII) documents and can contain any number of subcommands for input into dpadmin, except a batch subcommand. A subcommand must be entered on a single line (the new line character indicates the end of the command). For each subcommand, the administrator's distinguished name and password must be specified in the command line. The syntax for the subcommand is exactly the same as if the subcommand was entered directly into a shell (without the dpadmin part). The script cannot contain XML, so subcommands that require XML input must have it in a file. If the distinguished name (or DN) contains space(s), use double-quotes around it.
The following is an example batch-script file (each command is on a single line):
The batch subcommand takes the -c or --continue option and requires the name of the batch script file specified by using -f or --file.
Syntax
$ dpadmin batch [-c|--continue] -f|--file batch-script-file
$ dpadmin batch -h|--help
Options
Table 12-7, which describes what options are supported, contains two columns: the first column lists the possible options, arguments or operands for the batch subcommand; the second column gives a brief description.
Options
Table 12-8 summarizes the dpadmin command options supported. The table is organized by subcommands listed in subheads. It contains two columns: the first column lists the possible options, arguments or operands; the second column gives a brief description.
par
Description
The par command performs functions involving the specified .par file. It can be used for exporting and importing channels and/or providers from and into the Sun ONE Portal Server.
Syntax
The par command syntax is described in this section. Mixing long-named options with short ones in one command line is not recommended.
Short-Named Format
par containers -r uid -p password [-d] dn|global
par describe [-d] parfile
par export -r uid -p password [-m] [-d] [-v] parfile dn|global {exportfile|from=}...
par import -r uid -p password [-o] [-d] [-v] parfile [dn|global [op...]]
par import -r uid -p password -a [-d] [-v] parfile [dn|global]
Long-Named Format
par containers --runasdn uid --password password [--debug] dn|global
par describe [--debug] parfile
par export --runasdn uid --password password [--modify] [--debug] [--verbose] parfile dn|global {exportfile|from=}...
par import --runasdn uid --password password [--overwrite] [--debug] [--verbose] parfile [dn|global [op...]]
par import --runasdn uid --password password --auto [--debug] [--verbose] parfile [dn|global]
Subcommands
The following subcommands are supported:
containers
Description
Lists all available containers and channels in a particular display profile document, indicated by the specified directory server name (or global). This can be used as an aid to formulating other commands.
Syntax
par containers -r|--runasdn uid -p|--password password [-d|--debug] [-v|--verbose] dn|global
Example
par containers -r "uid=amAdmin,ou=people,o=sesta.com,o=isp" -p joshua -d "o=sesta.com,o=isp"
In this example, the command lists all available containers in the display profile document residing in the LDAP node "o=sesta.com,o=isp".
describe
Description
Describes the contents of the specified .par file, including the entries, and any built-in autoextract operations defined for the entries.
Syntax
par describe parfile
Example
par describe myfile.par
In this example, the command output or description of the myfile.par may be something like the following:
Class Root: /
Property Based File Root: /pbfiles
Display Profile Root: /dp
Static Content Root: /static
Entry: mychannel
AutoExtract:dpnode=o%3Dsesta.com%2Co%3Disp,channel,entry=mychann el
DP Document: this my JSP based channel.
Channel: SampleJSP.a
Includes: Property Based File, root templateBaseDir, path default/mychannel/samplecontent.jsp (channel)
Includes: Property Based File, root templateBaseDir, path default/mychannel/sampledoedit.jsp (channel)
Includes: Property Based File, root templateBaseDir, path default/mychannel/sampleedit.jsp (channel)
Includes: Property Based File, root templateBaseDir, path default_en_US/mychannel/samplecontent.jsp
(channel)
Includes: Property Based File, root templateBaseDir, path default_en_US/mychannel/sampledoedit.jsp
(channel)
Includes: Property Based File, root templateBaseDir, path default_en_US/mychannel/sampleedit.jsp
(channel)
export
Description
Populates the specified .par file by exporting the provider or channel information from the portal server. The command takes a .par file, a directory server name argument (or keyword global) corresponding to the desired display profile document to update, and any number of (requires at least one) exportfile or from specifications. The from specifications contain exactly the same information as an export file; the only difference is that the "lines" are separated by semicolons.
The par export command without the -m option creates a .par file. The par export command with the -m option is used to update and / or add to an already existing .par file that defines a provider, channel or container.
Syntax
par export -r|--runasdn uid -p|--password password [-d|--debug] [-v|--verbose] parfile dn|global {exportfile|from=}...
par export -r|--runasdn uid -p|--password password [-d|--debug] [-v|--verbose] -m|--modify parfile dn|global {exportfile|from=}...
Example
par export -r "uid=amAdmin,ou=people,o=sesta.com,o=isp" -p joshua mychannel.par "o=sesta.com,o=isp" myexport.txt
Here myexport.txt contains:
from: channel mychannel
directory: templateBaseDir . mychannel
description: this is my JSP based channel
In this example, the command exports the channel definition and template files for mychannel into mychannel.par from the "o=sesta.com,o=isp" dn. Also, if it were a JSPProvider channel, the directory line transfers all of the .jsp files, including locale-specific versions.
import
Description
Imports objects from the specified .par file into the portal server. The command takes a .par file, and optional arguments for the display profile document to import the objects into the indicated display node in the directory server (or the root display profile indicated by the keyword global), and operations to be performed. If these things are not specified, they are taken from the .par file. The auto option can be used to indicate that you wish to simply perform the autoextract operations already contained in the .par file.
To add a new channel, you can use the par import command with or without the -o option. If a channel already exists, you must use the -o option with the par import command to completely replace (overwrite) the old channel. You can use this subcommand to import providers as well as channels.
Syntax
par import -r|--runasdn uid -p|--password password [-o] [-d|--debug] [-v|--verbose] parfile [dn|global [op...]]
par import -r|--runasdn uid -p|--password password -a|--auto [-d|--debug] [-v|--verbose] parfile [dn|global]
Examples
Example 1
par import -r "uid=amAdmin,ou=people,o=sesta.com,o=isp" -p joshua --auto myfile.par "o=sesta.com,o=isp"
In this example, the command extracts the channel from myfile.par file, if that is the automatic operation defined in the myfile.par parfile.
Example 2
par import -r "uid=amAdmin,ou=people,o=sesta.com,o=isp" -p joshua myfile.par "o=sesta.com,o=isp" "entry=mychannel,channel=anothername,avail=topcontainer"
In this example, the command extracts the channel explicitly, installing it with a different name in the target dn, and making it available in container topcontainer.
Options
Table 12-9, which describes what options are supported in alphabetical order, contains two columns: the first column lists the possible options for the par command; the second column gives a brief description.
Arguments
Table 12-10, which describes what arguments are supported, contains two columns: the first column lists the possible arguments for the par command; the second column gives a brief description.
Table 12-10 par Command Arguments
Argument
Description
dn
Specifies the distinguished node in the directory server to access. Use the format "o=organizationName,o=organizationalUnit"
global
Specifies the global level node in LDAP to access the display profile document.
exportfile
These files each correspond to an entry (provider, channel, or provider/channel combination) in the .par file, and simply specify the data to be inserted into the specified .par file. It can be a small file if the information is too large to list on the command line. See Export Files for more information.
from
Specified on the command line, this is taken as equivalent to an export file containing the "from" line, followed by an equal to ("=") sign, and any other lines separated by a semicolon (";"). See from in Table 12-11 for more information on line properties.
op
Specifies the operation to perform. See Operations for more detail.
parfile
Specifies the par file to operate upon; that is, indicates the par file to import, export, or describe.
Export Files
These files simply specify data to be inserted into a .par file. The file consists of lines containing a keyword, followed by a colon and white space delimited fields. The line "from:" is required and it must be the first line of the file. Lines beginning with "#" are treated as comments.
Table 12-11, which describes the export file line properties, contains two columns: the first column lists the possible line keywords; the second column gives a brief description.
Operations
Each operation (op), in the export file or on the command line, must be specified as a comma separated list of keywords that can have values, most of which are optional. The operations are in a blank or space separated list. Each operation is in the following format.
dpnode=dn,entry=name,provider[=name],channel[=name],container=name[,av ail=name,selected]
dpnode
This specifies the distinguished name in the directory server (or the keyword global) for the display profile document that this operation is targeted at. May not apply if the context it is being specified in has already provided this. For example, if the import subcommand defines the distinguished name, the distinguished name in the file is ignored.
entry
This specifies the entry name in the .par file. This is not needed if the:
- .par file only contains one entry, as the operation defaults to that entry
- Operation is already associated with an entry such as the autoextract option for an entry.
The par utility defaults to the first entry in the file if an entry is not specified.
provider
This indicates that a provider extraction is to take place. If the name is missing, it uses the name packaged with the provider in the .par file.
channel
This indicates that a channel extraction is to take place. If the name is missing, it uses the name provided with the channel in the .par file.
container
This applies only to channel extractions and indicates which container the channel is to be inserted into. If omitted, the channel is inserted into the "channels" element at the display profile document root.
avail
This applies only to channel extractions and indicates a container whose "avail" (or available) list is to receive a reference to the new channel. If omitted, no new channel reference is created.
selected
This applies only if "avail" was used. It indicates that the container whose "avail" list received a reference, also has a reference placed in its "selected" list.
If the op information is in both the par import command and in the .par file, the command information takes precedence.
Par Files
This section contains supplemental information on the par file format. You do not require this information to run the par command.
The par file is a jar file with manifest entries for transporting channels, providers, and their associated files. It is intended allow flexibly when installing providers, channels, or both. The .par file contains 4 major types of files:
- XML documents containing the provider and or channel information for the display profile. This document is a parEntry , as described in the display profile DTD. This parEntry contains a channel, a provider, or a channel/provider combination.
- Class files associated with the provider or channel.
- Property based files. These are general files associated with the channel or provider (usually the channel), which have to be deployed underneath some configurable root on the portal server.
- Static content files. These are files deployed as documents on the web server.
Par File Contents
Table 12-12, which describes the headers the .par file must contain, contains two columns: the first column lists the required global headers; the second column gives a brief description.
The .par file must include a named entry for each parEntry XML file. Table 12-13, contains two columns: the first column lists the possible headers; the second column gives a brief description. The section for each named entry may contain the following headers:
If the .par file contains only one entry, entries need not be named in manipulating the file since the default entry is the entry used if none is named.
rwadmin
Description
The rwadmin command enables you to manage the Rewriter data available in the iPlanet Directory Server Access Management Edition Rewriter service.
Syntax
The rwadmin command syntax is described in this section.
Short Named Format
rwadmin list -u uid -w password [-l locale] [-b] [-h]
rwadmin store -u uid -w password [-l locale] [-b] [-h] filename
rwadmin get -r rulesetname -u uid -w password [-l locale] [-b] [-h] [filename]
rwadmin remove -r rulesetname -u uid -w password [-l locale] [-b] [-h]
Long Named Format
rwadmin list --runasdn uid --password password [--locale locale] [--verbose] [--version] [--help]
rwadmin store --runasdn uid --password password [--locale locale] [--verbose] [--version] [--help] filename
rwadmin get --rulesetid rulesetname --runasdn uid --password password [--locale locale] [--verbose] [--version] [--help] [filename]
rwadmin remove --rulesetid rulesetname --runasdn uid --password password [--locale locale] [--verbose] [--version] [--help]
Subcommands
These subcommands are supported:
list
Description
This command lists all the available ruleset names.
Syntax
rwadmin list -u|--runasdn uid -w|--password password
Example
rwadmin list -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua
In this example, the command displays names of all available rulesets.
store
Description
This command stores the rules available in the local file system into iPlanet Directory Server Access Management Edition. To store the DefaultRuleSet, use the following command:
rwadmin store -u uid -w password /resources/DefaultRuleSet.xml
where /resources/DefaultRuleSet.xml is the location of the ruleset stored in rewriter.jar file. When this command is executed, if a ruleset with the same ID already exists, no new data are stored. Delete the existing ID and try again.
Syntax
rwadmin store -u|--runasdn uid -w|--password password filename
Example
rwadmin store -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua /opt/data/ExampleRuleSet.xml
In this example, the command stores the rules available at /opt/data/ExampleRuleSet.xml into the iPlanet Directory Server Access Management Edition.
get
Description
This command gets the ruleset from iPlanet Directory Server Access Management Edition. If filename is provided, the retrieved ruleset is stored in the specified file, or else it is displayed on stdout (or the console).
Syntax
rwadmin get -r|--rulesetid ruleset -u|--runasdn uid -w|--password password [filename]
Examples
Example 1
rwadmin get -r "ExampleRuleSet" -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua
In this example, the command retrieves the ruleset named ExampleRuleSet from iPlanet Directory Server Access Management Edition and displays it on the console.
Example 2
rwadmin get -r "ExampleRuleSet" -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua /tmp/abc.xml
In this example, the command retrieves the ruleset named ExampleRuleSet from iPlanet Directory Server Access Management Edition and saves it in the file abc.xml in the /tmp directory.
remove
Description
This command deletes the ruleset from iPlanet Directory Server Access Management Edition. This command deletes the ruleset without any warning.
Syntax
rwadmin remove -r|--rulesetid ruleset -u|--runasdn uid -w|password password
Example
rwadmin remove -r "ExampleRuleSet" -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua
In this example, the command deletes the ruleset whose name is ExampleRuleSet from iPlanet Directory Server Access Management Edition.
Options
Table 12-14 summarizes the rwadmin command options supported in alphabetical order. It contains two columns: the first column lists the possible options; the second column gives a brief description.
rdmgr
Description
The rdmgr command is the main command to work with the Search service. There are two types of subcommands: ones that are used to work with resource descriptions (RDs); and ones that are used for database maintenance. The rdmgr command is normally run in a search-enabled portal server instance directory, which is the /server-instance-directory/deployment_uri directory. This is the deployment URI path you selected at install time. If you chose the default Portal Server install, this is the /var/opt/SUNWps/https-servername/portal directory.
Syntax
The general syntax of the rdmgr command is:
# rdmgr [subcommand] [options] [input]
The RD subcommands more specifically follow this syntax:
# rdmgr [-umgdnUL] [-ACSTNPq] [-a att,att,...] [-b number]
[-c search.conf] [-i charset] [-o charset] [-j number] [-l number]
[-p progress] [-r number] [-s schema] [-y dbname] [filename|-Q query]
The database maintenance subcommands more specifically follow this syntax:
# rdmgr [-OXIERGBL] [-ASTDVNP] [-a att,att,...] [-b number]
[-c search.conf] [-j number] [-l number] [-p progress] [-r number]
[-s schema] [-y dbname]
You can use -l number to set the log level number for any RD or database subcommand. A setting of 1 (default) logs all the rdmgr commands. The higher the number the more detail the log file contains. The possible levels are 1- 100. If this option is not specified, this command assumes the setting defined by the debug-loglevel in the search.conf file. The log file name is defined by the rdmgr-logfile in the search.conf file.
Where the -c search.conf option gives the location of the search.conf file. If you do not use this option, the default value is config/search.conf in the current directory. The search.conf file lists all the specific search values you have set.
You can use -p progress to show the progress of any RD or database subcommand. If you only enter -p, the progress is displayed on stdout.
Subcommands
The following subcommands are supported:
- Resource Description Subcommands
- Database Maintenance Subcommands
- Usage Message and Version Subcommands
Resource Description Subcommands
Description
The RD subcommands allow you to run a batch process to insert or replace RDs, merge RDs filtered by a view, retrieve RDs filtered by a view, delete RDs and count RDs. Table 12-15 is a two-column table that lists the subcommand in the first column with a brief description in the second column.
Syntax
# rdmgr [-umgdnUL] [-ACSTNPq] [-a att,att,...] [-b number]
[-c search.conf] [-i charset] [-o charset] [-j number] [-l number]
[-p progress] [-r number] [-s schema] [-y dbname] [filename|-Q query]
Options
Table 12-16, which describes the options supported, is a two-column table that lists the options or arguments in the first column with a brief description in the second column.
Note If you enter rdmgr with no subcommand, the command assumes the -u subcommand. If you enter rdmgr with no subcommand and a query (-Q), the command assumes the -g subcommand.
Examples
Example 1
Set environment variable LD_LIBRARY_PATH to /opt/SUNWps/lib.
In the /var/opt/SUNWps/https-sesta.com/portal directory, type
# /opt/SUNWps/bin/rdmgr -U
In this example, the entire default database of resource descriptions is printed out to stdout in UTF-8 SOIF format.
Example 2
In the default search directory of /var/opt/SUNWps/https-sesta.com/portal,
# /opt/SUNWps/bin/rdmgr -d -Q java
In this example, all the resource descriptions that have java any where in them are deleted.
Database Maintenance Subcommands
Description
The database subcommands allow an administrator to optimize a search database, to truncate or empty a database, to reindex a database, to delete expired RDs from a database, and recover a database. Table 12-17 is a two-column table that lists the subcommand in the first column with a brief description in the second column.
Syntax
# rdmgr [-OXIERGBL] [-ASTDVNP] [-a att,att,...] [-b number]
[-c search.conf] [-j number] [-l number] [-p progress] [-r number]
[-s schema] [-y dbname]
Options
Table 12-18, which describes what options are supported, is a two-column table that lists the options or arguments in the first column with a brief description in the second column.
Examples
Example 1
In the default search directory,
# /opt/SUNWps/bin/rdmgr -E -j 13 -p stdout -r 5
In this example, up to 13 RDs are removed from the database if they are expired. The progress report to stdout, prints the elapsed time in seconds and the number of RDs processed so far after every five resource descriptions.
Example 2
The Search engine is not responding. In the default search directory,
# /opt/SUNWps/bin/rdmgr -R
This recovers all the search databases and makes the Search Engine available again. Use this command to release stale locks in the database and to roll back incomplete data transactions. Stale locks and incomplete transactions can result from a database process being abnormally terminated.
Usage Message and Version Subcommands
Table 12-19 lists the subcommands to display the usage message or to view the version information in the first column and a brief description in the second column.
Table 12-19 rdmgr Subcommands for Usage Message and Version
Argument/Operand
Description
-h or -?
Shows the usage message.
-v
Shows version information
Return Codes
The rdmgr command returns return codes to the shell.
0 - Success
1 - Failure
sendrdm
Description
The sendrdm command provides a mechanism for a CGI or command-line based search. An rdm (resource description manager) request is sent in SOIF format to the Search server. This command is normally run in a search-enabled Portal Server instance directory, which is the /server-instance-directory/deployment_uri directory. This is the deployment uri path you selected at install time. If you chose the default Portal Server install, this is the /var/opt/SUNWps/https-servername/portal directory. Where the value of servername is the default Portal Server instance name—the fully qualified name of your Portal Server.
Note For the default installation, set the environment variable LD_LIBRARY_PATH to /opt/SUNWps/lib.
Syntax
The syntax of the sendrdm command is:
# sendrdm [-dv] [-t n] [-u uri] RDM-in [RDM-out]
Options
Table 12-20 summarizes sendrdm command options supported in alphabetical order. It contains two columns: the first column lists the possible options; the second column gives a brief description.
Example
In the /var/opt/SUNWps/https-servername/portal directory as root:
# /opt/SUNWps/lib/sendrdm -t 3600 -u /rdm/incoming rdmquery.soif result.soif
This example imports from a Compass Server 3.01x using /rdm/incoming as the uri with the timeout set to one hour. The content of rdmquery.soif is:
@RDMHEADER { -
catalog-service-id{48}: x-catalog://frankie.sesta.com:89/Compass-2
rdm-type{10}: rd-request
rdm-version{3}: 1.0
rdm-query-language{8}: gatherer
}
@RDMQUERY { -
scope{3}: all
}
StartRobot
The StartRobot script can be used by an administrator to start the robot manually. Usually this script is used by the scheduler to start the robot at set times (cron job). The StartRobot command is in the /var/opt/SUNWps/https-servername/portal directory.
Syntax
# StartRobot
Options
There are no options.