Chapter 4 i-Planet User Administration Command Line Interface

This chapter describes the Java command line interface that i-Planet administrators can use to:

• Create i-Planet users

• Delete i-Planet users

• View the properties of all i-Planet users

• List all i-Planet users

Configuring and Testing Classpath Settings

The command-line utility is a Java class called UserAdminCL. Before you can run UserAdminCL, you must be root on your i-Planet server and have the classes shown in Table 4-1 in your classpath:

Setting Your Classpath

Use the following procedure to set your classpath so you can use UserAdminCL.

To Set Your Classpath

1. As root, type the following command to set your classpath:

   # CLASSPATH=/opt/SUNWjeev/classes/SNUtils.jar:/opt/SUNWjeev/classes\ /preference_servlet.jar:/opt/SUNWjeev/classes/common.jar:/usr/java/lib\ /classes.zip:/opt/SUNWstnr/lib/useradmin.jar

2. Type the following command to export your classpath:

   # export CLASSPATH

Verifying the Settings to Use UserAdminCL

Use the following procedure to verify the settings to use UserAdminCL:

To Verify Settings to Use UserAdminCL

1. As root, type the following command to run UserAdminCL:

   # java com.sun.stnr.useradmin.UserAdminCL

If you see the following usage message, you are ready to use UserAdminCL.

com.sun.stnr.common.CommandLineException: missing switch: +action
usage: [jre|java] com.sun.stnr.useradmin.UserAdminCL +action

[create|delete|get|list] [-srclogin] [-destlogin] [-usersfile]

[-defsfile] [-older] [-nologin] [-debug] [-interactive]

If you see other error messages, verify your classpath and try again.

Using UserAdminCL

The UserAdminCL supports several actions:

• Listing i-Planet users

• Getting specific information about i-Planet users, such as their role

• Creating a new i-Planet user

• Deleting an i-Planet user.

You must use the +action command-line switch and one of the actions listed above. Depending on the action, other optional switches provide additional information. Each switch is described below and illustrated with an example.

Using UserAdminCL Summary

The actions and switches available are summarized as follows:

• -srclogin LOGINID--Specifies the user ID of an existing i-Planet user for use with the delete, create, and get actions.

• -destlogin LOGINID--Specifies the user ID of a new i-Planet user that is used with the create action.

• -usersfile FILENAME--Specifies the file name for the i-Planet user properties file. Use this with the create and delete actions.

• -defsfile FILENAME--Specifies the file name for i-Planet's default file. Use this with the create action.

• -older N--Specifies i-Planet users who have last logged in N or more days ago. Use this with delete and list actions.

• -nologin--Specifies i-Planet users who have not yet logged in. Use this with the list and delete actions.

• -interactive--Turns off all user interaction for use with the delete action.

• -debug--Turns on debugging. Use this with all actions.

Listing i-Planet Users

You can list all i-Planet users who have logged in or for whom profiles have been created in standard output (one line per user).

You can use two optional switches with the list action:

• -older N --Lists the i-Planet users who have not logged in for more than N days. If you specify -older 0, all i-Planet users will be listed.

• -nologin--Lists the i-Planet users who have never logged in. If neither switch is present, all i-Planet users are listed.

To List i-Planet Users Without Any Switch

1. Type the following command to list all i-Planet users without any optional switch, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action list

   This command lists all i-Planet users who have logged in or for whom profiles have been created:

   root abc jdoe def

To List i-Planet Users With the -nologin Switch

1. Type the following command to list all i-Planet users with the -nologin switch, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action list -nologin

   This command lists all i-Planet users who have not logged in:

   root

To List i-Planet Users With the -older N Switch

1. Type the following command to list all i-Planet users with the -older N switch, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action list -older 30

   This command lists all i-Planet users whose last login was more than 30 days ago:

   root abc

Viewing an i-Planet User's Properties

Use the following procedure to view an i-Planet user's properties through standard output. Key-value pairs are separated by a new line.

To View an i-Planet User's Properties

