Sun Java System Portal Server 7.1 Command Line Reference

Chapter 2 Desktop Subcommands

This chapter describes the following subcommands:

`psadmin get-attribute`

Description

Gets the portal attribute for a base dn or from global or default levels.

Syntax

Long Format

psadmin get-attribute --component desktop -attribute-name attribute-name --adminuser uid --passwordfile password-filename [--dn dn] -portalid portal-ID [--output output-file] [--debug]

Short Format

psadmin get-attribute -m desktop -a attribute-name -u uid -f password-filename [-d dn] -p portal-ID [-o output-file]

Options

The following options are required:

[--adminuser | -u] uid: Specifies the administrator's distinguished name.
[--attribute-name | -a] attribute-name: Specifies the desktop attribute name for which the value is to be retrieved. User friendly desktop attributes can be fetched from the list-attribute subcommand, with component name as desktop.
[--component | -m] desktop: Always desktop for this module.
[--passwordfile | -f] password-filename: Specifies the administrator's password in the password file.
[--portalId | -p] portal-ID: Specifies the portal ID.

The following options are optional:

--debug: Used for debugging purpose only. By default, this is set to false. Set this flag to true to see exceptions that caused the error.
[--dn | -d] dn: Specifies the distinguished name for whom desktop attribute is to be retrieved.
[--output | -o] output-file: Specifies a file for output.

`psadmin set-attribute`

Description

Sets the portal desktop attribute to the supplied value or values for a base dn or at global or default levels.

Syntax

Long Format

psadmin set-attribute --component desktop --attribute-name attribute-name --adminuser uid --passwordfile password-filename [-add add_values] [--remove remove_values] [--inherit ] [--dn dn] --portalid portal-ID set_values --debug

Short Format

psadmin set-attribute -m desktop -a attribute-name -u uid -f password-filename [-d dn] -p portal-ID [ -A add_values] [-E remove_values][--inherit] set_values --debug

Options

The following options are required:

[--adminuser | -u] uid: Specifies the administrator's distinguished name.
[--attribute-name | -a] attribute-name: Argument which specifies the name of the desktop attribute for which the value is to be added, removed, replaced, or inherited. User friendly desktop attributes can be fetched from list-attribute command, with component name as desktop.
[--component | -m] desktop: Always desktop for this module.
[--passwordfile | -f] password-filename: Specifies the administrator's password in the password file.
[--portalId | -p] portal-ID: Specifies the portal ID.

The following options are optional:

[--add | -A] add_values

Applies to multi value attribute. Specifies a comma separated list of values to be set for an attribute. Mutually exclusive to --inherit option and set_values operand. The list of value is enclosed in "; for example, "val1","val2","val3".

--debug

Used for debugging purpose only. By default, this is set to false. Set this flag to true to see exceptions that caused the error.

[--dn | -d] dn

Specifies the distinguished name for whom desktop attribute is to be set.

--inherit

Allows the specified attribute at the given dn, to inherit its value from the parent dn.

The dn is mandatory to use this option.

[--remove | -E] remove_values

Applies to multi value attribute. Specifies a comma separated list of values to be removed for an attribute. Mutually exclusive to --inherit option and set_values operand. The list of value is enclosed in "; for example, "val1","val2","val3".

Operands

The following operand is supported:

set_values: Specifies the value to be set.

Limitations

You cannot do the following:

Use --add or --remove option with the --inherit option.
Use --add, --remove, or --inherit options with set_values operand.
Use the --inherit option without supplying the --dn option.

`psadmin list-attributes`

Description

Lists the portal desktop attributes which are defined at any base dn or at global or default levels. This subcommand can be used when an administrator wants to see the entire list of desktop attributes.

Syntax

Long Format

psadmin list-attributes --component desktop --adminuser uid --passwordfile password-filename [--output output-file] [--verbose] [--debug]

Short Format

psadmin list-attributes -m desktop -u uid -f password-filename [-o output-file] [-v] [--debug]

Options

The following options are required:

[--adminuser | -u] uid: Specifies the administrator's distinguished name.
[--component | -m] desktop: Always desktop for this module.
[--passwordfile | -f] password-filename: Specifies the administrator's password in the password file.

