Chapter 8   Using the Command Line Interface




Command Line Inferface Overview

---

This chapter describes the command-line interface (ipsadmin) available for iPlanet Portal Server administration. Use ipsadmin to import XML files to register (or update) iPlanet Portal Server applications or content providers.

How it Works

---

As iPlanet Portal Server is installed, XML files shipped with the product are imported into the Profile and Policy Server (using ipsadmin) to register the existing applications. See /etc/opt/SUNWips/xml to see the XML code used.

If new applications are written that should be administered through the iPlanet Portal Server desktop or if expanding on the capabilities of existing modules, it is necessary to write and import an XML file to register the module with the Profile and Policy Server. Additionally, use the ipsadmin command to script or automate most routine tasks that could otherwise be accomplished through the Administration Console. For example:

• Create domains

• Create roles

• Add a user

ipsadmin Command

---

By providing additional or new information to the Profile and Policy Server, the ipsadmin command allows the creation or modification of:

• A role

• A user

• A domain

• A component

Usage

ipsadmin [-import|-chkxml] xmlfile

ipsadmin [change] [role|user|domain|component] name [xmlfile]

ipsadmin [get|delete][role|user|domain|component] name

Where:

-import imports the xmlfile as a new component in the Profile service.

-chkxml checks the validity of the XML and reports errors without making any changes to the Profile. Use this before importing any data.

xmlfile comprises component name, attributes, and privileges as per the webtopimport.dtd file. See Code Example 8-1 for the DTD and annotations.

create, get, change, delete are operations that can be performed on a profile.

name is the name of the profile to be operated on.

role, user, domain, component are the types of the profile to be operated on.

file is the XML file containing the contents for the operation with regard to attributes and privileges. This uses the iwt:Att and iwtPriv tags in the wtimport.dtd file.

Using ipsadmin

---

Importing a New Component

1. Create a file newComponent.xml which describes what the Profile Server must know about the component:

<iwt:Component name="newComponent"

Within this section, specify other "newComponent"-wide data, such as description, resource bundle, and index.

>

<iwt:Att name="newComponent-attribute1"

Within this section, specify other newComponent-attribute1 related data, such as description, index, default value, and type.

>

</iwt:Att>

2. List as many other attributes as you require.

<iwt:Priv name="newComponent-privilege1"

Within this section, specify other newComponent-privilege1 related data, such as description, index, default value, or type.

>

</iwt:Att>

</iwt:Component>

3. Issue the ipsadmin command:

   # ipsadmin -import newComponent.xml

   
   

   ---

   Note

   ipsadmin registers the attributes and privileges in the iPlanet Portal Server LDAP data store, but does not remove this metadata if the component is deleted later with the ipsadmin delete command. A subsequent addition of the same component (for example, with extra attributes) will generate warnings that the attributes and privileges are already registered; these are harmless errors and are for information only.

   ---

   
   

Creating a New Domain

1. Create an XML file which contains attributes and privileges for this Domain.

This XML file looks like the XML in the Importing a New Component"example, except that it does not have the enclosing <iwt:Component> tags and it could have attributes and privileges from any of the components currently imported. It contains <iwt:Att and <iwt:Priv tags only.

2. Issue the ipsadmin command:

   # ipsadmin create domain SampleDomain SampleDomain.xml

Creating a New Role

1. Create an XML file which contains attributes and privileges for this role (Employee, in this example).

This XML file looks like the XML in the Importing a New Component"example, except that it does not have the enclosing <iwt:Component> tags and it could have attributes and privileges from any of the components currently imported. It contains <iwt:Att and <iwt:Priv tags only.

2. Issue the ipsadmin command:

   # ipsadmin create role /SampleDomain/Employee xmlfile

Creating a New User and Assigning a Role

1. Create an XML file which contains attributes and privileges for this user.

This XML file looks like the XML in the Importing a New Component" example, except that it does not have the enclosing <iwt:Component> tags and it could have attributes and privileges from any of the components currently imported. It contains <iwt:Att and <iwt:Priv tags, plus these tags:

<iwt:Att name="iwtUser-role" >

<Val>/Sampledomain/Employee</Val>

</iwt:Att>

2. Execute the ipsadmin command:

   # ipsadmin create user SampleDomain/decoy xmlfile

If the role attribute is omitted, ipsadmin will create the user, but issue a warning that the role is not set. If that happens, the role can always be added later using the ipsadmin change command.

Reading (Getting) a Profile

Use ipsadmin to read information out of the Profile Server, to more easily update specific information or to modify the extracted information to create a similar, new entry.

# ipsadmin get domain SampleDomain # ipsadmin get component newComponent # ipsadmin get role /SampleDomain/Employee # ipsadmin get user /SampleDomain/decoy

All display the attributes and privileges on stdout via the <iwt:Att and <iwt:Priv tags. The output can be saved in a file and later used for updating or creating another profile.

Changing a Profile

Use ipsadmin to modify existing Profile entries by specifying change on the command line as well as the type of component that the XML specifies to change.

Here is an example on how to modify a user's first name and last name, assume the user is user1 under domain dom1.