1. Type the following command to view an i-Planet user's configuration, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action get -srclogin jdoe

   This command displays the properties of the i-Planet user specified after the switch -srclogin:

   + properties for login=jdoe Common.MailServer=mail.sun.com Common.CalendarServer=calendar.sun.com SNDesktop.userTemplatePath=/etc/opt/SUNWstnr/html_templates/ userTemplate.html SNDesktop.prefTemplatePath=/etc/opt/SUNWstnr/html_templates/ prefTemplate.html user.url=http://memnoch.eng.sun.com:8080/servlet/SNDesktop? template=user role=web Common.EmployeeNumber=12345 Common.UserName=jdoe SNDesktop.feedbackTemplatePath=/etc/opt/SUNWstnr/html_templates/feedbackTemplate.html SNDesktop.checkCalendar=1 SNDesktop.serviceTimeout=5000 SNDesktop.checkMail=1 SNDesktop.lang=usenglish session.uid=jdoe IMAP.Mail.password=f6006d14cafef5faa Common.LastName=Doe Common.FirstName=Jane SNDesktop.advancedTemplatePath=/etc/opt/SUNWstnr/html_templates/advancedTemplate.html Common.DefaultMailServer=mail.sun.com

Creating a New i-Planet User

You can create a new i-Planet user using the properties of an existing i-Planet user, using the configuration files that you specify, or using system defaults as the basis:

• If you specify both -srclogin SRCID and destlogin DESTID, create creates a login ID DESTID that is based on the properties of the existing i-Planet user named SRCID.

• If you specify only -destlogin DESTID, the new i-Planet user DESTID is based on the system default settings.

• If you specify neither -srclogin nor -destlogin, the information for one or more new i-Planet users is gathered from default configuration files.

Creating a New i-Planet User Using an Existing i-Planet User As the Basis

If you provide both the -srclogin SRCID and -destlogin DESTID switches, the create action makes a new i-Planet user based on the properties of the existing i-Planet user that you specified. The new i-Planet user has the login ID of DESTID and has each property of the i-Planet user with login ID SRCID (except the IMAP password).

To Create a New i-Planet User Using an Existing i-Planet User As the Basis

1. Type the following command to create a new i-Planet user using an existing i-Planet user as a basis, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action create -srclogin olduser \ -destlogin newuser

   This command returns the confirmation that the user indicated in the command was created:

   # + created user=bc81306

Creating an i-Planet User from System Defaults

If you provide only the -destlogin DESTID switch, then you create a new i-Planet user based on system defaults. The system defaults for creating a i-Planet user in this fashion are stored in the default i-Planet user configuration file and the default profile file.

The following properties are in i-Planet's default user configuration file /etc/opt/SUNWstnr/defaultUser.conf:

• Common.UserName

• Common.FirstName

• Common.LastName

• Common.MailServer

• Common.CalendarServer

• Common.EmployeeNumber

• Common.DefaultMailServer

• SNDesktop.userTemplatePath

• SNDesktop.prefTemplatePath

• SNDesktop.feedbackTemplatePath

• SNDesktop.advancedTemplatePath

• SNDesktop.checkCalendar

• SNDesktop.checkMail

• SNDesktop.lang

• SNDesktop.serviceTimeout

The following properties are stored in i-Planet's /opt/SUNWjeev/profiles/.default file:

• role

• user.url

  ---

  Note -

  You can edit these files directly to set defaults for all new i-Planet users in the system. Each file consists of key value pairs separated by an =, with one pair on each line.

  ---

To Create a New i-Planet User Using System Defaults As a Basis

1. Type the following command to create a new i-Planet user using system defaults as a basis, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action create -destlogin bc81306

   This command returns the confirmation that the user indicated in the command was created:

   + created user=bc81306

Creating New i-Planet Users From a Text File

If you specify neither -srclogin nor -destlogin switches with the create action, then UserAdminCL reads data for the new i-Planet user from text files. You can create multiple identical i-Planet users using predefined defaults that are set up in a defaults file, or by specifying the per i-Planet user configuration in a flat file, or both. You can specify two command line switches:

• usersfile--Specifies the users file, and defaults to ./users if not specified.

• defsfile--Specifies the defaults file, and defaults to ./defaults, if not specified.

Each line in the users file contains information for a single user in the form of one or more key-value pairs. Keys and values are separated by an = (equals sign), and key-value pairs are separated by a ; (semicolon); see the example for the Procedure "To Create New Users From a Text File" below. Only the key session.uid is required--any other pairs are optional.

The defaults file format is identical to that of the i-Planet users file, except that it contains only a single line of properties. The properties specified in the defaults are applied to each i-Planet user named in the i-Planet users file for any values not explicitly specified in the i-Planet user's file.

i-Planet stores an i-Planet user's IMAP mail password as an encrypted value. It is encrypted with a proprietary algorithm. If you wish to specify a mail password for each i-Planet user in the users file, you can do so, but it must be in plain text. The password will be encrypted before it is saved.