The following options are optional:

--debug: Used for debugging purpose only. By default, this is set to false. Set this flag to true to see exceptions that caused the error.
[--output | -o] output-file: Specifies a file for output.
[--verbose | -v]: Removes display profile verbosely.

`psadmin list-dp`

Description

Retrieves and displays display profile node objects.

Syntax

Long Format

psadmin list-dp --name name --adminuser uid --passwordfile password-filename --dn dn --portalid portal-ID [--global] [--dry-run] [--output output-file]

Short Format

psadmin list-dp -n name -u uid -f password-filename -d dn -p portal-ID [ -g] [-r] [-o output-file]

Options

The following options are required:

[--adminuser | -u] uid: Specifies the administrator's distinguished name.
[--dn | -d] dn: Distinguished name of the target node. This is mutually exclusive to -g option.
[--passwordfile | -f] password-filename: Specifies the administrator's password in the password file.
[--portalId| -p] portal-ID: Specifies the portal ID; if this is not supplied, the default is used.

The following options are optional:

[--dry-run | -r]: Attempt to execute command without writing out to LDAP. Default is false.
[--global | -g]: Global display profile. Default is false. This is mutually exclusive to -d option.
[--name | -n] name: Name of the target display object. If omitted, the entire display profile is displayed.
[--output | -o] output-file: Specifies a file for output.

Example

Example 2–1 `psadmin list-dp`

./psadmin list-dp -u amadmin -f ps_password -p myPortal1 -g -n RenderingWrappingProvider

The output is:

<Provider name="RenderingWrappingProvider" class=
"com.sun.portal.wireless.providers.rendering.wrapping
.RenderingWrappingProvider" version="2">
<Properties>
<String name="wrappedChannel" value="*** Enter channel name to be wrapped ***"/>
<String name="refreshTime" value="0" advanced="true"/>
<String name="fontFace1" value="Sans-serif"/>
<String name="contentPage" value="contentWrapper.jsp"/>
<String name="editPage" value="editWrapper.jsp" advanced="true"/>
<String name="editContainerName" value="JSPRenderingEditContainer" advanced="true"/>
<String name="processPage" value="doedit.jsp" advanced="true"/>
<Boolean name="showExceptions" value="false"/>
<Boolean name="isTopLevel" value="false" advanced="true"/>
</Properties>
</Provider>

`psadmin merge-dp`

Description

Retrieves and displays the merged result of the given display profile node objects.

Syntax

Long Format

psadmin merge-dp --name name --adminuser uid --passwordfile password-filename --dn dn --portalid portal-ID [--global] [--dry-run] [--output output-file]

Short Format

psadmin merge-dp --n name -u uid -f password-filename -d dn -p portal-ID [-g] [-r] [-o output-file]

Options

The following options are required:

[--adminuser | -u] uid: Specifies the administrator's distinguished name.
[--dn | -d] dn: The distinguished name of the target node. This is mutually exclusive to -g option.
[--passwordfile | -f] password-filename: Specifies the administrator's password in the password file.
[--portalId | -p] portal-ID: Specifies the portal ID; if this is not supplied, the default is used.

The following options are optional:

[--dry-run | -r]: Attempt to execute command without writing out to LDAP. Default is false.
[--global | -g]: Global display profile. Default is false. This is mutually exclusive to -d option.
[--name | -n] name: Name of the target display object. If omitted, merges the entire display profile.
[--output | -o] output-file: Specifies a file for output.

Example

Example 2–2 `psadmin merge-dp`

./psadmin merge-dp -u amadmin -f ps_password -p myPortal1 -d "cn=hr_role,o=Developersample,dc=country,dc=sun,dc=com" -n "JSPTabContainer/bookmark"

In the above example, psadmin merge-dp subcommand retrieves and displays the merged result of the specified DP node objects for hr_role and amadmin role. Objects are displayed in their native XML format. The object to be displayed is sent to standard out.

The psadmin merge-dp 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.

A portion of the result is displayed below:

<Channel advanced="false" lock="false" merge="fuse" name="bookmark" 
provider="BookmarkProvider">
<Properties advanced="false" lock="false" merge="fuse" name="_properties" 
propagate="true">
<String advanced="false" lock="false" merge="replace" name="title" propagate="true"
	value="Bookmark Provider"/>
<String advanced="false" lock="false" merge="replace" name="windowPref" 
propagate="true" value="all_new"/>
<String advanced="false" lock="false" merge="replace" name="width" 
	propagate="true" value="thin"/>
<Boolean advanced="false" lock="false" merge="replace" name="isEditable" 
	propagate="true" value="true"/>
<Boolean advanced="false" lock="false" merge="replace" name="isTopLevel" 
	propagate="true" value="false"/>
<String advanced="false" lock="false" merge="replace" name="editType" 
	propagate="true" value="edit_subset"/>
<String advanced="false" lock="false" merge="replace" name="description" 
	propagate="true" value="Bookmark Channel Provider Sample Implementation"/>
<String advanced="false" lock="false" merge="replace" name="fontFace1" 
	propagate="true" value="Sans-serif"/>
<String advanced="false" lock="false" merge="replace" name="productName" 
	propagate="true" value="Sun JavaTM System Portal Server 7"/>
<String advanced="false" lock="false" merge="replace" name="helpURL" 
	propagate="true" value="en/desktop/bkmark.htm"/>
<Collection advanced="false" lock="false" merge="fuse" name="targets" 
	propagate="true">
<String advanced="false" lock="false" merge="replace" name=
	"Sun home page|http://www.sun.com" 
	propagate="true" value="Sun home page|http://www.sun.com"/>
<String advanced="false" lock="false" merge="replace" name=
	"CNN home page|http://www.cnn.com" 
	propagate="true" value="CNN home page|http://www.cnn.com"/>
<String advanced="false" lock="false" merge="replace" 
	name="Yahoo home page|http://www.yahoo.com" 
	propagate="true" value="Yahoo home page|http://www.yahoo.com"/>
</Collection>
<String advanced="false" lock="false" merge="replace" name="refreshTime" 
	propagate="true" value="0"/>
<ConditionalProperties advanced="false" condition="locale" lock="false" 
	merge="fuse" propagate="true" value="en">
<String advanced="false" lock="false" merge="replace" name="title" 
	propagate="true" value="Bookmark Provider"/>
<String advanced="false" lock="false" merge="replace" name="description" 
	propagate="true" value="Bookmark Channel Provider Sample Implementation"/>
<Collection advanced="false" lock="false" merge="fuse" name="targets" propagate="true">
<String advanced="false" lock="false" merge="replace" name="Sun home page|
	http://www.sun.com" propagate="true" value="Sun home page|http://www.sun.com"/>

`psadmin modify-dp`

Description

Changes the value for an existing display profile object.

Syntax

Long Format

psadmin modify-dp --parent parent --adminuser uid --passwordfile password-filename --dn dn --portalid portal-ID [--global] [--dry-run] [--combine] [--output output-file] dp-document

Short Format

psadmin modify-dp -P parent -u uid -f password-filename -d dn -p portal-ID [-g] [-r] [-m] [-o output-file] dp-document

Options

The following options are required:

[--adminuser | -u] uid: Specifies the administrator's distinguished name.
[--dn | -d] dn: Distinguished name of the target node. This is mutually exclusive to -g option.
[--passwordfile | -f] password-filename: Specifies the administrator's password in the password file.
[--portalId | -p] portal-ID: Specifies the portal ID, if this is not supplied, the default is be used.

The following options are optional:

[--combine | -m]: Combine with the existing display profile object. For example, use this option to add a channel specified in the existing XML file to a container's existing selected list. By default, this is false. This option is not supported for provider.
[--dry-run | -r]: Attempt to execute command without writing out to LDAP. Default is false.
[--global | -g]: Global display profile. Default is false. This is mutually exclusive to -d option.
[--output | -o] output-file: Specifies a file for output.
[--parent | -P] parent: Name of the parent display object. If omitted, assumes the node to be modified is under root.

Operands

Specifies one or more files which contain XML fragments.

Example 1

Example 2–3 `psadmin modify-dp`