1. Create an XML file named /tmp/user.xml which contains following tags:

   <iwt:Att name="iwtUserInfoProvider-firstName"> <Val>FirstName</Val> </iwt:Att> <iwt:Att name="iwtUserInfoProvider-lastName"> <Val>LastName</Val> </iwt:Att>

The attributes name for user's first name and last name are:

• "iwtUserInfoProvider-firstName"

• "iwtUserInfoProvider-lastName"

All the iPlanet Portal Server defined attributes and privileges could be find in the XML files under /etc/opt/SUNWips/xml directory.

2. Issue the ipsadmin command

   # ipsadmin change user /dom1/user1 /tmp/user.xml

The XML specifies what needs to be changed and values enclosed within the iwt:Att and iwt:Priv tags.

Deleting a Profile

Use ipsadmin to delete existing Profile entries by specifying delete on the command line. For example:

# ipsadmin delete user /SampleDomain/decoy # ipsadmin delete role /SUN/Employee # ipsadmin delete domain SUN # ipsadmin delete component newComponent

Sample Code

---

Code Example 8-1 XML Sample Compliant with import.dtd 

---

<!-- name:name of the component -->

<!-- ver :Version no of this DTD -->

<!-- desc:Brief description in <3 words -->

<!-- resB:Relative path of resource bundle to -->

<!-- use for getting l18n desc version -->

<!-- idx :Index into res bundle to get l18n -->

<!-- version of desc. -->

<!-- Att*,Priv* : privileges and attributes -->

<!-- Naming Convention : -->

<!-- Component name : [a-zA-Z][a-zA-Z0-9]* -->

<!-- Attribute name : <ComponentName>-[[a-zA-Z0-9-]+ -->

<!-- Privilege name : <ComponentName>-[[a-zA-Z0-9-]+ -->

<!-- Absolutely NOT allowed : [./#_] -->

<!-- Special/Reserved attribute names: -->

<!-- desc stored as attribute called -->

<!-- "Description" (string) -->

<!-- idx stored as attribute called -->

<!-- "DescIndex" (string) -->

<!-- resB stored as attribute called -->

<!-- "ResourceBundle" (string) -->

<!-- All XML ATTs tagged with #IMPLIED are optional, -->

<!-- All XML ATTs tagged with #REQUIRED are mandatory -->

<!ELEMENT iwt:Component (iwt:Att*, iwt:Priv*)>

<!ATTLIST iwt:Component

name CDATA #REQUIRED

ver CDATA #FIXED "1.0"

desc CDATA #IMPLIED

resB CDATA #IMPLIED

idx CDATA #IMPLIED>

<!-- Privilege : -->

<!-- name:Name of the privilege -->

<!-- type:Type of the privilege -->

<!-- desc:Brief description in <3 words -->

<!-- idx :Index into resB to find l18n version -->

<!-- of the description -->

<!-- val :Default value for boolean type priv : -->

<!-- true=ALLOW, false=DENY -->

<!-- Dlst:Deny List for list type privileges -->

<!-- Alst:Allow List for list type privileges -->

<!-- Special privilege : -->

<!-- "Execute" (boolean) represents execute -->

<!-- permission -->

<!ELEMENT iwt:Priv (iwt:Dlst*,iwt:Alst*)>

<!ATTLIST iwt:Priv

name CDATA #REQUIRED

type (boolean|list) "boolean"

desc CDATA #IMPLIED

idx CDATA #IMPLIED

val (true|false) #IMPLIED

>

<!-- Attribute -->

<!-- name:Name of the Attribute -->

<!-- desc:Brief description in <3 words -->

<!-- idx :Index into resB to find l18n version -->

<!-- userConfigurable:flag to indicate if attribute -->

<!-- value is allowed to be specified on a -->

<!-- per User/Role basis -->

<!-- type:Datatype of the value -->

<!-- of the description -->

<!-- Val:Value of the attribute - multiple for-->

<!-- "list" type attributes. -->

<!-- RPerm:List of roles allowed to read the value -->

<!-- Special keywords : ADMIN : admin role -->

<!-- OWNER : allow owner -->

<!-- WPerm:List of roles allowed to write the value -->

<!-- Special keywords : ADMIN : admin role -->

<!-- OWNER : allow owner -->

<!-- CVal:Possible choice values for choice* type -->

<!-- attributes. -->

<!ELEMENT iwt:Att (iwt:Val*,iwt:RPerm*,iwt:WPerm*,iwt:CVal*)>

<!ATTLIST iwt:Att

name CDATA #REQUIRED

desc CDATA #IMPLIED

idx CDATA #IMPLIED

userConfigurable (TRUE|FALSE) "TRUE"

type (string | number | boolean | singlechoice | multichoice

|protected | stringlist | numberlist | binary ) "string"

>

<!ELEMENT iwt:Val (#PCDATA)*>

<!ELEMENT iwt:Dlst (#PCDATA)*>

<!ELEMENT iwt:Alst (#PCDATA)*>

<!ELEMENT iwt:CVal (#PCDATA)*>

<!ELEMENT iwt:Rperm (#PCDATA)*>

<!ELEMENT iwt:Wperm (#PCDATA)*>

<!-- Example -->