For example, to add three i-Planet users and specify an IMAP password, a mail server, and calendar server for each, you can use the following procedure.

To Create New Users From a Text File

1. Create a ./users file, for example.

   This file should contain the following information:

   session.uid=bob;IMAP.Mail.password=gimme session.uid=bill;IMAP.Mail.password=bokbok session.uid=jan;IMAP.Mail.password=joshua

   This file is used to specify information that is different for each i-Planet user that is being created. At a minimum, each i-Planet user's login name (session.uid) and the IMAP mail password (IMAP.Mail.password) falls into this category.

2. Because the mail and calendar server are constant among all the i-Planet users, create a ./defaults file with a single line to populate the mail and calendar server values for all users, for example:

   Common.MailServer=foo.bar.com;Common.CalendarServer=farble.bar.com

3. With these files in place, type the following command to run UserAdminCL:

   # java com.sun.stnr.useradmin.UserAdminCL +action create + created login=bob + created login=bill + created login=jan

   This command returns the confirmation that the user or users indicated in the command were created:

   + created login=bob + created login=bill + created login=jan

Deleting i-Planet Users

You can remove i-Planet users from the system in three different ways: by user ID, by user's last login time (if any), or by reading a list of login IDs from a text file.

• If you provide the -srclogin LOGINID switch, the login ID LOGINID will be deleted.

• If you specify the -older N switch, then users who have not logged in for N days will be deleted.

• If you specify the -nologin switch, then users who have never logged in will be deleted.

• If you provide none of the above switches, UserAdminCL reads a list of users to delete from a text file.

• If you specify the -interactive switch, you will not be asked if you want to delete the user first.

In addition to any specific i-Planet user being deleted, all i-Planet users "aliased" to this user are also removed.

Deleting a Specific i-Planet User by Userid

If you specify the -srclogin LOGINID switch after the delete action, then the login ID LOGINID will be removed from the i-Planet database.

To Delete a Specific i-Planet User by Userid

1. Type the following command to delete a specific i-Planet user, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action delete -interactive \ -srclogin jb34290

   This command returns the confirmation that the user indicated in the command was deleted:

   + deleted login=jb34290

Deleting i-Planet Users Based on Last Login Time

If you specify either the -nologin or -older N switches, i-Planet users are removed based on their last update time (stored as the value for the i-Planet user's Common.UpdateTime property). You can view this property with the get action.

• If you specify -nologin, then users who have not yet logged in will be deleted (Common.UpdateTime property is null).

• If you specify -older N, then users with an update time of more than N days from the present are deleted.

  ---

  Note -

  Any user that is deleted with the -nologin switch is also removed by the -older N switch. Specifying -older 0 selects all users.

  ---

To Delete i-Planet Users Based on Last Login Time Using the -older N Switch

1. Type the following to delete i-Planet users based on last login time using the -older N switch, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action -interactive delete -older 30

2. Confirm that you want the user indicated deleted by typing y or n:

   + delete login=bob [yes/no] y + deleted login=bob + delete login=bill [yes/no] y + deleted login=bill + delete login=bob [yes/no] n + no action for login=jan

To Delete i-Planet Users Based on Last Login Time Using the -nologin Switch

1. Type the following to delete i-Planet users based on last login time using the -nologin switch, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action delete -interactive -nologin

2. Confirm that you want the user indicated deleted by typing y or n:

   + delete login=bob [yes/no] y + deleted login=bob

Deleting i-Planet Users According to a List

If you do not specify -older N, -nologin, or -srclogin switches with the delete action, a list of i-Planet users to be removed will be read from a text file. You can provide the file name on the command line to identify the file to be used. If you do not specify a file, ./users will be used.

UserAdminCL reads a list of login IDs from the users file and deletes each one from the system.

The format of this users file is identical to the users file described in the section "Creating New i-Planet Users From a Text File". However, only the session.uid property is used and all other content is ignored.

To Delete i-Planet Users According to a List

1. Type the following to delete i-Planet users according to a list, for example:

   # java com.sun.stnr.useradmin.UserAdminCL +action delete -interactive

   This command returns confirmation that the users who meet the criterion in the command are deleted:

   + deleted login=bob + deleted login=bill + deleted login=jab

   ---

   Note -

   You can specify the -interactive switch to prevent prompting.

   ---