./psadmin modify-dp -u amadmin -f ps_password -P JSPTabContainer/bookmark2 -d cn=hr_role,o=Developersample,dc=country,dc=sun,dc=com" -p myPortal1 -m modify.xml

In the above example, the value of the channel, bookmark2, under the container, JSPTabContainer, is changed by the modify-dp subcommand. The data is supplied to the modify-dp command either from one or more input files or from a standard input in the form of an XML fragment that follows the command. The modify.xml file contains the following:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Properties>
<String name="title" value="My Bookmarks"/>
<String name="refreshTime" value="600"/>
<Collection name="targets">
<String value="Sun home page|http://www.sun.com"/>
<String value="Everything you want to know about Portal
...|http://www.iplanet.com/products/iplanet_portal/home_portal.html"/>
<String value="iPlanet home page|http://www.iplanet.com"/>
</Collection>
</Properties>

The semantics of the modify sub command vary based on the type of the display profile being modified. When combine option is specified, the new properties are combined with the existing display profile object, rather than replacing them.

Different variations of modify sub command are provided below:

Display Profile: An entire display profile can be changed to a new object value specified by a file. If the combine option is specified, every display profile object in the display profile document is combined.
Channel or Container: A channel or a 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 the parent option is absent, the root display profile object is assumed to parent container. So, root is searched for a channel or container that matches the name of the new display profile object.
Properties: A display profile objects properties can be changed to the new value. The parent option is required to modify a display profile objects 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 objects 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.
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.

Using the list-dp subcommand, you can view the way the bookmark2 channel is changed:./psadmin list-dp -u amadmin -f ps_password -p myPortal1 -d "cn=hr_role,o=Developersample,dc=country,dc=sun,dc=com" -n "JSPTabContainer/bookmark2"

The result is displayed below:

<Channel name="bookmark3" provider="BookmarkProvider">
    <Properties>
        <String name="title" value="My Bookmarks"/>
        <String name="refreshTime" value="600"/>
        <Collection name="targets">
            <String value="Sun home page|http://www.sun.com"/>
            <String value="Everything you want to know about Portal ...|
					http://www.iplanet.com/products/iplanet_portal/home_portal.html"/>
            <String value="iPlanet home page|http://www.iplanet.com"/>
        </Collection>
    </Properties>
</Channel>

Example 2–4 Example 2

If you need to remove a property, <String value="Everything you want to know about Portal ...| http://www.iplanet.com/products/iplanet_portal/home_portal.html"/> from bookmark3 explained in Example1, you can use the modify command.

Create a modify file as follows.

<Channel name="bookmark3" provider="BookmarkProvider">
    <Properties>
        <String name="title" value="My Bookmarks"/>
        <String name="refreshTime" value="600"/>
        <Collection name="targets">
            <String value="Sun home page|http://www.sun.com"/>
            <String value="iPlanet home page|http://www.iplanet.com"/>
        </Collection>
    </Properties>
</Channel>

Now run the following command:

./psadmin modify-dp -u amadmin -f ps_password -P JSPTabContainer/bookmark2 -d cn=hr_role,o=Developersample,dc=country,dc=sun,dc=com" -p myPortal1 modify.xml

In this example, you are replacing the entire properties section.

`psadmin add-dp`

Description

Adds a new display profile object to the display profile.

Syntax

Long Format

psadmin add-dp [--parent parent] --adminuser uid --passwordfile password-filename --dn dn --portalid portal-ID [--global] [--dry-run] dp-document

Short Format

psadmin add-dp [-P parent] -u uid -f password-filename -d dn -p portal-ID [-g] [-r] dp-document

Options

The following options are required:

[--adminuser | -u] uid: Specifies the administrator's distinguished name.
[--dn | -d] dn: Distinguished name of the target node. This is mutually exclusive to -g option.
[--passwordfile | -f] password-filename: Specifies the administrator's password in the password file.
[--portalId | -p] portal-ID: Specifies the portal ID, if this is not supplied, the default is used.

The following options are optional:

[--dry-run | -r]: Attempt to execute command without writing out to LDAP. Default is false.
[--global | -g]: Global display profile. Default is false. This is mutually exclusive to -d option.
[--parent | -P] parent: Name of the parent display object. If not specified , the object gets added to the root.

