Using a Flat-File User Repository (Sun Java System Message Queue 4.3 Administration Guide)

Sun Java System Message Queue 4.3 Administration Guide

Using a Flat-File User Repository

Message Queue provides a built-in flat-file user repository and a command line tool, the User Manager utility (imqusermgr), for populating and managing it. Each broker has its own flat-file user repository, created automatically when you start the broker. The user repository resides in a file named passwd, in a directory identified by the name of the broker instance with which the repository is associated:

   …/instances/instanceName/etc/passwd

(See Appendix A, Platform-Specific Locations of Message Queue Data for the exact location of the instances directory, depending on your operating system platform.)

User Groups and Status

Each user in the repository can be assigned to a user group, which defines the default access privileges granted to all of its members. You can then specify authorization rules to further restrict these access privileges for specific users, as described in User Authorization. A user’s group is assigned when the user entry is first created, and cannot be changed thereafter. The only way to reassign a user to a different group is to delete the original user entry and add another entry specifying the new group.

The flat-file user repository provides three predefined groups:

admin: For broker administrators. By default, users in this group are granted the access privileges needed to configure, administer, and manage message brokers.
user: For normal (non-administrative) client users. Newly created user entries are assigned to this group unless otherwise specified. By default, users in this group can connect to all Message Queue connection services of type NORMAL, produce messages to or consume messages from all physical destinations, and browse messages in any queue.
anonymous: For Message Queue clients that do not wish to use a user name known to the broker (for instance, because they do not know of a real user name to use). This group is analogous to the anonymous account provided by most FTPservers. No more than one user at a time can be assigned to this group. You should restrict the access privileges of this group in comparison to the user group, or remove users from the group at deployment time.

You cannot rename or delete these predefined groups or create new ones.

In addition to its group, each user entry in the repository has a user status: either active or inactive. New user entries added to the repository are marked active by default. Changing a user’s status to inactive rescinds all of that user’s access privileges, making the user unable to open new broker connections. Such inactive entries are retained in the user repository, however, and can be reactivated at a later time. If you attempt to add a new user with the same name as an inactive user already in the repository, the operation will fail; you must either delete the inactive user entry or give the new user a different name.

To allow the broker to be used immediately after installation without further intervention by the administrator, the flat-file user repository is created with two initial entries, summarized in Table 9–1:

The admin entry (user name and password admin/admin) enables you to administer the broker with Command utility (imqcmd) commands. Immediately on installation, you should update this initial entry to change its password (see Changing a User’s Password).
The guest entry allows clients to connect to the broker using a default user name and password (guest/guest).

You can then proceed to add any additional user entries you need for individual users of your message service.

Table 9–1 Initial Entries in Flat-File User Repository


User Name	Password	Group	Status
`admin`	`admin`	`admin`	Active
`guest`	`guest`	`anonymous`	Active

Using the User Manager Utility

The Message Queue User Manager utility (imqusermgr) enables you to populate or edit a flat-file user repository. SeeUser Manager Utility for general reference information about the syntax, subcommands, and options of the imqusermgr command.

User Manager Preliminaries

Before using the User Manager, keep the following things in mind:

The imqusermgr command must be run on the host where the broker is installed.
If a broker-specific user repository does not yet exist, you must start up the corresponding broker instance to create it.
You must have appropriate permissions to write to the repository; in particular, on Solaris and Linux platforms, you must be logged in as the root user or the user who first created the broker instance.

Subcommands and General Options

Table 9–2 lists the subcommands of the imqusermgr command. For full reference information about these subcommands, see Table 15–15.

Table 9–2 User Manager Subcommands


Subcommand	Description
`add`	Add user and password to repository
`delete`	Delete user from repository
`update`	Set user’s password or active status (or both)
`list`	Display user information

The general options listed in Table 9–3 apply to all subcommands of the imqusermgr command.

Table 9–3 General User Manager Options


Option	Description
`-f`	Perform action without user confirmation
`-s`	Silent mode (no output displayed)
`-v`	Display version information [Any other options specified on the command line are ignored. ]
`-h`	Display usage help

Displaying the Product Version

To display the Message Queue product version, use the -v option. For example:

   imqusermgr  -v

If you enter an imqusermgr command line containing the -v option in addition to a subcommand or other options, the User Manager utility processes only the -v option. All other items on the command line are ignored.

Displaying Help

To display help on the imqusermgr command, use the -h option, and do not use a subcommand. You cannot get help about specific subcommands.

