|
| |
| Sun Java System Portal Server 6 2004Q2 Administration Guide | |
Chapter 21
Command-Line UtilitiesThe Sun Java™ System Portal Server provides a set of command-line utilities in addition to its graphical user interface.
The command-line utilities discussed in this chapter are listed in Table 21-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. They are grouped by function: Desktop, Rewriter and Search.
Also available is the command-line interface amadmin for Sun Java System Identity Server administration. The primary purpose of the amadmin tool is to help an administrator perform batch administrative tasks on the Identity 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 Sun Java System Identity Server 6 2004Q2 Programmer’s Guide.
deployDescription
The deploy command packages the source files for the Sun Java System Portal Server web application files and deploys the package to the web container that hosts the portal server software.
The source files for the Sun Java System Portal Server are stored in the /opt/SUNWps/web-src directory. The WEB-INF/xml subdirectory contains web.xml fragment files that are combined by the deploy command to form the web.xml file for the Sun Java System Portal Server web application. The corresponding sections of the web.xml fragment files are combined based on the alphabetic order of the web.xml fragment files. Once the final web.xml file is formed, the files in the opt/SUNWps/web-src directory are put into a web application archive (WAR) file using the jar command. This WAR file is deployed to a web container using the deploy command.
Syntax
/opt/SUNWps/bin/deploy [redeploy]
Subcommands
The deploy command takes the redeploy subcommand. If the deploy command is invoked without the redeploy option, it prompts for configuration information from standard input.
redeploy
Description
The redeploy subcommand specifies that the deploy command reuse the Uniform Resource Indicator (URI) and other information assoicated with the Sun Java System Portal Server web application from the current deployment.
Syntax
deploy redeploy
pdeployDescription
The pdeploy is a command line tool that can be used to deploy and undeploy the portlet web application into the portal server.
The pdeploy command requires:
Some of the default settings used by the pdeploy command to deploy portlet applications are available in the PDConfig.properties file. This file is installed into the /etc/opt/SUNWps/portlet directory.
When the pdeploy command deploys the portlet application, it refers to the following parameters in the PDConfigure.properties file:
Syntax
This section describes the pdeploy command syntax.
Short-Named Format
pdeploy deploy -u uid -w password {-g|-d dn} -p webcontainerpassword -V -r rolesfile -f userinfofile -v -l warfile
pdeploy undeploy -u uid -w password {-g|-d dn} -p webcontainerpassword -V -v -l warfile
Long-Named Format
pdeploy deploy --runasdn uid --password password {--global|--dn dn} --wc_password webcontainerpassword --rolesfile rolesfile --userinfofile userinfofile --verbose --locale warfile
pdeploy deploy --help
pdeploy deploy --version
pdeploy undeploy --runasdn uid --password password {--global|--dn dn} --wc_password password --verbose --locale portletwebapp
pdeploy undeploy --help
pdeploy undeploy --version
Subcommands
The pdeploy command takes these subcommands:
deploy
Description
If the subcommand is deploy, the pdeploy command deploys the portlet web application into the portal server. After this command completes, you can create channels based on the portlets defined in the deployed portlet web application.
Syntax
pdeploy deploy -u uid -w password {-g|-d dn} -p webcontainerpassword warfile
pdeploy deploy -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 deploy subcommand; the second column gives a brief description.
Table 21-3 deploy Subcommand Operands
Operand
Description
warfile
Specifies the path to the war file.
Examples
In the following example, the pdeploy command deploys the /tmp/SamplePortletApp.war into the portal server.
pdeploy deploy -u “uid=amAdmin,ou=people,o=sesta.com,o=isp” -w admin -p sunone -g /tmp/SamplePortletApp.war
Sometimes the portlet application defines logical roles in the portlet.xml file. During deployment, the logical roles need to be mapped to the actual roles defined in the system. To accomplish this, supply a role mapping file.
The role mapping file is expected to contain ActualRole=LogicalRole entries. The file supplied must follow Java™ porperty file format. For example:
cn\=HRManager,dc\=iplnaet,dc\=com=Manager
cn\=Emp,dc\=iplnaet,dc\=com=Employee
The following pdeploy command will provide the role mapping file for deploying the SamplePortletApp.war file into the portlet application.
pdeploy deploy -u “uid=amAdmin,ou=People,o=sesta.com,o=isp” -w admin -p sunone -r /tmp/RoleMaps -g /tmp/SamplePortletApp.war
Sometimes the portlet application will need access to the information associated with each user. During deployment, logical user information entry name must be mapped to the actual user information entry name defined in the system. To accomplish this during deployment, a user information entry map can be supplied.
The user information file is expected to contain ActualEntryName=LogicalEntryName entries. For example:
lastname=lname
firstname=fname
The following deploy command will provide the user information file for deploying the SamplePortletApp.war file into the portlet application.
pdeploy deploy -u “uid=amAdmin,ou=People,o=sesta.com,o=isp” -w admin -p sunone -f /tmp/UserInfoMaps -g /tmp/SamplePortletApp.war
undeploy
Description
The undeploy subcommand removes the portlet application from the portal server. However, it does not remove all the channel definitions already created for portlets defined in the portlet web application. All channels associated with the portlet web application (being removed) must be manually removed.
Syntax
pdeploy undeploy -u uid -w password {-g|-d dn} -p webcontainerpassword -v portletwebapp
pdeploy undeploy -h|--help
Options
Table 21-4 and Table 21-5 describes what options are supported and contains two columns: the first column lists the possible options, arguments, or operands for the undeploy subcommand; the second column gives a brief description.
The following pdeploy command undeploys the portlet web application named SamplePortletApp from the portal server.
pdeploy undeploy -u “uid=amAdmin,ou=People,o=sesta.com,o=isp” -w admin -g
dpadminDescription
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|merge|modify|add|remove [command-specific options] -u uid
-w password {-g|-d dn} [-l locale] [-r] [-b] [-V] [-h] [file]$ dpadmin batch [-c] -f batch-script-filename [-l locale] [-b] [-h]
Long-Named Format
$ dpadmin list|merge|modify|add|remove [command-specific options] --runasdn uid --password password {--global|--dn dn} [--locale locale] [--dryrun] [--verbose] [--version] [--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.
- Name of the display profile node object to display by using the -n or --name option.
- 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, it displays the entire display profile document. The -g or --global option displays the entire root display profile document.
Syntax
$ dpadmin list -u|--runasdn uid -w|--password password {(-g|--global)|(-d|--dn dn)} [-n|--name name]
$ dpadmin list -h|--help
Options
Table 21-6 contains two columns: the first column lists the possible options, arguments or operands for the list subcommand; the second column gives a brief description. The following options are supported:
Examples
Example 1
$ dpadmin list -n TemplateTableContainer -u "uid=amAdmin,ou=people,dc=org,dc=com" -w joshua -d "dc=org,dc=com"
This example gets the named TemplateTableContainer from the dc=org,dc=com organization node and prints it to standard out.
Example 2
$ dpadmin list -n mailcheck -u "uid=amAdmin,ou=people,dc=org,dc=com" -w joshua -g
This example goes to the global level only to get mailcheck and if found, prints it to standard out.
Example 3
$ dpadmin list -n TemplateTableContainer/Bookmark2 -u "uid=amAdmin,ou=people,dc=org,dc=com" -w joshua -d "dc=org,dc=com"
This example gets the channel named Bookmark2 located in the container TemplateTableContainer and prints it to standard out.
merge
Description
This subcommand retrieves and displays the merged result of the specified DP node objects. Objects are displayed in their native XML format. The object to be displayed is sent to standard out. If you do not use the -n or --name option, then an error is reported.
The merge command accepts the following arguments:
--name or -n
The name argument specifies the fully-qualified name of the DP container, channel, or provider object to display. If the name argument is absent, then the entire DP document is displayed. If the name argument does not identify a DP node object, then an error is reported.
Note
The merge subcommand merely displays the merged view of the object and does not persist the result. The underlying data does not get affected by running this subcommand.
Examples
$ dpadmin list -n “Bookmark” \
-u “uid=amAdmin,ou=People,dc=iplanet,dc=com” -w joshua \
-d “dc=iplanet,dc=com”
<Channel name=”Bookmark” provider=”BookmarkProvider”>
<Properties merge=”fuse” lock=”false” name=”_properties”>
<String name=”title” value=”My Bookmarks” merge=”replace” lock=”false”/>
<String name=”refreshTime” value=”600” merge=”replace” lock=”false”/>
<Collection name=”targets” merge=”fuse” lock=”false”>
<String value=”Sun home page|http://www.sun.com” merge=”replace” lock=”false”/>
<String value=”Everything you want to know about Sun Java System...|http://www.sun.com/software/products/portal_srvr/home_portal.htm l” merge=”replace” lock=”false”/>
<String value=”Sun Java System home page|http://www.sun.com/software” advanced=”false” merge=”replace” lock=”false”/>
</Collection>
</Properties>
</Channel>
$ dpadmin list -n “Bookmark” \
-u “uid=amAdmin,ou=People,dc=iplanet,dc=com” -w joshua \
-d “cn=HR Role,dc=iplanet,dc=com”
<Channel name=”Bookmark” provider=”BookmarkProvider”>
<Properties merge=”fuse” lock=”false” name=”_properties”>
<String name=”title” value=”HR Admin Bookmarks” merge=”replace” lock=”false”/>
<Collection name=”targets” merge=”fuse” lock=”false”>
<String value=”HR Admin home page|http://hr.acme.com” merge=”replace” lock=”false”/>
</Collection>
</Properties>
</Channel>
$ dpadminmerge -n “Bookmark” \
-u “uid=amAdmin,ou=People,dc=iplanet,dc=com” -w joshua \
-d “uid=hradmin,ou=people,dc=iplanet,dc=com”
<Channel name=”Bookmark” provider=”BookmarkProvider”>
<Properties merge=”fuse” lock=”false” name=”_properties”>
<String name=”title” value=”HR Admin Bookmarks” merge=”replace” lock=”false”/>
<Collection name=”targets” merge=”fuse” lock=”false”>
<String value=”Sun home page|http://www.sun.com” merge=”replace” lock=”false”/>
<String value=”Everything you want to know about Sun Java System ...|http://www.sun.com/software/products/portal_srvr/home_portal.html” merge=”replace” lock=”false”/>
<String value=”Sun Java System home page|http://www.sun.com/software” advanced=”false” merge=”replace” lock=”false”/>
<String value=”HR Admin home page|http://hr.acme.com” merge=”replace” lock=”false”/>
</Collection>
<Collection name=”GlobalThemes” merge=”fuse” lock=”false”>
<Collection name=”theme1” merge=”fuse” lock=”false”>
<String name=”description” value=”Sun Java System” merge=”replace” lock=”false”/>
...
</Collection>
</Collection>
<Collection name=”locales” merge=”fuse” lock=”false” propagate=”true” advanced=”false”>
<String name=”en_US” value=”English (United States)” merge=”replace” lock=”false”/>
</Collection>
<String name=”docroot” value=”/docs/” merge=”replace” lock=”false”/>
<String name=”helpURL” value=”desktop/usedesk.htm” merge=”replace” lock=”false”/>
</Properties>
</Channel>
This is the merged result of the Bookmark channel for the userhradmin who is assigned to the HR Role.
modify
Description
This subcommand changes the value of an existing display profile object. The data that is supplied to the dpadmin modify command is either from one or more input files or from standard input (an XML fragment that follows the command).
This XML data always requires a proper XML header as well as a nams 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.
- 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 (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 replaced 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. Since 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 -m or --combine 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] [-m|--combine] file|EOF
$ dpadmin modify -h|--help
Options
Table 21-7 contains two columns: the first column lists the possible options, arguments or operands for the modify subcommand; the second column gives a brief description. The following options are supported:
Examples
Example 1
$ dpadmin modify -p TemplateTableContainer -u "uid=amAdmin,ou=people,dc=org,dc=com" -w joshua -d "dc=org,dc=com" <<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
In this example, modify (replace) 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,dc=org,dc=com" -w joshua -d "dc=org,dc=com" farble.xml
In this example, in the channel NewNews, replace 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,dc=org,dc=comp" -w joshua -d "dc=org,dc=com"
...
<Collection name="news">
<Collection name="bar">
<String name="msg" value="hi"/>
</Collection>
</Collection>
...
$ dpadmin modify -p TemplateTableContainer -u "uid=amAdmin,dc=org,dc=com" -w joshua -d "dc=org,dc=com" -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,dc=org,dc=com" -w joshua -d "dc=org,dc=com"
...
<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,dc=org,dc=com" -w joshua -d "dc=org,dc=com"
<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,dc=org,dc=com" -w joshua -d "dc=org,dc=com" -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,dc=org,dc=com" -w joshua -d "dc=org,dc=com"
<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 value 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.
Example 5
$ dpadmin list -n test \
-u "uid=amAdmin,ou=People,dc=iplanet,dc=com" -w joshua \
-d "dc=iplanet,dc=com"
<Channel name="test" provider="testprovider">
<Properties>
<Collection name="foo">
<String name="foo1" value="bar"/>
</Collection>
</Properties>
</Channel>
$ dpadmin modify -p test \
-u "uid=amAdmin,ou=People,dc=iplanet,dc=com" -w joshua \
-d "dc=iplanet,dc=com" -m <<EOF
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<ConditionalProperties condition="client" value="nokia">
<Collection name="foo">
<String name="foo1" value="nokia bar"/>
</Collection>
</ConditionalProperties>
EOF
$ dpadmin list -n test \
-u "uid=amAdmin,ou=People,dc=iplanet,dc=com" -w joshua \
-d "dc=iplanet,dc=com"
<Channel name="test" provider="testprovider">
<Properties>
<Collection name="foo">
<String name="foo1" value="bar"/>
</Collection>
<ConditionalProperties condition="client" value="nokia">
<Collection name="foo">
<String name="foo1" value="nokia bar"/>
</Collection>
</ConditionalProperties>
</Properties>
</Channel>
$ dpadmin modify -p test \
-u "uid=amAdmin,ou=People,dc=iplanet,dc=com" -w joshua \
-d "dc=iplanet,dc=com" -m <<EOF
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<ConditionalProperties condition="client" value="nokia">
<ConditionalProperties condition="locale" value="en">
<String name="abc" value="nokia en abc"/>
</ConditionalProperties>
</ConditionalProperties>
EOF
$ dpadmin list -n test \
-u "uid=amAdmin,ou=People,dc=iplanet,dc=com" -w joshua \
-d "dc=iplanet,dc=com"
<Channel name="test" provider="testprovider">
<Properties>
<Collection name="foo">
<String name="foo1" value="bar"/>
</Collection>
<ConditionalProperties condition="client" value="nokia">
<Collection name="foo">
<String name="foo1" value="nokia bar"/>
</Collection>
<ConditionalProperties condition="locale" value="en">
<String name="abc" value="nokia en abc"/>
</ConditionalProperties>
</ConditionalProperties>
</Properties>
</Channel>
In this example, the Combine option is used to add conditional properties.
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 one or more files specified as an argument to the command. Data for the new object must be XML and conform the Sun Java System Portal Server display profile DTD.
This XML data always requires a proper XML header as well as a name 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 (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 or display profile provider.
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 where the display profile node object is to be added to (the -p or --parent option).
Syntax
$ dpadmin add -u|--runasdn uid -w|--password password {(-g|--global)|(-d|--dn dn)} [-p|--parent parent] file|<<EOF
$ dpadmin add -h|--help
Options
Table 21-8 contains two columns: the first column lists the possible options, arguments or operands for the add subcommand; the second column gives a brief description. The following options are supported:
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 21-9 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.
Syntax
$ dpadmin remove -u|--runasdn uid -w|--password password {(-g|--global)|(-d|--dn dn)} [-n|--name name] [-p|--parent parent] -t|--type type
$ dpadmin remove -h|--help
Options
Table 21-10 contains two columns: the first column lists the possible options, arguments or operands for the remove subcommand; the second column gives a brief description. The following options are supported:
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"
In this example, the command removes the property named locations from the channel or container named Bookmarks.
Example 2
$ dpadmin remove -t provider -n "pctest" -u "uid=amAdmin,ou=people,o=sesta.com,o=isp" -w joshua -g
Remove the provider pctest 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"
In this example, the command 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.
Example batch-script file (each command is on a single line):
add -p PostalMailer -u uid=amAdmin,ou=People,dc=iplanet,dc=com -w joshua -d dc=iplanet,dc=com zipCodes.xml
add -p PostalStamps -u uid=amAdmin,ou=People,dc=iplanet,dc=com -w joshua -d dc=iplanet,dc=com zipCodes.xml stampRates.xml
add -p PostalRates -d "cn=hr role,dc=iplanet,dc=com" zipCodes.xml stampRates.xml
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] -u|--runasdn uid -w|--password password -f|--file batch-script-file
$ dpadmin batch -h|--help
Options
Table 21-11 contains two columns: the first column lists the possible options, arguments or operands for the batch subcommand; the second column gives a brief description. The following options are supported:
Options
Table 21-12 is a summary of the dpadmin command. 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. The following options are supported:
parDescription
The par command performs functions involving the specified .par file. It can be used for exporting and importing channels or providers to and from the Sun Java System 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] -s staticdir [-v] parfile dn|global {exportfile|from=}...
par import -r uid -p password [-o] [-d] -s staticdir [-v] parfile [dn|global [op...]]
par import -r uid -p password -a [-d] -s staticdir [-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] --staticdir staticdir [--verbose] parfile dn|global {exportfile|from=}...
par import --runasdn uid --password password [--overwrite] [--debug] --staticdir staticdir [--verbose] parfile [dn|global [op...]]
par import --runasdn uid --password password --auto [--debug] --staticdir staticdir [--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:
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] -s|--staticdir staticdir [-v|--verbose] parfile dn|global {exportfile|from=}...
par export -r|--runasdn uid -p|--password password [-d|--debug] -s|--staticdir staticdir [-v|--verbose] -m|--modify parfile dn|global {exportfile|from=}...
Example
par export -r "uid=amAdmin,ou=people,dc=sesta,dc=com" -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 "dc=sesta,dc=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.
If you want 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] -s|--staticdir staticdir [-v|--verbose] parfile [dn|global [op...]]
par import -r|--runasdn uid -p|--password password -a|--auto [-d|--debug] -s|--staticdir staticdir [-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 21-13 contains two columns: the first column lists the possible options for the par command; the second column gives a brief description. This command supports the following options (listed in alphabetical order):
Table 21-13 par Command Options
Options
Description
-a or --auto
Use with the import command to apply the autoextract operations from the .par file. There should be no operations specified on the command line in this case. The dn argument may still be specified; if specified, it replaces the dn in the autoextract operations. If operations are specified on the command line they are ignored.
-d or --debug
Specify this to produce extra debugging information on error messages.
-m or --modify
Use with the export command to update an existing .par file rather than replace it. Any new files added for an entry supplement or replace the old ones. Also, use this command to add new files to an existing provider or channel by using a .par file.
-o or --overwrite
Use with the import command to replace existing channels.
-p or --password
Specifies the password for authentication. Required for all of the subcommands except describe. If not specified, the par utility prompts for it.
-r or --runasdn
Specifies the distinguished name of the user for authentication. Required for all of the commands except describe. If not provided, the par utility prompts for it. Use the format uid=userName,ou=people,o=organizationName,o=organizationalUnit
-s or --staticdir
Defines the host-specific directory of the static content directory to be used for import or export.
-v or --verbose
Describes operations as they are executed. Use with the import and export commands.
-V or --version
Specify this option to par to print descriptive information about the utility, such as its version, legal notices, and other similar information to standard output. Any subcommand and all other options are ignored when this option is present.
-?
Obtain help for any subcommand.
Arguments
Table 21-14 contains two columns: the first column lists the possible arguments for the par command; the second column gives a brief description. This command takes the following arguments:
Table 21-14 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 21-15 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 21-15 contains two columns: the first column lists the possible line keywords; the second column gives a brief description.
Table 21-15 Export File Line Properties
Line
Description
from: types name
“from” indicates what entity is being exported. types can be “channel”, “provider”, or “channel,provider”, and “channel+provider”. The name indicates the channel name, or a provider name if a provider is being exported. The name must be URL encoded if the name contains white space (+), commas (%2C), colons (%3A), semicolons (%3B), plus signs (%2B), or percent signs (%25).
auto: none
"auto" specifies the autoextract operation for the entry. It takes the op argument followed by the operation. "none" can also be entered, suppressing the autoextract. If no "auto:" line is specified, a default autoextract is produced. The default operation is to extract the channel and/or provider with its original names.
auto: op
file: root|. path [types]
"file" indicates that a file, based on a property setting, is to be included. The property can come from either the "desktop properties" file, located by default in /etc/opt/SUNWps/desktop/desktopconfig.properties file or from the display profile visible to a getProperty() call for the item being exported or imported. root specifies the root of the file location and path specifies the path to the rest of the file. root is a property name that corresponds to a directory (like). If root is given as ".", the file is assumed to be static content located at the web server’s doc root. You can also specify the types of operation the file is to be associated with, defaulting to "channel". types can be “channel”, “provider”, or “channel,provider”, and “channel+provider”.
class: class [types]
"class" indicates that a class file is to be packaged with the entry, and you may optionally specify the types of operations that the class file are associated with. If not specified, "provider" is assumed. types can be "channel", "provider", or "channel,provider", and "channel+provider"; also, when specifying both, you can use a space.
directory: root|. dir +|.|filter [types]
"directory" implies an entire directory search with all non-directory files to be included as if entered as "file" lines. It includes the capability of specifying a "filter", that is a directory component which must be present in recursive directory searches. root specifies the root of the directory, or "." to indicate static content. dir is the directory underneath the root to search from, which can be given as "." to start at the root itself. filter specifies the filter component which must be in the directory, which implies a recursive descent. It can be given as "+" for a recursive descent with no filter, or "." for no recursive descent (just the contents of the actual directory). You can also specify the types of operation, which default to "channel". types can be “channel”, “provider”, or “channel,provider”, and “channel+provider”.
entry: name
"entry" specifies the entry name used in the .par file. If not specified, it defaults to the name from the "from: " line.
desc: text
Any number of "desc" lines may appear, and are concatenated together as a user-visible description packaged with the entry.
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[,avail=nam e,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:
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 simply 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 simply 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 and/or channel.
- Property based files. These are general files associated with the channel, portlet, 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 21-16 contains two columns: the first column lists the required global headers; the second column gives a brief description. The .par file must contain the following headers:
Table 21-16 Global Headers
Header
Description
PS-Version
Specifies a portal server specific version number of the .par file. Also verifies that this is a .par file.
PS-DefaultEntry
Names the entry used for operations involving an unnamed entry.
PS-DPRoot
Indicates the root directories in the archive for parEntry documents, classes, property based files, and static content, respectively. If unspecified, the corresponding files are rooted at the top of the archive.
PS-ClassRoot
PS-PBFileRoot
PS-StaticRoot
In the .par file, there must be a named entry for each parEntry XML file. Table 21-17 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:
Table 21-17 Named Entry Headers
Header
Description
PS-EntryName
Specifies the command visible name of the entry.
PS-AutoExtract
Specifies the autoextract operation for the entry, if one exists.
PS-Include
Contains a comma separated list of archived files specified by their actual archive path. The path implies what type of file they are according to the "root" specifications. The files are appended with a parenthesized number which corresponds to the types of operations the file applies to (a mask with 1 for provider, 2 for channel). This can be ignored if there are no files other than the XML document associated with the entry.
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.
rwadminDescription
The rwadmin command enables the administrator to manage the Rewriter data available in the Sun Java System Identity Server 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 Sun Java System Identity Server. If you want 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 RuleSet stored in rewriter.jar file. Note that when this command is executed, if a ruleset with the same ID already exists, no new data is 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 Sun Java System Identity Server.
get
Description
This command gets the RuleSet from Sun Java System Identity Server. If the 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 Sun Java System Identity Server 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 Sun Java System Identity Server. 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 Sun Java System Identity Server.
Options
Table 21-18 is a summary of the rwadmin command. It contains two columns: the first column lists the possible options; the second column gives a brief description. The command supports the following options (listed in alphabetical order):
Table 21-18 rwadmin Command Options
Option
Description
-b or --verbose
Specify this argument to rwadmin to provide detailed information what is happening when the command is executed
filename
Specify this option with the store subcommand to indicate the file to get the RuleSet data from when importing into the Sun Java System Identity Server. Specify this with the get subcommand to indicate the file in which the retrieved RuleSet data should be stored.
-h or --help
Specify this option to rwadmin to print out a brief help page to standard output. If no subcommand is present, a generic help page for rwadmin is printed. If one of the rwadmin subcommands is present, then a brief help page that is specific to the subcommand is printed.
-l or --locale
Use this option to have all output messages localized in the specified locale. If not specified, it defaults to system locale.
-r or --rulesetid
Use this option to specify the name of the RuleSet to operate upon
-u or --runasdn
Specify this option with the distinguished name of the user to use to bind to the Directory Server.
--version
Specify this option to rwadmin to print descriptive information about the utility, such as its version, legal notices, and other similar information to standard output. Any subcommand and all other arguments are ignored when this option is present.
-w or --password
Specify this option with the password of the distinguished name of the user used to bind to the Directory Server.
rdmgrDescription
The rdmgr command is the main command used to work with the Search service. It gives the administrator 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. Where the value of the servername is the default Portal Server instance name—the fully qualified name of your Portal Server.
Syntax
The general syntax of the rdmgr command is:
The RD subcommands more specifically follow this syntax:
The database maintenance subcommands more specifically follow this syntax:
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
Description
The RD subcommands allow an administrator 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 21-19 is a two-column table that lists the subcommand in the first column with a brief description in the second column.
Table 21-19 rdmgr RD Subcommands
Subcommand
Description
-u
Insert or replace RDs. This subcommand is the default subcommand if none is stated.
-m
Merge RDs filtered by a view.
-g
Retrieve RDs filtered by a view.
-d
Delete RDs.
-n
Count the RDs
-U
Dump database in SOIF to stdout.
-L
Lists selected fields from the database to stdout. Requires the -a att option.
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 21-20 is a two-column table that lists the options or arguments in the first column with a brief description in the second column. The following options are supported:
Table 21-20 Options for rdmgr RD Subcommands
Argument/Operand
Description
-A
Do not use schema aliases in config/schema.rdm file in the default search directory. Use with the u and m subcommands.
-C
Do not create database if database is missing. Use with the u and m subcommands.
-S
Disable schema checking. Use with the u and m subcommands.
-T
Operate on the taxonomy. The taxonomy is used for browsing and classifying the database contents and is in the config/taxonomy.rdm file in the default search directory. Use with any resource description command.
-N
The function you specified in the command works only on the non-persistent data in the resource description. RDs in the database are a merge of persistent and non-persistent data.
-P
The function you specified in the command works only on the persistent data in the resource description. RDs in the database are a merge of persistent and non-persistent data.
-q
Delete SOIF input file on exit. Use with the u, m, g and d subcommands.
-a att,att...
Specifies attribute view list. The att names are not case sensitive and can be any attribute whether or not they are defined in the schema; for example, author or title. If you have a multi-valued att like class-1, class-2, and class-3, only enter class as the att name.
-b number
Set the indexing batch size to this number of RDs. Use with the u and m subcommands.
-c search.conf
Specify where the search.conf file is. If you do not use this option, the default is the config/search.conf file in the default search directory. Other wise, you have to give the full path to the file.
-i charset|-o charset
The -i option specifies the character set of the input SOIF stream. The -o option specifies the character set of the output SOIF stream. For example, ISO8859-1, UTF-8, UTF-16. Character sets ISO8859-1 through ISO8859-15 are supported. Use -i with the u, m and d subcommands. Use -o with the g, U and L subcommands.
-j number
Limits the number of retrieved results. Use with the u subcommand. If not stated, the default value is unlimited except with the Q option (default 20).
-l number
Set log level to number. 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. This works with all subcommands.
-p {stdout|stderr|
filename}
Prints or displays progress to stdout, stderr or the filename file. This works with all subcommands. Timing information is reported in seconds.
-r number
Use with the progress option. A report is generated every number of RDs. The default is 500. Use with the u, m, g, d and U subcommands.
-s schema
Specifies the schema definition file. If you do not use this option, the default is the config/schema.rdm file in the search server instance directory.
-y dbname
Specifies the search database name. If you are running this command on any database other than the default one, you need to use this option. The default database is the database defined in the config/search.conf file labeled datbase-name=logicaldbname.
filename|-Q query
This input option is used with the u, m, g and d subcommands.
The filename is a file of RDs using the default schema (use -s option for any other schema) in SOIF format:
The query is any regular search query.
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 21-21 is a two-column table that lists the subcommand in the first column with a brief description in the second column.
Table 21-21 rdmgr Database Maintainance Subcommands
Subcommands
Description
-O
Optimize the database. If you are running this subcommand on any database other than the default one, you need to use the -y option. The default database is the database defined in the config/search.conf file labeled datbase-name=logicaldbname. For example, the default value is datbase-name=default and the default database directory is db/default.
Databases do not normally need to be optimized.
-X
Truncate or empty a database. If you are running this subcommand on any database other than the default one, you need to use the -y option. Disk space used for indexes is recovered, but disk space used by the main database is not recovered, instead, it is reused as new data is added to the database.
-I
Reindex a database. If you are running this subcommand on any database other than the default one, you need to use the -y option.
-E
Delete expired RDs from a database. If you are running this subcommand on any database other than the default one, you need to use the -y option.
-R
Recover all databases. This is a global command and takes no options. All database processes, including other rdmgr instances and the main search server must be stopped before running this command.
-G
Repartition the database. This command takes no options. The partitions are defined in the config/search.conf file labeled datbase-partitions=p1,p2,p3,.... where p1, p2, and p3 are the filenames of the partitions. The server needs to be restarted after running this command.
-B
Completely deletes the database. Recovers all the disk space. There should be no indexing happening and the Portal server has to be off when you run this subcommand.
-L
Lists selected fields from the database to stdout. Requires the -a att option. If you are running this subcommand on any database other than the default one, you need to use the -y option.
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 21-22 is a two-column table that lists the options or arguments in the first column with a brief description in the second column. The following options are supported:
Table 21-22 Options for rdmgr Database Maintenance Subcommands
Argument/Operand
Description
-A
Do not use schema aliases in config/schema.rdm file in the default search directory. Use with the I subcommand.
-S
Disable schema checking. Use with the I subcommand.
-T
Operate on the taxonomy. The taxonomy is used for browsing and classifying the database contents and is in config/taxonomy.rdm file in the default search directory. Use with O, X, I, E, B, U, and L subcommands.
-D
Update the database only; do not update the index. Use with E and X commands.
-V
Update the index only; do not update the database. Use with E and X commands.
-N
The function you specified in the command works only on the non-persistent data in the resource description. RDs in the database are a merge of persistent and non-persistent data. Use with I, E, U, and L commands.
-P
The function you specified in the command works only on the persistent data in the resource description. RDs in the database are a merge of persistent and non-persistent data. Use with I, E, U, and L commands.
-a att,att...
Specifies attribute view list. The att names are not case sensitive and can be any attribute whether or not they are defined in the schema; for example, author or title. If you have a multi-valued att like class-1, class-2, and class-3, only enter class as the att name.
-b number
Set the indexing batch size to this number of RDs. Use with the I command.
-c search.conf
Specify where the search.conf file is. If you do not use this option, the default is the config/search.conf file in the default search directory. Other wise, you have to give the full path to the file.
-j number
Limits the number of retrieved results. Use with the E subcommand. If not stated, the default value is unlimited.
-l number
Set log level to number. A setting of 1 (default) logs all the rdmgr commands. The higher the number the more detail the logfile contains. The possible levels are 1- 100. This works with all subcommands.
-p {stdout|stderr|
filename}Prints or displays progress to stdout, stderr or filename. This works with all subcommands.
-r number
Use with the progress option. A report is generated every number of RDs. The default is 500. Use with the u, m, g, d and U subcommands.
-s schema
Specifies the schema definition file. The default is the config/schema.rdm file in the default search directory.
-y dbname
Specifies the search database name. If you are running this command on any database other than the default one, you need to use this option. You do not need to use this option for the default database. The default database is the database defined in the config/search.conf file labeled datbase-name=filename.
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 ‘hung’ or 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 21-23 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 21-23 rdmgr Subcommands for Usage Message and Version
Argument/Operand
Description
-h or -?
Show the usage message.
-v
Show version information
Return Codes
The rdmgr command returns return codes to the shell.
0 - Success
1 - Failure
sendrdmDescription
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 the servername is the default Portal Server instance name—the fully qualified name of your Portal Server.
Syntax
The syntax of the sendrdm command is:
Options
Table 21-24 is a summary of the sendrdm command. It contains two columns: the first column lists the possible options; the second column gives a brief description. The command supports the following options (listed in alphabetical order):
Table 21-24 sendrdm Command Options
Argument/Operand
Description
-d
Debug mode. The default is off. This option turns it on.
-t n
Specifies time in seconds. Command times out after n seconds. Default is 300 seconds.
-u uri
Designates the uri directory (enter full path) for the server you are importing from.
-v
Version.
RDM-in
The RDM request file name. This is a required argument.
RDM-out
The RDM result file name. The default is standard out.
Example
In the /var/opt/SUNWps/https-servername/portal directory as root:
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:
Code Example 0-1
@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
}
StartRobotThe 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.
StopRobot
The StopRobot script can be used by an administrator to stop the robot manually. Usually this script is used by the scheduler to stop the robot at set times (cron job). The StopRobot command is in the /var/opt/SUNWps/https-servername/portal directory.
Syntax
# StopRobot
Options
There are no options.