Operand

Specifies one or more files each of which contains XML fragment.

Example

Example 2–5 `psadmin add-dp`

./psadmin add-dp -u amadmin -f ps_password -P JSPTabContainer/bookmark2 -d "cn=hr_role,o=Developersample,dc=country,dc=sun,dc=com" -p myPortal1 add.xml

In the example above, a new channel, bookmark2 is added to the container, JSPTabContainer. The psadmin add-dp takes 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. It requires that the object to be added does not exist in the display profile.

The add.xml file contains the data for the channel bookmark2. The content of add.xml file is displayed below:

<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<Channel name="bookmark3" provider="BookmarkProvider">
    <Properties>
    </Properties>
</Channel>

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.
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.

`psadmin remove-dp`

Description

Removes an existing display profile object from the display profile.

Syntax

Long Format

psadmin remove-dp --name name [--parent parent] --type type --adminuser uid --passwordfile password-filename --dn dn --portalid portal-ID [--global] [--dry-run]

Short Format

psadmin remove-dp -n name [-P parent] -t type -u uid -f password-filename -d dn -p portal-ID [-g] [-r]

Options

The following options are required:

[--adminuser | -u] uid: Specifies the administrator's distinguished name.
[--dn | -d] dn: Distinguished name of the target node. This is mutually exclusive to -g option.
[--name | -n] name: Name of the target display object. This should be specified as none if type is root or if the entire display profile needs to be removed.
[--passwordfile | -f] password-filename: Specifies the administrator's password in the password file.
[--portalId | -p] portal-ID: Specifies the portal ID; if this is not supplied, the default is used.
[--type | -t] type: Type of the display object are root, channel, provider, property, available, or selected.

The following options are optional:

[--dry-run | -r]: Attempt to execute command without writing out to LDAP. Default is false.
[--global | -g]: Global display profile. Default is false. This is mutually exclusive to -d option.
[--parent | -P] parent: Name of the parent display object. If not specified , the object gets removed from the root.

Example

Example 2–6 `psadmin remove-dp`

./psadmin remove-dp -u amadmin -f ps_password -p myPortal1 -d "cn=hr_role,o=Developersample,dc=country,dc=sun,dc=com" -n "JSPTabContainer/bookmark3" -t channel

In the above example, psadmin remove-dp removes the channel bookmark3 from the container JSPTabContainer.

If you need to remove the channels that are added to a user or role, run the following command:

./psadmin remove-dp -u amadmin -f ps_password -p myPortal1 -d "cn=hr_role,o=Developersample,dc=country,dc=sun,dc=com"

This command removes all channels that are added to the role. It retains only the channels that are present in the Developersample.

Chapter 2 Desktop Subcommands

psadmin get-attribute

Description

Syntax

Long Format

Short Format

Options

psadmin set-attribute

Description

Syntax

Long Format

Short Format

Options

Operands

Limitations

psadmin list-attributes

Description

Syntax

Long Format

Short Format

Options

psadmin list-dp

Description

Syntax

Long Format

Short Format

Options

Example

Example 2–1 psadmin list-dp

psadmin merge-dp

Description

Syntax

Long Format

Short Format

Options

Example

Example 2–2 psadmin merge-dp

psadmin modify-dp

Description

Syntax

Long Format

Short Format

Options

Operands

Example 1

Example 2–3 psadmin modify-dp

Example 2–4 Example 2

psadmin add-dp

Description

Syntax

Long Format

Short Format

Options

Operand

Example

Example 2–5 psadmin add-dp

psadmin remove-dp

Description

Syntax

Long Format

Short Format

Options

Example

Example 2–6 psadmin remove-dp

`psadmin get-attribute`

`psadmin set-attribute`

`psadmin list-attributes`

`psadmin list-dp`

Example 2–1 `psadmin list-dp`

`psadmin merge-dp`

Example 2–2 `psadmin merge-dp`

`psadmin modify-dp`

Example 2–3 `psadmin modify-dp`

`psadmin add-dp`

Example 2–5 `psadmin add-dp`

`psadmin remove-dp`

Example 2–6 `psadmin remove-dp`