For example, the following command displays help about imqusermgr:

   imqusermgr  -h

If you enter an imqusermgr command line containing the -h option in addition to a subcommand or other options, the Command utility processes only the -h option. All other items on the command line are ignored.

Adding a User to the Repository

The subcommand imqusermgr add adds an entry to the user repository, consisting of a user name and password:

   imqusermgr add  [-i brokerName]
                    -u userName  -p password
                   [-g group]

The -u and -p options specify the user name and password, respectively, for the new entry. These must conform to the following conventions:

All user names and passwords must be at least one character long. Their maximum length is limited only by command shell restrictions on the maximum number of characters that can be entered on a command line.
A user name cannot contain an asterisk (*), a comma (,), a colon (:), or a new-line or carriage-return character.
If a user name or password contains a space, the entire name or password must be enclosed in quotation marks (" ").

The optional -g option specifies the group (admin, user, or anonymous) to which the new user belongs; if no group is specified, the user is assigned to the user group by default. If the broker name (-i option) is omitted, the default broker imqbroker is assumed.

For example, the following command creates a user entry on broker imqbroker for a user named AliBaba, with password Sesame, in the admin group:

   imqusermgr add  -u AliBaba  -p Sesame  -g admin

Deleting a User From the Repository

The subcommand imqusermgr delete deletes a user entry from the repository:

   imqusermgr delete  [-i brokerName]
                       -u userName

The -u option specifies the user name of the entry to be deleted. If the broker name (-i option) is omitted, the default broker imqbroker is assumed.

For example, the following command deletes the user named AliBaba from the user repository on broker imqbroker:

   imqusermgr delete  -u AliBaba

Changing a User’s Password

You can use the subcommand imqusermgr update to change a user’s password:

   imqusermgr update  [-i brokerName]
                       -u userName  -p password

The -u identifies the user; -p specifies the new password. If the broker name (-i option) is omitted, the default broker imqbroker is assumed.

For example, the following command changes the password for user AliBaba to Shazam on broker imqbroker:

   imqusermgr update  -u AliBaba  -p Shazam

Note –

For the sake of security, you should change the password of the admin user from its initial default value (admin) to one that is known only to you. The following command changes the default administrator password for broker mybroker to veeblefetzer:

   imqusermgr update  -i mybroker  -u admin  -p veeblefetzer

You can quickly confirm that this change is in effect by running any of the command line tools when the broker is running. For example, the following command will prompt you for a password:

   imqcmd list svc  mybroker  -u admin

Entering the new password (veeblefetzer) should work; the old password should fail.

After changing the password, you should supply the new password whenever you use any of the Message Queue administration tools, including the Administration Console.

Activating or Deactivating a User

The imqusermgr update subcommand can also be used to change a user’s active status:

   imqusermgr update  [-i brokerName]
                       -u userName  -a activeStatus

The -u identifies the user; -a is a boolean value specifying the user’s new status as active (true) or inactive (false). If the broker name (-i option) is omitted, the default broker imqbroker is assumed.

For example, the following command sets user AliBaba’s status to inactive on broker imqbroker:

   imqusermgr update  -u AliBaba  -a false

This renders AliBabe unable to open new broker connections.

You can combine the -p (password) and -a (active status) options in the same imqusermgr update command. The options may appear in either order: for example, both of the following commands activate the user entry for AliBaba and set the password to plugh:

   imqusermgr update  -u AliBaba  -p plugh  -a true
   imqusermgr update  -u AliBaba  -a true  -p plugh

Viewing User Information

The imqusermgr list command displays information about a user in the user repository:

   imqusermgr list  [-i brokerName]
                    [-u userName]

The command

   imqusermgr list  -u AliBaba

displays information about user AliBabe, as shown in Example 9–1.

Example 9–1 Viewing Information for a Single User

User repository for broker instance: imqbroker
----------------------------------
User Name    Group    Active State
----------------------------------
AliBaba      admin    true

If you omit the -u option

   imqusermgr list

the command lists information about all users in the repository, as in Example 9–2.

Example 9–2 Viewing Information for All Users

User repository for broker instance: imqbroker
--------------------------------------
User Name    Group        Active State
--------------------------------------
admin        admin        true
guest        anonymous    true
AliBaba      admin        true
testuser1    user         true
testuser2    user         true
testuser3    user         true
testuser4    user         false
testuser5    user         false