sungard higher education luminis message broker … · what can we help you achieve? sungard higher...

What can we help you achieve?

SunGard Higher EducationLuminis Message Broker (LMB)

Installation and Administration GuideVersion E Feb 2, 2007

Version E Feb 2, 2007ii LMB Installation and Administration Guide

Confidential Business Information

This documentation is proprietary information of SunGard Higher Education and is not to be copied, reproduced, lent or disposed of, nor used for any purpose other than that for which it is specifically provided without the written permission of SunGard Higher Education.

Prepared By: SunGard Higher Education4 Country View RoadMalvern, Pennsylvania 19355United States of America

© 2004-2007 SunGard. All rights reserved. The unauthorized possession, use, reproduction, distribution, display or disclosure of this material or the information contained herein is prohibited.

In preparing and providing this publication, SunGard Higher Education is not rendering legal, accounting, or other similar professional services. SunGard Higher Education makes no claims that an institution's use of this publication or the software for which it is provided will insure compliance with applicable federal or state laws, rules, or regulations. Each organization should seek legal, accounting and other similar professional services from competent providers of the organization's own choosing.

Without limitation, SunGard, the SunGard logo, Banner, Campus Pipeline, Luminis, PowerCAMPUS, Matrix, and Plus are trademarks or registered trademarks of SunGard Data Systems Inc. or its subsidiaries in the U.S. and other countries. Third-party names and marks referenced herein are trademarks or registered trademarks of their respective owners.

Version E Feb 2, 2007 About this guide iii

ABOUT THIS GUIDE

As an information system professional who may have to maintain the Luminis Message Broker, or the servers upon which it runs, you play a large role in making the system suc-cessful. To help you, this guide contains procedures and recommendations about the initial installation tasks in which you will engage, and ongoing administration tasks nec-essary to keep the system and its required software components running smoothly.

WHO IS IT FOR?

This guide is designed to be used by anyone who needs to install, configure, or adminis-ter the Luminis Message Broker software, or the servers on which the software runs. To use this guide effectively, the following skill set is assumed:

• 1-2 years server administration on the platform used for deployment (Windows or Solaris)

• 1-2 years network administration, including DNS, LAN, Firewall, and Internet secu-rity exposure

• Exposure to and experience working with the Lightweight Directory Access Protocol (LDAP) and with manipulation of data stored via LDAP

• Familiarity with the Java Messaging Service (JMS) API

• Familiarity with Internet protocols or standards such as HTTP, HTTPS, and XML

• Familiarity with the systems and supporting datastores for any clients that will be set up as message producers or consumers using Luminis Message Broker

• In-depth knowledge of custom adapters or applications used to enable client systems to use the JMS model and the Luminis Message Broker

If you are unsure of any of these skills, please contact SunGard Higher Education for more details or to inquire about training.

HOW DO I USE IT?

This guide is designed as a reference, providing information about such things as:

• How the Luminis Message Broker employs Sun components and the JMS API to cre-ate a mechanism for disparate Java based or HTTP compatible systems to communicate data

• Setting up the configuration files that support system installation and running the appropriate installation scripts

Version E Feb 2, 2007iv LMB Installation and Administration Guide

• Creating the appropriate elements in the system’s LDAP store to support administra-tion of client systems

• Using the Message Broker Administration tool and mbtool administrative interface to manage and monitor the destinations, objects, and clients associated with the system

As you work through this guide, please note the following conventions:

Administrative user vs. Administrator

Throughout this guide you will be instructed to log in to the server as the administrative user or into the system as an administrator.

For command line procedures administrative user assumes that you are logging in to the server’s operating system with the credentials of the user who has administra-tive privileges over the files used by the Luminis software.

For administrative procedures carried out through the Web interface, the designation administrator assumes that you are accessing the system through a browser and logging in as a user who has been granted the administrative permis-sions necessary to access the Message Broker Tool.

Command Line In command lines, the backslash ( \ ) is used to denote line breaks.

Command windows The Luminis system requires a UNIX emulator called Cyg-win in order to run administrative scripts and command in a Windows operating system. If instructed to open a com-mand window while using Windows, you should use Cygwin unless instructed otherwise.

Drive Designations To designate mounted drives, we use conventions relative to the operating system upon which you are running the software.

For Sun Solaris, we refer to /opt as the mounted installa-tion drive:

/opt/. . .

For Windows, we refer to D: as the mounted installation drive:

D:\. . .

Monospaced font The following typeface is used for file names, distin-guished names, functions, commands, and examples:

monospaced font

Version E Feb 2, 2007 About this guide v

WHERE DO I FIND MORE INFORMATION?

For the third-party applications and systems used by the Luminis Message Broker soft-ware (such as Sun Message Queue server, Directory server, etc.), this guide is intended to augment each vendor’s proprietary materials. In all cases, SunGard Higher Education rec-ommends that you consult the vendor’s documentation for more information about its products. To better understand the Luminis Message Broker, the Sun components that it employs, and the Java Messaging Service specification, SunGard Higher Education rec-ommends that you read the following:

Notes, Cautions, and Warnings Throughout the guide, you will see the following symbols:

Note:

Caution:

Warning:

A Note indicates additional information that may be useful. A Caution provides information that if not observed may cause the system to operate less than optimally. A Warning provides information that if not observed will cause the sys-tem or one of its components to fail.

Path references and variables Throughout this guide you will see path references in this form:

$CP_ROOT/slapd-<serverID>/...

All paths use forward slashes ( / ). If you are installing on a Windows system, assume the equivalent of a backward slash (\).

Names between the “< >” symbols represent values that you designate. For example, the variable, <serverID> above would represent the name you gave the computer when you installed the operating system. Assuming $CP_ROOT is the environment variable for the installation directory and you installed the Luminis software in /opt/cp30 on a computer with an identifier of tango, the actual path would be:

/opt/cp30/slapd-tango/. . .

Vertical bar ( | ) A vertical bar ( l ) is used as a separator for logically orga-nized user interface elements. For example, File | New means you should click the File menu and choose New. Server Status | View Log means you should select the Server Status folder from the administrative menu and then click the View Log link.

Version E Feb 2, 2007vi LMB Installation and Administration Guide

Sun Directory Server 5.2 Administrator's Guide

Java Message Service API, Version 1.1

Java Message Service API Tutorial

Sun Message Queue Administrator’s Guide, version 3.6

Sun Message Queue Developer’s Guide, version 3.6

If you need more information about using the Broker Administration Tool, consult the online help files that are available with this application. For additional information about how SunGard Higher Education uses the JMS model or the IMS specification, consult the following:

SunGard Higher Education Data Integration SDK IMS Protocol Specification

For more information on other Integration Technology components contact SunGard Higher Education.

WHAT’S IN THIS GUIDE?

This guide contains the following chapters:

Chapter 1. Provides instructions for installing the Luminis Message Broker software components and configuring them to operate in your computing environment.

Chapter 2. Provides an overview of the tools used to administer the system and proce-dures for managing the broker, its messaging destinations, and the clients that access them.

Chapter 3. Provides procedures for creating new objects to support custom integration and adapter deployment.

Chapter 4. Provides a list of the mbtool command-line options that can also be used to create and administer the destinations, connections, and objects that support messag-ing, and to administer the Luminis Message Broker.

Glossary. Provides a glossary of terms that will be presented throughout the guide and within the software components with which you’ll be working.

ALTERNATE FORMAT

SunGard Higher Education is committed to making all our products, materials, and information accessible to those with disabilities. To obtain a copy of this document in an alternate format, please call SunGard Higher Education.

Version E Feb 2, 2007 Contents vii

CONTENTSCHAPTER 1

• Installing the Luminis Message Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.2

• Installation prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.3

General requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.3

Windows requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.4

Solaris requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.6

Linux Advance Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.8

• Installing the software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.9

Creating an installation file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.9

Running the installation script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.14

Verifying the LMB directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.15

• Starting up and shutting down the Luminis Message Broker . . . . . . . . . . . . . . . . . . . .1.17

Starting up the system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.17

Shutting down the system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.17

Stopping and starting and the Directory server . . . . . . . . . . . . . . . . . . . . . . . . . . .1.18

Shutting down the Broker (Message Queue and the Web server) . . . . . . . . . . . .1.18

Shutting down the entire system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.18

• Logging in and verifying installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.20

Logging in to the Message Broker Administration Tool . . . . . . . . . . . . . . . . . . . . . . .1.20

Testing mbtool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.21

• Additional setup and integration issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.22

e-Learning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.22

Luminis Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.22

CHAPTER 2

• Administering the Luminis Message Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.2

• Pausing and resuming the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.3

• Setting Message Broker configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.5

• Creating and managing destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.7

Creating destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.7

Setting access policies for destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.9

Adding users to the LDAP store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.9

Configuring access restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.11

Managing destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.13

viii LMB Installation and Administration Guide Version E Feb 2, 2007

Monitoring destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.13

Purging subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.14

Deleting subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.14

Purging destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.15

Deleting destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.15

• Setting connection access policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.17

• Creating and managing HTTP clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.19

Creating HTTP clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.19

Resetting properties for HTTP clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.22

Deleting HTTP clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.23

• Monitoring and configuring logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.24

Message Broker logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.24

Configuring Message Broker logging characteristics . . . . . . . . . . . . . . . . . . . . . . . . . .2.26

Working with the cplog4j.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.26

Working with the config.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.29

Monitoring other system logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.30

Directory server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.31

Web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.31

• Backing up the system and its data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.32

Backing up the LDAP repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.32

Backing up the persistent message store and configurations . . . . . . . . . . . . . . . . . . .2.35

• Changing administrative credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.36

• Reallocating memory to the JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.37

Determining the memory allocated to the JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.37

Resetting memory allocated to the JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.37

• Resetting the Message Broker Administration Tool timeout . . . . . . . . . . . . . . . . . . . .2.39

CHAPTER 3

• Creating and managing administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.2

• Creating administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.3

• Managing administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.13

Modifying object properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.13

Deleting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.14

CHAPTER 4

• Using mbtool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.2

• mbtool commands and options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.3

Version E Feb 2, 2007 Contents ix

• Executing mbtool commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.13

APPENDIX A

• Timezone and country codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A.2

timezones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A.2

Country codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A.5

GLOSSARY

• Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .G.1

x LMB Installation and Administration Guide Version E Feb 2, 2007

Installing the Luminis Message Broker

CHAPTER 1 CONTENTS

This chapter provides information about installing the Luminis Message Broker software and its systemic components, including prerequisites that you should observe, procedures for configuring setup files, and steps for running the installation scripts.

• Installing the Luminis Message Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.2

• Installation prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.3

General requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.3

Windows requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.4

Solaris requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.6

Linux Advance Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.8

• Installing the software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.9

Creating an installation file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.9

Running the installation script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.14

Verifying the LMB directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.15

• Starting up and shutting down the Luminis Message Broker . . . . . . . . . . . . . . . . . . . .1.17

Starting up the system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.17

Shutting down the system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.17

Stopping and starting and the Directory server . . . . . . . . . . . . . . . . . . . . . . . . . . .1.18

Shutting down the Broker (Message Queue and the Web server) . . . . . . . . . . . .1.18

Shutting down the entire system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.18

• Logging in and verifying installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.20

Logging in to the Message Broker Administration Tool . . . . . . . . . . . . . . . . . . . . . . .1.20

Testing mbtool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.21

• Additional setup and integration issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.22

e-Learning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.22

Luminis Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.22

CHAPTER 1

1.2 LMB Installation and Administration Guide Version E Feb 2, 2007

INSTALLING THE LUMINIS MESSAGE BROKER

The Luminis Message Broker (LMB) consists of a number of third party software com-ponents that work together to store the user, group, and object information required to authenticate clients into the system and implement the Java Messaging Service specifica-tion to exchange messages between external clients. The LMB software and all required components are provided with your license and can be installed on either a Windows, Sun Solaris, or Linux server.

This chapter outlines the specific components that are installed on your system to sup-port the LMB, the general system requirements that must be met prior to installing the software on any server, specific hardware and software requirements for Windows, Solaris, and Linux servers, and the procedures necessary to install the Luminis Message Broker on these operating systems and to test the successfulness of the installation.

Caution: This chapter is primarily written for clients who are installing a stand-alone version of the Luminis Message Broker to support learning management system inte-gration within their campus environment. If you are deploying LMB as part of the complete Luminis Platform, you will install it along with the other Luminis compo-nents using the procedures outlined in the Luminis Platform Installation Guide. Before installing the Luminis Platform, you should review the installation procedures con-tained in the subsequent sections of this guide and if necessary add and adjust any appropriate LMB installation parameters in your Luminis Platform installation file. You should also review the section “Luminis Platform” on page 1.22 for a list of issues that you should be aware of when implementing LMB along with the Luminis Platform. Once you have installed the Luminis Platform components, you should refer again to this guide for information on accessing the LMB administrative interfaces and for setting up and administering the objects that will be used in your messaging environment.

Version E Feb 2, 2007 Installing the Luminis Message Broker 1.3

INSTALLATION PREREQUISITES

When you install the Luminis Message Broker (LMB) the following primary compo-nents are installed on your system in addition to SunGard Higher Education software:

• Sun Directory Server 5.2. This component provides the LDAP-based directory used to support user and group authentication and to store aspects of the administered objects used by the Broker.

• Java Development Kit 1.5. Provides the Java Virtual Machine, the Java platform core classes, the Java Runtime Environment (JRE), and supporting files that are all required to run Java programs. The JRE acts as an interface between compiled Java binary code and the microprocessor that actually performs the program's instructions.

• Sun Message Queue Server 3.6. Provides the framework and engine for the Java Messaging Service through which LMB is implemented.

• Apache Tomcat 5.5.17. Provides the Web server and Web container through which the Message Broker Administration Web application is run and through which the HTTP Gateway used by HTTP clients is managed.

Note: The specific service pack or hotfix levels for these products may vary depending on the LMB version you are deploying. Also, if you are installing the LMB software on a Windows Platform, you will first need to install Cygnus Solutions CYGWIN, which provides a UNIX emulator that is necessary to run shell programs used to start up, shut down, and administer LMB.

You can install LMB software and these third party components on a Windows, Solaris, or Linux server that meets the minimum general and specific hardware and software requirements outlined below.

GENERAL REQUIREMENTS

To install the components that support LMB on any server, you must ensure that the following basic system and network requirements are in place:

• Clean server. The server that you install the LMB software and its components on must not have previously had any Campus Pipeline, Luminis Platform, or iPlanet/Sun products installed on it. Old components (even if they have been uninstalled) can cause the installation to fail or the subsequent operation of the machine and its com-ponents to be compromised.

• Directory Server ports. You can install the Directory Server on any port, but keep the following in mind:– The standard Directory Server port is 389.– Port 636 is reserved for LDAP over SSL (SLDAP), so you should not use this port

for the standard installation.


Installation prerequisites

– Port numbers 1-1024 have been assigned to services by the Internet Assigned Numbers Authority. Do not use ports below 1024 (other than 389 or 636) for direc-tory services.

– On UNIX, the Directory Server must run as root on port 389 or 636. On Windows, the directory service must have administrative privileges if it runs on port 389 or 636.

– Do not choose ports that are already in use.– The Directory Server also provides a Web application that is used to configure and

manage aspects of the software that will require a port.

• Web server ports. The standard Web server port number is 80 and the standard SSL-enabled web server port number is 443. To avoid conflicts with Web servers running under these standard ports, you should install the Web server for LMB on another port. SunGard Higher Education recommends 7677. Also, the Web server provides a Web application for administration, which will need to run on a specified port.

• DNS and IP address. Prior to installing Directory Server and the Web Server, you must ensure that DNS is properly configured with an entry for the server in a DNS server and that the system has a static IP address.

• Installation user. The software must be installed by a user with root privileges on UNIX or an administrator privileges on Windows.

• Administrative user. An operating system administrative user must exist under which the software is run. On Windows, this user should be a member of the local administrator group. On UNIX, this user should be non-privileged (not root).

• User Group. For UNIX, a user group must also be created that will dictate the per-missions placed on the installed files.

• System clock. Because the system will be integrated with other servers and applica-tions, it is important that the system clock is correct at installation and kept accurate during operation.

• Firewall. SunGard Higher Education highly recommends installing LMB and its component software behind an institutional firewall.

In addition to these general requirements, each operating system upon which you are installing has its own particular requirements. These operating system requirements and the minimum hardware and software specifications for each are outlined in the following sections.

WINDOWS REQUIREMENTS

To install LMB and its components on a Windows server, the following requirements and specifications must be met:

• Operating System. Windows 2000 (Server SP2 or later) or Windows 2003



• CPU. Intel Pentium II or later processor

• Cygwin.The Cygnus Solutions CYGWIN software provides a UNIX emulator that is necessary to run shell programs used to start up, shut down, and administer LMB in a Windows environment. You must install version 1.5 or later before installing the LMB software.

• Memory and Disk Space. The performance of the system will be directly related to the amount of memory and free disk space available to each component. The follow-ing table outlines the minimum recommendations for the primary components included in the system:

• Patches. You should install the latest security patches available for the Windows operating system that you are using.

• Internet Information Server. Do not install this with Windows.

• TCP/IP network protocol. Specify TCP/IP as the only network protocol and do not install any other network services.

• System tuning. There are many elements of the Windows operating system that should be tuned or configured to optimally run the Sun components, especially the Directory Server. Refer to your Windows documentation for information on Win-dows tuning for multi-threaded Internet services.

• Browser. Netscape Communicator 4.72 or higher or Microsoft Internet Explorer 5.0 or higher are required to access the Web Server Administration and LMB Administra-tion Tool Web applications.

As outlined above, a UNIX emulation program called Cygwin must be installed and configured. To run the scripts used to start up and shut down the system, and to adminis-ter LMB using the mbtool interface, you will need to use the Cygwin emulator

Component Installation disk space

Free disk space Memory

Cygwin 230 MB

Directory Server 120 MB 200 MB 256 MB (min)

Java Development Kit 120 MB

Luminis Message Broker 100 MB 70 MB

Sun Message Queue 60 MB 1200 MB 128 MB

Tomcat Web Server 120 MB 230 MB 64 MB

1The 200 MB estimate is based upon the default message size limit imposed on the persis-tent message store. You can increase this value to accommodate the messaging needs of your system.

2The 30 MB estimate accounts for log files generated by the Web server during operation.



exclusively as the scripts do not run in a DOS command window. When you install Cyg-win, you should install the following packages:

• ash • bash • coreutils • cygwin • findutils • gawk • grep • gzip • sed • tar

Once you have verified that your server meets these minimum requirements, proceed to the installation instructions on page 9.

SOLARIS REQUIREMENTS

To install LMB and its components on a Solaris server, the following requirements and specifications must be met:

• Operating System. Sun Solaris 9 or 10

• CPU. UltraSPARC

• Memory and Disk Space. The performance of the system will be directly related to the amount of memory and free disk space available to each component. The follow-ing table outlines the minimum recommendations for the primary components included in the system:



Directory Server 120 MB 200 MB 256 MB (min)

Java Development Kit 120 MB

Luminis Message Broker 100 MB 70 MB

Sun Message Queue 10 MB 1200 MB 128 MB



• Patches. Apply the latest recommended patch cluster for your Solaris operating sys-tem (consult sunsolve.sun.com). You should also run the idsktune utility, which is installed with Directory Server, to obtain information about additional patches that might be required and to get advice on tuning kernel parameters.

• System tuning. There are many elements of the Solaris operating system that should be tuned or configured to properly run the Sun components, especially the Directory Server. Some of these elements include:

– The tcp_time_wait_interval specifies the number of milliseconds that a TCP con-nection will be held in the kernel's table after it has been closed. If its value is above 30000 (30 seconds) and the directory is being used in a LAN, MAN, or under a single network administration, it should be reduced by adding a line simi-lar to the following to the /etc/init.d/inetinit file:

ndd -set /dev/tcp tcp_close_wait_interval 30000

– The tcp_conn_req_max_q0 and tcp_conn_req_max_q parameters control the maxi-mum backlog of connections that the kernel will accept on behalf of the Directory Server process. If the directory is expected to be used by a large number of client hosts simultaneously, these values should be raised to at least 1024 by adding a line similar to the following to the /etc/init.d/inetinit file:

ndd -set /dev/tcp tcp_conn_req_max_q0 1024

ndd -set /dev/tcp tcp_conn_req_max_q 1024

– The tcp_keepalive_interval specifies the interval in seconds between keepalive packets sent by Solaris for each open TCP connection. This can be used to remove connections to clients that have become disconnected from the network.

– The tcp_rexmit_interval_initial value should be inspected when performing server performance testing on a LAN or high speed MAN or WAN. For operations on the wide area Internet, its value need not be changed.

– The tcp_slow_start_initial parameter should be inspected if clients will predomi-nately be using the Windows TCP/IP stack.

– The rlim_fd_max parameter in the etc/system file should be set to 4096. Under nor-mal operation you should not need to set this value any higher. However, if you do, you will also need to decrease the value of the tcp_smallets_anon_port parameter in the /etc/init.d/inetinit file.

Note: For more information on tuning these parameters, refer to the Sun Directory Server 5.2 Installation Guide. You may also want to consult any of a number of com-

Tomcat Web Server 100 MB 230 MB 64 MB

1The 200 MB estimate is based upon the default message size limit imposed on the persis-tent message store. You can increase this value to accommodate the messaging needs of your system.

2The 30 MB estimate accounts for log files generated by the Web server during operation.





mercially available books or articles concerning Solaris performance tuning for the Internet.

• Browser. Netscape Communicator 4.72 or higher or Microsoft Internet Explorer 5.0 or higher are required to access the Web Server Administration and LMB Administra-tion Tool Web applications.

Once you have verified that your server meets these minimum requirements, proceed to the installation instructions on page 9.

LINUX ADVANCE SERVER

LMB and its components can be installed on a server running Linux Advance Server 3. Minimum specifications for the Luminis Message Broker components are the same as outlined for Solaris and Windows platforms in the previous sections. For information on processor, memory, and disk space requirements for Sun compo-nents on Linux, refer to your Sun documentation. At minimum, the following Linux RPMs must be installed:

• compat-gcc 7.3

• compat-gcc-c++ 7.3

• compat-libstdc++ 7.3


INSTALLING THE SOFTWARE

When you install the Luminis Message Broker (LMB), you install software developed by SunGard Higher Education and a number of third party components required to run the system. To install LMB and its components, you perform the following basic steps:

• Obtain installation media or download installation files from SunGard Higher Educa-tion Customer Support Center.

• Create an installation configuration file containing information specific to your com-puting environment

• Run the installation script against this file

The following sections provide detailed information for each step and a list of the directories and critical files laid down on your server with the installation.

CREATING AN INSTALLATION FILE

Once you have obtained the installation package, you are ready to install the LMB soft-ware. To do so, you will need to create a special installation configuration file that will be used to pass institution-specific values into the installer as it lays down and configures the components of the system. To create your configuration file, do the following:

Using a text editor, create a file with the following name and extension:

lmb.conf

This file will work with a number of default configuration files called by the installer. Values that you add to this file will supplant or be co-opted into parame-ters in other files. If you are installing the software from a CD, you should create a temporary directory into which you will save the lmb.conf file.

Open this file and add the following parameters to it:

admin.id=admin.password=cp.root=license.key=os.user.id=os.group.id=resource.directory.manager.dn=resource.directory.manager.password=resource.host=resource.ldap.suffix=resource.ldap.port=school.cityschool.countryschool.name


Installing the software

school.stateschool.timezoneschool.ziptiers=

This is the minimum set of parameters that are required to install LMB and its com-ponent software, for which you must provide information unique to your environment. Note also that the os.user.id and os.user.group parameters are only required for installations on UNIX (Solaris and Linux). In Canadian installations, you need to replace school.zip with school.postal. You also need to add school.province.

In addition to these required parameters, you may add any of the following to the lmb.conf and set them appropriately for your environment. Note that if you do not add the following optional parameters to the file, they will be set with defaults.

http.non.proxy.hosts=http.proxy.host=http.proxy.portserver.instance.id=verbose=ws.http.port=ws.https.port=

Add values to the required (and optional) parameters as outlined in the follow-ing table:

Parameter Description Default Restrictions

admin.id An administrative user ID that will be used as the default for all other admin-istrative IDs if no other .id parameters are specified in the lmb.conf file. For the quickest installation, pro-vide a value for this parameter and allow it to be used for all others. If you want to specify unique credentials for all other administrative users, you may do so.

admin Only use only alphabetic and numeric characters (e.g. admin123), no spaces or special/reserved charac-ters such as backslashes ( \ ), at signs ( @ ), colons ( : ), dollar signs ( $ ), and the like.Caution: Do not use cpuser as the admin.id value.



admin.password The password used for the default administrative user. If no other .password parameters are specified in the lmb.conf. file, this value will be used as the default password for all administra-tive users.

Must be a mini-mum of eight characters. Do not use spaces, tabs, or special/reserved characters such as backslashes ( \ ), at signs ( @ ), colons ( : ), dollar signs ( $ ), and the like. Restrict passwords to combinations of letters, numbers, and if necessary a period ( . ), dash ( - ), or underscore ( _ ) to introduce variability and added security.

cp.root The primary installation directory for the LMB software

Must observe the following format:

Windows:<D>\:\\<dirname>

UNIX/Linux:/dirname/

Note: In this exam-ple, the colon has been escaped (with backslashes). You would also need to escape an equals sign if used in the lmb.conf file.

http.non.proxy.hosts Hostnames that do not need to be handled by a proxy server.

Space or comma separated list of which each entry must be preceded by an asterisk as follows:

*.<host>.<domain>

http.proxy.host The hostname of the proxy server behind which the system is deployed.




http.proxy.port The port on which the proxy server runs.

license.key A license key that sets the software components that will be installed and options for certain system features based upon the way in which you've licensed the software.

os.user.id Required only on UNIX. The UNIX user that the software programs will be installed and owned by.

Must be a user already created for the software.

os.group.id Required only on UNIX. The UNIX group that will govern permissions on the installed files.

Must be a group already created to support the soft-ware installation.

resource.directory.manager.dn

The distinguished name (DN) for the Directory Manager.

Directory Manager

resource.directory.manager.password

The password for the direc-tory manage.r

same as that sup-plied for admin.password

Must be eight char-acters or more.

resource.host The fully qualified domain name of the computer upon which you are installing the software, For example, lmb.wasatch.edu.

resource.ldap.port The port that will be used for LDAP.

389

resource.ldap.suffix The root suffix for the LDAP DIT

cp

school.city The city in which you school is located.

school.country The country in which your school is located.

Must be specified using a two letter code. Refer to Appendix A of this guide.

school.name The name of the school.




school.province If your school is located in Canada, this property is used to define the province.

school.state If your school is located in the US, this property is used to specify the state.

Use standard US Postal Service two letter abbreviation.

school.timezone The default timezone in which the school is located.

America/Denver Concatenated value using standard tim-ezone area and representative city designations. Refer to Appendix A of this guide.

school.zip (postal) US Postal code for school location.

server.instance.id The id used to name the directory and web server instances.

cp

tiers The components to install. The possible values are calendar, mail, message-broker, portal, and resource. For an LMB installation, the value to use is:

messagebroker

For LMB installs, values other than messagebroker will not be allowed.

verbose Whether verbose output is displayed during installa-tion. Possible values are yes or no.

No

ws.http.port The port under which the Web server will run.

80 To avoid conflicts with other Webserv-ers, you should choose an alter-nate port for LBM. SunGard recom-mends 7677.




Save and close the lmb.conf file.

The values added to this file will be incorporated into the installation by pointing the installation script at this file, as outlined in the next section. Since the installer will read this file, it should be saved in an accessible location. The temporary direc-tory that you created to extract the installation files is recommended. If you are installing from a CD, save the lmb.conf file to a temporary directory on the server.

RUNNING THE INSTALLATION SCRIPT

Once you have obtained and unpacked the installation files and created and configured a lmb.conf file for site-specific installation variables, you are ready to run the installation script. To do so, use the following procedure:

Warning: If you are installing on a Windows platform you will need to use the Cyg-win application to run the installation script. If you are installing the LMB software from CD, you can obtain the Cygwin executable from the /image/windows/cygwin directory. You can also download Cygwin from the Internet. If you are downloading the application, you must use version 1.5 or higher.

Open a command window on the server where you intend to install the software.

Log in as root (UNIX) or a user with local administrative privileges (Windows).

Change to the directory into which you extracted the installation files.

If you are installing from a CD, change to the drive in which the disk is located.

From the command prompt, type the following as appropriate to the platform upon which you are installing, replacing the variable with the location of the lmb.conf file:

On Linux

LP-4.0.0.0-linux /<path>/lmb.conf

On UNIX

LP-4.0.0.0-linux /<path>/lmb.conf

On Windows

ws.https.port The port under which secure (HTTPS) pages will be delivered.

443 To avoid conflicts with other Webserv-ers, you should choose an alter-nate port for LBM. SunGard recom-mends 7678.




LP-4.0.0.0-windows.exe \<path>\lmb.conf

Once this command is executed, the components of LMB will begin to be installed.

You should shut down and restart the operating system after installation so that all changes are read correctly into the LMB configurations at startup.

VERIFYING THE LMB DIRECTORY STRUCTURE

Once the LMB software is installed the structure that is created will vary based on oper-ating system; however, there are a number of primary directories that you will work with that serve the following purposes:

• pipeline. This is the installation root directory, which is set up with the following environment variable: $CP_ROOT. The name is variable and may be different on your system.

• bin. The bin directory contains the following executable scripts used to startup, shut-down, and manage the Message Broker:– mbclasspath.Used by command line applications and scripts to compute the Java

class paths. – mbgetmaxheap. Lists the maximum amount of memory allocated to the Java Vir-

tual Machine (JVM) in which LMB is deployed.– mbqueryconfig. Used to query the system for properties.– mbsetmaxheap. Used to adjust the memory used by the JVM. – mbtool. A command line interface that provides a set of commands that allow you

to startup, shutdown, and administer the Broker and the destinations and objects that are managed through it.

– startcp. A master startup command.– stopcp. A master shut down command

• logs. The logs directory contains the error, exception, and message traffic monitoring logs.

• webapps. The webapps directory contains configuration, HTML, JSP, and other files that control the operation and appearance of the system, including the following.– cps. The cps directory is the primary directory for the static HTML pages used in

the system.– css. Contains the cascading style sheet (style.css), which is used to apply standard

fonts, lines, and other elements for the system’s Web application.– help. Contains the .jsp and image files that constitute the Luminis Message Broker

Administration Tool’s online help system.– insecure. Contains .jsp files used to log in to the system.



– META-INF. An artifact of the system installation. When directories are unzipped from a jar file, the java Jar utility uses META-INF to record meta data about the jar file contents, such as version, producer, and the like.

– secure. Contains the .jsp files used to render the Luminis Message Broker Admin-istration Tool.

– WEB-INF. Contains configuration files for the system and the resource elements of the system channels that are not intended to be Web visible in the following subdirectories· classes. The classes directory contains the Java class files that constitute the sys-

tem software.· config. This directory includes files that control the operation of the system and

its components, including the cplog4j.properties, which defines the elements of the system that will be written to the cp.log or other files, the verbosity of the logging information, and the number and size of the log files

– lib. Contains the Java Archive (JAR) files that provide the instructions for the sys-tem and its operations.

The LMB software also relies on other software components including the Sun Direc-tory Server and Message Queue Server and the Tomcat Webserver. The products directory is the default installation directory for the Tomcat Webserver for all operating systems. It contains the executables, database files, and operational components for the Web Server software. On UNIX and Linux machines, the Directory Server components that support the Luminis Message Broker are installed in a /ds subdirectory under /prod-ucts. On UNIX and Linux The Message Queue Server components are installed under /var/imq and /etc/imq. In Windows environments the Sun directory is the default installa-tion directory for the Directory Server and Message Queue Server that support the Luminis Message Broker.

When the LMB system is installed a test certificate is generated and set up to support SSL implementation. In most instances, this test certificate will be suitable for the system and its deployment. However, if you need to install a commercial server certificate to sup-port enhanced SSL deployment with other client applications, you may do so. The procedures for installing a server certificate include:

• Creating a Certificate Signing Request (CSR)

• Submitting the CSR to a Certificate Authority (CA)

• Obtaining the certificate and installing it on the Web server

• Configuring the system to recognize the CA

For detailed procedures, refer to the following publication, which can be obtained through the Customer Support Center:

Luminis Platform Installation Guide


STARTING UP AND SHUTTING DOWN THE LUMINIS MESSAGE BROKER

When you start up the Luminis Message Broker (LMB), you use a single command to initiate the Sun Directory Server, Sun Message Queue Server, and Tomcat Web Server. When you shut down LMB, you can selectively stop some of these components or stop all of them at once. The following sections provide instructions for starting up and shutting down LMB.

STARTING UP THE SYSTEM

To start up LMB, do the following:

Caution: Prior to starting the system for the first time, you should load the .cprc file that is located in the installation directory. To do so, open a bourne or bash shell (Cygwin on Windows), change to the installation directory and type the following:

. .cprc

Log in to the server where the LMB software is installed as the administrative user.

From the command line (use Cygwin on Windows) type the following:

startcp

The startcp script starts all LMB components. The script also verifies that the sys-tem environment is configured correctly. If there are configuration problems, the script broadcasts the following error, provides some corrective suggestions, and exits the start up routine:

Platform startup failed.The environment is not configured correctly.

Note: If you are running LMB on a UNIX platform and accessing the system through a telnet or null-modem connection, you may want to run the following command to start up the system so that inadvertent closing of the command window does not bring down the system:

nohup startcp

SHUTTING DOWN THE SYSTEM

You can shut down portions of the system or the entire system depending upon your needs. Use the following procedures as appropriate:


Starting up and shutting down the Luminis Message Broker

STOPPING AND STARTING AND THE DIRECTORY SERVER

There may be times when you want to shut down and restart the Directory Server manu-ally. To shut down and restart the Directory Server, do the following:

Caution: If you shut down the Directory Server, the LMB software will be inaccessi-ble by users. In most cases, you will shut down the entire system instead of the Directory Server.

Log in to the Luminis Message Broker server as the administrative user.

From the command line (use Cygwin on Windows) change to the following directory:

$CP_ROOT/bin/rc

Type the following to stop the Directory Server:

10-ldap.stop

Note: You can also start and stop the Directory Server through the Directory Server Console. To access the Console you would enter the FQDN of the server followed by the port number upon which the Console has been set to run, as illustrated below:

http://<hostname>.<domain>:<port>

SHUTTING DOWN THE BROKER (MESSAGE QUEUE AND THE WEB SERVER)

To shut down and restart the Message Queue and Web server components, which con-stitute the Broker, use the following procedure:

Log in to the LMB server as the administrative user.


mbtool stop broker

The stop broker command shuts down the LMB processes, the Message Queue Server, and the Web Server. In most instances, these are the only components that you would need to stop.

To restart the system, type the following:

mbtool start broker

SHUTTING DOWN THE ENTIRE SYSTEM

In some instances, you may need to shut down the Broker and the Directory Server, in effect shutting down the entire system. To do so, use the following procedure:



Starting up and shutting down the Luminis Message Broker


stopcp -a

The stopcp command when used with the -a switch shuts down the LMB processes, the Message Queue Server, the Web Server, and the Directory Server. To restart the system, use the startcp command.


LOGGING IN AND VERIFYING INSTALLATION

Once you have installed the Luminis Message Broker (LMB) software and started up the system for the first time, you should log in to both the Web-based Message Broker Administration Tool and the mbtool interface to verify successful installation. The follow-ing sections provide information for logging in to each.

LOGGING IN TO THE MESSAGE BROKER ADMINISTRATION TOOL

To log in to the Message Broker Administration Tool, use the following procedure:

From your administrative machine, open your Internet browser.

Enter the URL for the Message Broker login page.

The URL for the login page should be similar to the following, where the variable information represents the fully qualified domain name or IP address of the server upon which the Broker was installed and the port under which the Web server is running (typically 7677):

http://<machine name or IP address>:<port>

For example, if LMB were installed on a machine named mbserver under the aschool.edu domain on port 7677, the login URL would be:

http://mbserver.aschool.edu:7677

Note: Depending on your preference, you may want to run the administrative interface for the Message Broker under Secure Socket Layer (SSL) encryption. If so, you would access the login page using the https protocol (e.g. https://oursever.ascholl.edu:7678)

In the Secured Access Login box, enter your username and password.

The username and password combination should be the values you supplied for the following parameters in the installation configuration file:

admin.id admin.password

Once authenticated, you see the Message Broker Administration Tool menu, simi-lar to the following that outlines the number of messages currently contained in the system and their combined size, as well as access to other administrative options:


Logging in and verifying installation

If you see this window, the Web server and the Web-based administration compo-nents of LMB have been installed correctly. You should now test whether the mbtool interface operates correctly.

TESTING MBTOOL

To log in and test the mbtool interface, do the following:

Log in to the server where the LMB is installed as the administrative user.

Open a command window (on Windows use Cygwin).

At the prompt type the following command:

mbtool list brokerstatus

If installed correctly, you should see output similar to the following:

The broker state is: running

Current Number of Messages in System: 0Max Size of Messages in System: 200mMax Number of Messages in System: 100000Current Size of Messages in System (bytes): 0Max Message Size: 100k


ADDITIONAL SETUP AND INTEGRATION ISSUES

The Luminis Message Broker is designed to support message transmission from one or more integrated learning management systems. Consequently, installation of LMB may only be a portion of the setup required to get the fully integrated system operating. If you are using LMB as part of your Integration Technology for e-Learning implementation or have installed LMB with a complete Luminis Platform, you may need to refer to addi-tional documentation and be aware of a few issues.

E-LEARNING

If you are implementing LMB as part of the Integration Technology for e-Learning implementation, you will also need to refer to the following publications:

Integration for e-Learning Banner Installation Guide

Integration for e-Learning Message Reference Guide

These publications will detail the additional installation and configuration steps neces-sary to install the Learning Management Gateway (LMG) and get other portions of system running.

LUMINIS PLATFORM

In some cases, you will be installing and using LMB as part of a complete Luminis Plat-form deployment. If this is the case, you need to be aware of the following:

Note: For detailed procedures on setting any of the options or properties outlined below, refer to your Luminis Platform Installation Guide.

• You cannot install the system on a Linux server.

• The following integration properties must be set as outlined: – data.integration.incoming.synchronize.cp.with.sis.credential. This property

controls whether the Luminis Platform login credential is automatically synchro-nized with the SIS credential. For e-Learning implementations, you can set this to true to default password changes to the Banner or Plus system.

– data.integration.incoming.synchronize.cp.credential.on.update. Sets whether the logon credential is updated on person update operations. The default for this property is false. This property is only used if the data.integration.incoming.syn-chronize.cp.with.sis.credential (described above) is set to false.

– data.integration.incoming.person.email.address.source. Allows you to config-ure whether a user’s e-mail address will be derived from an IMS-ES XML import


Additional setup and integration issues

or event and if so, which data element to use. The data.integration.incoming.per-son.email.address.source property can have one of three values: userid, email, or NONE. The default is userid, which extracts an e-mail identifier (possibly without the domain) from the person/userid element with a useridtype attribute that has an EmailID value. The email value will cause the Luminis Platform to extract the e-mail address from the person/email element of the XML document. The NONE value specifies that the e-mail address should not be updated through an LDISP IMS-ES XML document.

– data.integration.incoming.synchronize.cp.credential.when.none. This setting enables an account credential to be seeded whenever the account does not have a credential. The default behavior is only to seed the credential when the account is created. By default this is set to false.

– messaging.datapipeline.client.cp$cpincoming.enabled. This property sets whether the data integration adapter is enabled. For e-Learning implementations this should be set to true.

– messaging.datapipeline.client.cp$cpentityevent.enabled. This property enables the event processing between the Luminis Platform and Banner systems. The default is true.

– SCT.event.course_section.create.terms. Sets whether a course can be created or modified in the Luminis system through an event even if the associated term data for the course is not yet defined and resident in the Luminis system. If the SCT.event.course_section.create.terms property is set to False, events that attempt to create or modify courses for which there is no resident term data will fail. If the property is set to True, the course will be created or modified. To facilitate this action, the term that the course references will be partially created in the system. Unfortunately, attempts to create that same term at a future date will fail until the partially created term is deleted from the system. In the event that a partially cre-ated term must be deleted, you will not be able to recreate the term for one hour, due to a cache setting in the Luminis system. If you want to reduce this cache, you can reset the value of the following property:

bom.manager.TermManager.cache.lookup.ttl

Note: Most of these parameters are set by default or included in the di.properties file described in the next bullet point.

• Included with the Luminis Platform installation is a configuration file that needs to be adjusted and loaded into the system’s configuration directory to set up Banner or Plus integration. The sample configuration file is named di.properties and located under the following path:

$CP_ROOT/webapps/<luminis or msgbroker>/WEB-INF/config

Information on setting properties in this sample file or other properties to support integration of your Banner or Plus system with the Luminis software will be covered in the Luminis Platform Installation Guide.

• SunGard Higher Education strongly recommends setting the following configuration property to append to avoid problems with authorization events replacing roles for system users:

es.sct.role.update


Additional setup and integration issues

• If you are implementing LMB in a full Luminis Platform system, the location of the cplog4j.properties file that you configure for logging preferences will be under the following path, instead of the one outlined in the logging section of this book:

$CP_ROOT/webapps/luminis/WEB-INF/config

Administering the Luminis Message Broker

CHAPTER 2 CONTENTS

This chapter provides information about administering the Luminis Message Broker software, the destinations that it maintains, and the clients who use it to share messages.

• Administering the Luminis Message Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.2

• Pausing and resuming the Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.3

• Setting Message Broker configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.5

• Creating and managing destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.7

Creating destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.7

Setting access policies for destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.9

Managing destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.13

• Setting connection access policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.17

• Creating and managing HTTP clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.19

Creating HTTP clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.19

Resetting properties for HTTP clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.22

Deleting HTTP clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.23

• Monitoring and configuring logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.24

Message Broker logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.24

Configuring Message Broker logging characteristics . . . . . . . . . . . . . . . . . . . . . . . . . .2.26

Monitoring other system logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.30

• Backing up the system and its data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.32

Backing up the LDAP repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.32

Backing up the persistent message store and configurations . . . . . . . . . . . . . . . . . . .2.35

• Changing administrative credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.36

• Reallocating memory to the JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.37

Determining the memory allocated to the JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.37

Resetting memory allocated to the JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.37

• Resetting the Message Broker Administration Tool timeout . . . . . . . . . . . . . . . . . . . .2.39

CHAPTER 2


ADMINISTERING THE LUMINIS MESSAGE BROKER

The Luminis Message Broker (LMB) is a Java Messaging Service (JMS) provider that implements the JMS programming interface (API). The JMS API provides a method for disparate Java-based software systems or applications to communicate. LMB enhances the standard JMS model by also providing support for clients to communicate using HTTP.

The Broker Administration Tool is a graphical user interface (GUI) for administering LMB. The Administration Tool allows you to pause and resume messaging operations for the Broker, get information about the number and size of messages contained in the sys-tem, set parameters for message attributes, configure and manage the destinations clients use to publish and consume messages, set connection access policies for clients, and cre-ate HTTP clients.

Many of these same functions can also be performed through a command line interface called mbtool. This chapter outlines the administrative capabilities provided by the Broker Administration Tool and some common administrative tasks such as monitoring logs, backing up system data elements, and resetting passwords. For more information on man-aging the system using mbtool, refer to chapter 4 of this guide.

Note: If you are implementing LMB in a standalone environment, you should not have the need to adjust configuration settings in the system’s configuration directory for normal administration. However, if you do need to adjust properties in the configura-tion directory, you will need to use the configman command-line interface. For more information on using this utility, refer to the Luminis Platform Installation Guide.

Version E Feb 2, 2007 Administering the Luminis Message Broker 2.3

PAUSING AND RESUMING THE BROKER

The Message Broker Administration Tool provides a method for easily pausing and resuming the Broker if you need to temporarily halt message transmission. To pause and resume the Broker, use the following procedure:



The URL for the login page should be similar to the following, where the variable information represents the fully qualified domain name or IP address of the server upon which the Broker was installed and the port under which the Web server is running (typically 7677):










Pausing and resuming the Broker

To pause the Message Broker, click Pause.

You are alerted that the Message Broker has been paused and you are provided a Resume button, as illustrated below:

While paused, the Broker will not process messages.

To resume the Message Broker, click Resume.


SETTING MESSAGE BROKER CONFIGURATIONS

When you first log in to the Message Broker, you see an administrative tool menu simi-lar to the following:

You can use this menu to get information about the number of messages in the system and their combined size (under Broker Totals). You can use the Broker Configuration option in the menu to set limits on message number and size. To do so, use the following procedure:

If you have not already done so, open your Internet browser, enter the URL for the LMB machine, and enter your username and password to log in to the Message Broker Administration Tool.

From the options provided, click Broker Configuration.

You see the Broker Configuration window similar to the following:


Setting Message Broker configurations

The screen provides the following options:– Maximum # of messages in the system. Sets the maximum number of messages

that can be contained in all destinations (queues and topics) created and adminis-tered through the Luminis Message Broker. A value of 0 means no limit.

– Maximum size of messages in the system. Sets the maximum total size of all combined messages contained in the system's destinations. A value of 0 means no limit. By default, the system is set to 150 MB. If you adjust this value, you may also need to adjust the maximum amount of memory used by the Java Virtual Machine (JVM) in which the LMB software is deployed. Sun recommends allocat-ing twice the amount of memory to the JVM as the maximum size of messages that can be contained. For procedures on resetting the memory allocated to the JVM, refer to the section “Reallocating memory to the JVM” on page 2.37.

– Maximum message size. Sets a maximum size on each discrete message pub-lished to the system's destinations. A value of 0 means no limit.

To set a maximum number of messages that will be maintained by the sys-tem, enter a value in the field provided.

To set the maximum size that the system will support for all messages when combined, enter a value in the field provided.

The field supports the following abbreviations to designate size: m for Megabytes and k for Kilobytes. If no abbreviation is used, the system defaults to bytes.

To set a limit on the size of each individual message, enter a value in the field provided.

The field supports the following abbreviations to designate size: m for Megabytes and k for Kilobytes. If no abbreviation is used, the system defaults to bytes.

When finished setting configuration options, click Save Changes.

Your changes are preserved and you are returned to the Message Broker Adminis-tration Tool menu.

Note: The changes implemented through the Broker Configuration window are written to the following Message Queue Server configuration file:

$IMQ_VARHOME/instances/imqbroker/props/config.properties

While SunGard Higher Education does not recommend adjusting other properties contained in this file for a typical installation, your environment may warrant other modifications. For more information on the contents of this file, refer to the Sun Mes-sage Queue Administrator’s Guide.


CREATING AND MANAGING DESTINATIONS

Destinations are the intermediary locations set up to hold the messages published and consumed by clients interacting with the system. Through the Broker Administration Tool, you can create two types of destinations: queues or topics. Under the Java Messag-ing Service (JMS) specification there are two primary delivery models: point-to-point, in which a single publisher supports a single durable subscriber in a one-to-one model; and publish/subscribe, in which the messages created by a single publisher may be picked up by any number of subscribing clients who may or may not be durable.

A queue is used to support the point-to-point model. It ensures that the messages intended for a subscriber are received only by that subscriber whether the subscriber is active or not. A topic is used to support the publish/subscribe model. It allows a number of clients to receive the same messages. Typically topics are not durable, meaning that subscribing clients must be active to consume their messages. However, you can set up durable subscriptions within your topics so that subscribing clients do not loose messages in the event that they become inactive. You can also set up message selectors so that the subscribing clients only receive specific messages in which they are interested.

For more information on destinations, messaging models, and message selectors, refer to the overview chapter of this guide.

The following section outlines procedures for using the Message Broker Administration Tool to create and manage destinations.

Warning: Post installation, there are two destinations set up for internal system pur-poses: MBInternalAdminTopic and MBInternalLoggingTopic. If you modify or delete either of these destinations, the system will operate erratically or not at all.

CREATING DESTINATIONS

When you create a destination, a named representation of the destination is set up in the Broker Administration Tool and a default destination object is created in the system’s LDAP store to support the destination. You may then give clients access to the destination either as consumers or producers. To create a destination using the Message Broker Administration Tool, use the following procedure:


From the options provided, click Destinations.

You see a Destinations window similar to the following that provides a list of all the currently supported destinations, their type (topic or queue), the number of consum-ers each has, the total number of messages currently held by each, and the total size of these messages.


Creating and managing destinations

To create a new destination, click the New Destination button.

You see a Create New Destination window similar to the following:

In the field provided, enter a name for the destination.

This name must start with a letter, underscore ( _ ) or dollar sign ($). It cannot con-tain spaces and all remaining characters must be letters, digits, or the above listed symbols.

Using the radio buttons provided to select the type of destination, either Topic or Queue.

To create the destination as defined, click Create.

You are returned to the Destinations window where you see the new destination in the list, as illustrated below:



To make use of this destination, you would need to reference it through any adapters written to support external clients.

SETTING ACCESS POLICIES FOR DESTINATIONS

The Message Broker Administration Tool allows you to control client access to destina-tions at the user or group level. For each client system that you intend to access a destination, you will need to create a user (or group) that is associated with the client in the system’s LDAP store. When a client accesses the Broker, the user or group name is used for authentication. Based upon this authentication and access policies that you set up for a given destination, the Broker knows to treat the client as a consumer, producer, or browser of a given destination.

ADDING USERS TO THE LDAP STORE

To add a user or group to the system’s LDAP store to configure access restrictions for a given destination, you need to add entities under the Groups or People containers of the system’s messaging container. This structure is illustrated below, as it would appear if the Message Broker were integrated with a Luminis Platform system:



You can add users or groups using any commercially available LDAP browser as long as you put the users under the People container and groups under the Groups container, use cn as the naming attribute, and abide by the IETF RFC 2256 specification, which can be obtained from the following URL:

http://www.ietf.org/rfc/rfc2256.txt?number=2256

To add users, you can also use the Message Broker command line administration tool mbtool and the following procedure:

Log in to the server where LMB is installed as the administrative user.



mbtool add user -id=<username> -desc=<description> -credential=<password>

The user that you define will be added to the LDAP store. For example, you could add a WebCTUser to the system to support access for a WebCT client by executing the following command:

mbtool add user -id=WebCTUser -desc=WebCT client user -credential=webctpword

o=messaging

ou=Groups

ou=AdministeredObjects

cn=MessagingAdministrators

ou=People

cn=CPUser

cn=SomeOtherUser

cn=AnotherUser

cn=topic.CPMainDispatch

cn=topic.MBInternalAdminTopic

cn=topic.MBInternalLoggingTopic

cn=MBInternalQueueConnectionFactory

cn=MBInternalTopicConnectionFactory

cn=topic.CPInternalDispatch

cn=topic.CPInternalHotBackup



The code created to support the adapter for your external client should reference this user for authorization to the Message Broker. Based upon this authorization, you can configure access restrictions as outlined in the following section.

CONFIGURING ACCESS RESTRICTIONS

An access policy defines the users or groups that are specifically denied or allowed access to a destination as consumers, producers, or browsers. Each user or group that exists under the messaging container in the system's LDAP data store should map to an authorized user for a given client that is either producing or consuming messages. Before a client can access the system, it must authenticate as this authorized user. By restricting access to the destination at the user or group level, you effectively restrict access by a client.

For example, if you were using LMB to manage messaging between the Banner system and a WebCT system, each would have an associated, authorized user in the LDAP store (e.g. BannerUser, WebctUser, etc.). You could define their access by adding them or denying them as consumers, producers, or browsers under the destination that you created to hold messages being communicated between the two. Once you have added users or groups to the LDAP store using the mbtool interface, you can use the following procedure to edit their access for a given destination:



You see a Destinations window

From the Destinations list that appears, locate the destination for which you want to edit access policies and click the radio button next to its name.

Click the Edit Access button located below the list.

You see a Destination Access Policy window similar to the following:



The Destination Access Policy window allows you to add users and groups to or remove users and groups from policies that allow or deny access to the destination for the following actions.

– Consume. Defines the clients that are allowed to receive messages from the topic or queue.

– Produce. Defines the clients that are allowed to publish messages to the topic or queue.

– Browse. Defines the clients that are allowed to view messages on a queue, but who do not have the ability to consume them.

To add users or groups to any of these policies, enter the name as it appears under the LDAP ou=People or ou=Groups container to the field below the appropriate access policy and click Add.

Typically the name as stored in the directory server is prefaced by the following: cn=. When setting up access policies, do not enter the cn= portion.



To remove users or groups from any of these policies, highlight the name from the appropriate box and click Remove.

When you are finished adding users or groups to any of these policies, click Done.

MANAGING DESTINATIONS

Once a destination has been created and its access policies defined, you can use the Message Broker Administration Tool to monitor the number of consumers each has, the total number of messages currently held by each, and the total size of these messages. You can also use the Message Broker Administration Tool to purge the messages con-tained in a topic’s durable subscriptions, delete any durable subscriptions a topic might have, purge messages from a queue or topic, and delete destinations entirely. The follow-ing sections outline procedures for these activities.

MONITORING DESTINATIONS

To get information about the consumers that a destination supports and the messages that it contains, do the following:



You see a Destinations window similar to the following that provides a list of all the currently supported destinations, their type (topic or queue), the number of consum-ers each has, the total number of messages currently held by each, and the total size of these messages.

To get detailed information on a given topic destination that supports durable subscriptions, click the radio button next to its name and click Manage.

You see a Manage Destination window similar to the following that provides infor-mation about the durable subscriptions supported by the topic and the messages that they currently contain:



To return to the Destination list, click Done.

PURGING SUBSCRIPTIONS

When you purge a subscription, you clear all messages that it contains even if the con-sumers supported by a durable subscription have not yet picked up their messages. To purge the messages contained in a durable subscription set up for a topic destination, do the following:

If you have not already done so, access the Destination window by clicking the Destinations option from the Message Broker Administration Tool menu.

From the list of destinations, click the radio button next to the topic that con-tains the subscription that you want to purge.

Since Queues are always set up with single, durable consumers, there are no sub-scriptions associated with them. As such, only topics provide options to purge or delete subscriptions. To purge the messages contained in a queue, you would purge the destination as outlined on page 15.

From the Durable Subscription list that appears in the Manage Destination window, click the radio button next to the subscription that you want to purge.

Click the Purge Subscription button and respond appropriately to any addi-tional prompts.

The messages contained in the topic intended for the selected subscriber are deleted. These deleted messages will need to be resent for the subscriber to consume them.

When finished, click Done.

You are returned to the Destinations window.

DELETING SUBSCRIPTIONS

When you delete a subscription, you permanently remove it from a topic and remove the ability for clients supported by the topic’s subscription to receive messages. You also delete any messages that it might currently be saving for clients. To permanently delete a durable subscription set up for a topic destination, do the following:




From the list of destinations, click the radio button next to the topic that con-tains the subscription that you want to delete.

From the Durable Subscription list that appears in the Manage Destination window, click the radio button next to the subscription that you want to delete.

Click the Delete Subscription button and respond appropriately to any addi-tional prompts.

The selected subscription is removed from the topic. Clients supported by the sub-scription will no longer be able to receive messages.



PURGING DESTINATIONS

When you purge a destination, you delete all messages that it contains, regardless of whether clients have consumed them.To purge the messages contained in a queue or topic, do the following:


From the list of destinations, click the radio button next to the destination (topic or queue) that you want to purge.

From the Manage Destination window, click the Purge Destination button and respond appropriately to any additional prompts.

All messages from the selected destination are removed. Clients supported by the destination will no longer be able to consume these messages.



DELETING DESTINATIONS

To permanently delete a destination (topic or queue) and all messages that it currently contains, use the following procedure:

Warning: Post installation, there are two destinations set up for internal system pur-poses: MBInternalAdminTopic and MBInternalLoggingTopic. If you delete either of these destinations, the system will operate erratically or not at all.


From the list of destinations, click the radio button next to the destination (topic or queue) that you want to delete.



Click the Delete button and respond appropriately to any additional prompts.

The selected destination is permanently removed from the system.

Note: SunGard Higher Education recommends that each external client accessing the Broker have an associated user or group in the LDAP store to manage authentication and destination access. If you delete a destination and no longer require the associ-ated external clients to operate in the system, you may want to delete their associated users or groups from your directory server.


You are returned to the Message Broker Administration Tool options.


SETTING CONNECTION ACCESS POLICIES

To access the system and its destinations as a producer, consumer, or browser, each cli-ent must also be granted general connection access. Once a user (or group) is added to the system’s LDAP store to support a client, you can use the Message Broker Administration Tool and the following procedure to define a connection access policy:

If you have not already done so, add the user or group to the messaging con-tainer of the system’s LDAP store.

You can add users or groups using any commercially available LDAP browser as long as you put the users under the People container and groups under the Groups container, use cn as the naming attribute, and abide by the IETF RFC 2256 specifi-cation, which can be obtained from the following URL:


You can also add a user to the appropriate container by executing the following mbtool command:


For example, you could add a WebCTUser to the system to support access for a WebCT client by executing the following command:

mbtool add user -id=WebCTUser -desc=WebCT client user -credential=webctpword

Open an Internet browser, enter the URL for the LMB machine, and enter your username and password to log in to the Message Broker Administration Tool.

From the options provided, click Connection Access Policy.

You see a Connection Access Policy window similar to the following that provides the ability to allow or deny normal and administrative access to the Broker for users and groups.


Setting connection access policies

In the appropriate box, enter the name of the user or group for which you want to grant or deny access and click Add.

Typically the name as stored in the directory server is prefaced by the following: cn=. When setting up access policies, do not enter the cn= portion. For example, if you have a WebCT client that you intend to authorize into the Luminis Message Broker through an LDAP user named cn=WebCTUser, you would enter the value WebCTUser in the box under the Allow Users list under the Normal column and click Add.

If you need to remove a user or group from a policy, highlight the name and click the Remove button.

When finished setting access policies for users and groups, click Done.


CREATING AND MANAGING HTTP CLIENTS

One of the most powerful features of the Luminis Message Broker (LMB) is the support it provides for clients to consume messages via HTTP. The initial steps for creating an HTTP client are similar to setting up access for any other JMS client: create a user or group in the system’s LDAP store that will be associated with the client, use the Message Broker Administration Tool to set up access to a destination for the user or group in asso-ciated with the HTTP client (as a consumer in this case), then enable this user or group to get a general connection. Once these aspects are set up, you use additional options pro-vided by the Message Broker Administration Tool to name and enable an HTTP client, specify the destination from which it will consume messages, specify any message selec-tors that it will use to filter messages, set whether it is a durable connection, and specify the URL where the Broker will post the messages.

The following sections outline the process for creating new HTTP clients, modifying properties for HTTP clients, and deleting HTTP clients.

CREATING HTTP CLIENTS

To create an HTTP client that can consume messages from a given destination in the system, use the following procedure:

If you have not already done so, add the user or group that will be associated with the HTTP client to the messaging container of the system’s LDAP store.

You can add users or groups using any commercially available LDAP browser as long as you put the users under the People container and groups under the Groups container, use cn as the naming attribute, and abide by the IETF RFC 2256 specifi-cation, which can be obtained from the following URL:


You can also add a user to the appropriate container by executing the following mbtool command:



From the options provided, click Destinations|Edit Access.

You see the Destination Access Policy window.

Using the options provided through the Destination Access Policy window, grant access to this user to consume messages from the appropriate destina-tion and click Done.


Creating and managing HTTP clients

If a destination from which the HTTP client will consume messages does not already exist, you should first create it. For more information on creating and set-ting access policies for destinations, refer to the section “Creating and managing destinations” on page 2.7.

From the main Message Broker options page click Connection Access Policy.

You see the Connection Access Policy window.

Using the options provided through the Connection Access Policy window, grant connection access to this user and click Done.

From the main Message Broker options page click Outgoing HTTP Clients.

You see an Outgoing HTTP Clients window similar to the following that lists all HTTP clients maintained by the Broker, their destination types, the URLs to which messages will be posted for each, their status, and whether message delivery stops on errors.

Click the New Client button.

You see a Create Outgoing HTTP Client window similar to the following:

This window provides the following options that you use to define the characteris-tics, authentication properties, and message posting location of the HTTP client:



– Name. The name of the outgoing HTTP client as it will appear in picklists avail-able through the Message Broker Administration Tool. The name cannot contain spaces, parentheses, or asterisks. It must start with a letter, an underscore ( _ ), or a dollar sign ( $ ). All following characters must be letters or digits, but can include the underscore and dollar sign symbols.

– Enabled. Sets whether the HTTP client is enabled. If set to disabled, messages will not be posted for the client.

– Stop Delivery on Error. A drop-down that lets you specify whether message transmission will be halted when errors are encountered. If Stop Delivery on Error is set to true and an error status code is received, the client adapter will log an error, not acknowledge the message to the broker, go to sleep for a configurable period of time (default is 10 minutes), wake up, and try to post the same message again. If Stop on Delivery is set to false and an error code is received, an error will be logged to the LMB log files, the message will be acknowledged to the broker, and the HTTP client will continue with the next message. If you wish to guarantee message delivery, Stop Delivery on Error should be set to true.

– Consume From. A drop-down that lets you pick a destination from which the cli-ent should consume messages. You can set HTTP clients to consume messages from any of the topics or queues maintained by the system, but the JMS user asso-ciated with the client must be granted access to consume messages from this destination.

– JMS Connection User Name. The username under which the HTTP client will connect to LMB. This should be equal to a user created under the messaging con-tainer of the system's LDAP store that is associated with the HTTP client. This user should have been granted connection access to the Broker and access to con-sume messages from the destination selected in the field above.

– JMS Connection Password. A password associated with the user.– Verify Password. A field that allows you to retype the password to ensure

accuracy.– JMS Message Selector. A field that allows you to enter query strings that refer-

ence application-specific properties that a producing client places in a message. These are used so that the Broker can filter messages contained in a specific desti-nation for those in which the client is interested. For message selector syntax and semantics, refer to the JMS Specification.

– Durable. A drop-down that allows you to set whether the client is durable for any topic destinations. Typically, topic destinations are not durable, meaning that cli-ents must be active to consume messages posted to a topic. If you want messages to be saved for this client even when inactive, select true.

– Post to HTTP(s) URL. The HTTP or HTTPS URL to which the messages for this client will be posted.

– Authorization User Name. The name under which the client will be authorized to access the posting URL. The Message Broker uses basic HTTP authorization and will pass this username with the post operation.

– Authorization Password. The password under which the client will be authorized to access the posting URL. The Message Broker will pass this password with the post operation.

– Verify Password. A field that allows you to retype the authorization password to ensure accuracy.



Use the fields provided to define the HTTP client and its Broker access prop-erties, URL, and posting characteristics.

Click Create.

You are returned to the Outgoing HTTP Clients window where you see your new HTTP Client in the list.

RESETTING PROPERTIES FOR HTTP CLIENTS

Once you have created an HTTP client, you can reset any of the attributes that are defined for it. Typical changes would include disabling the client temporarily, resetting whether the Message Broker stops delivery on errors, or changing its subscription from type from durable to non-durable or vise versa.

To reset the properties for an existing HTTP client, use the following procedure:


From the options provided, click Outgoing HTTP Clients.

You see the Outgoing HTTP Clients window, which lists all HTTP clients main-tained by the system.

From the list, click the radio button next to the HTTP client for which you want to reset properties and click Modify.

You see a Modify Outgoing HTTP Clients window similar to the following:

Using the fields provided, reset properties for the HTTP client.



For example, you may want to temporarily disable this client and so would select false from the Enabled drop-down. Or, you may want to add query strings to the JMS Message Selector field to support changes recently made in a producing client.

It is important to note that the following properties provided through this screen are tied to destinations, connections, or message posting locations that may be refer-enced in external adapters and/or controlled by factors external to the HTTP client definitions provided within the Message Broker:

– Consume From– JMS Connection Username and Password– Post to HTTP(S) URL – Authorization Username and Password

If you adjust these properties incorrectly, messages may no longer be posted or received by consuming clients.

Click the Modify button.

To exit without changing properties, click Cancel.

DELETING HTTP CLIENTS

If you no longer need an HTTP client, you can delete it permanently from the system. To do so, use the following procedure:


From the options provided, click Outgoing HTTP Clients.

You see the Outgoing HTTP Clients window, which lists all HTTP clients main-tained by the system.

From the list, click the radio button next to the HTTP client that you want to delete and click Delete.

Respond appropriately to any additional prompts

The HTTP client is now permanently removed from the system.

Note: SunGard Higher Education recommends that each external client accessing the Message Broker have an associated user or group in the LDAP store to manage authentication and destination access. If you delete an HTTP client and no longer require the associated external clients to operate in the system, you may want to its associated user or group from your directory server.

Click Done to return the Message Broker Administration Tool options menu.


MONITORING AND CONFIGURING LOGS

When the system is running and messages are being routed through it, information about its performance, the success of message delivery, and the health of clients who are associated with the system are written to a number of log files contained under the follow-ing system directory:

<MB installation directory>/logs

You should periodically review the contents of the logs contained in this directory. If necessary, you may also need to adjust the logging verbosity on one or more logs, the amount of disk space each can consume, and the number of curricular log files that some of the logging mechanisms will write before overwriting earlier logs.

In addition to these logs, which are specific to LMB and its processes, you will also want to monitor the logs associated with the iPlanet Directory Server and Sun ONE Web server. The following sections outline the type of logs that are created by LMB and proce-dures for adjusting their characteristics, as well as the location of other system logs.

MESSAGE BROKER LOGS

The Message Broker writes information to five separate log files as follows:

• datapipeline-main.log. This file contains error and status information for the incom-ing adapter messages and for errors in HTTP client operation.

• datapipeline-audit.log. This contains the actual XML message body and status codes for HTTP client operations. Any message with a status of write_failure, client_exception, or Rejected means that data is not synchronized between the Mes-sage Broker and the incoming client data.

• mb-app.log. This log contains error and status information about the operation of the Message Broker Administration Tool Web application, the HTTP Gateway setup to help route messages to HTTP clients, and the mbtool interface.

• mb-broker.log. This log contains error and status information about the operation of the Sun ONE Message Queue server. Under a default installation of MQ server, this log is written to the $IMQ_VARHOME/instances/imqbroker/logs directory. Through configuration files in the Luminis Message Broker, the mb-broker.log has been redi-rected to be contained in the same location as other logs.

• mb-messages.log. A log that contains a record of all messages processed by the Luminis Message Broker that are associated with any administered objects created through the Message Broker Administration Tool or the mbtool interface. This log is generated only if message logging is enabled for a specific client adapter.

All of these logs are maintained within the /logs directory under the Message Broker installation root as illustrated below:


Monitoring and configuring logs

You’ll notice by this illustration that there are a few additional logs that are contained in this directory, including:

• install.log. A log containing installation information. This log can be deleted after successful installation.

• startcp.log. Provides information about the processes started using startcp.

• stopcp.log. Provides information about the processes stopped using stopcp.

Note: If your Luminis Message Broker is integrated with the Luminis Platform, you will also see a number of logs in this directory associated with Luminis Platform com-ponents. For more information on Luminis Platform logs, refer to the Luminis Platform System Administration Guide.

While the startcp and stopcp logs are not critical to Message Broker operation, you may occasionally want to look at them as well.



CONFIGURING MESSAGE BROKER LOGGING CHARACTERISTICS

You can reset the level at which information is written to the primary Message Broker logs. For circular logs, you can set the total number of logs to maintain and the size of each. To configure these logging characteristics, you must open and edit parameters in two system files:

• cplog4j.properties. This file, which is located under the following path, controls the characteristics of the datapipeline.audit.log, datapipeline-main.log, mb-app.log, and mb-messages.log files:

<Message Broker Installation Root>/webapps/msgbroker/WEB-INF/config

Note: If you are implementing LMB in a full Luminis Platform system, the location of the cplog4j.properties file that you configure for logging preferences will be under the following path: $CP_ROOT/webapps/luminis/WEB-INF/config

• config.properties. This file, which is located under the following path, controls the mb-broker.log file characteristics:

$IMQ_VARHOME/instances/imqbroker/props

WORKING WITH THE CPLOG4J.PROPERTIES FILE

The cplog4j.properties file controls the characteristics of the datapipeline.audit.log, datapipeline-main.log, mb-app.log, and mb-messages.log files. To set values in this file, use the following procedure:


Open a command window and change to the following directory:

<Message Broker Installation Root>/webapps/msgbroker/WEB-INF/config

Note: On Windows you may use the Explorer to access this directory.

From within this directory, use a text editor to open the following file:

cplog4j.properties

You see content similar to the following:

log4j.rootLogger=ERROR, filelog4j.appender.file=org.apache.log4j.RollingFileAppenderlog4j.appender.file.File=${util.logservice.log4j.directory}/mb-app.loglog4j.appender.file.MaxFileSize=1MBlog4j.appender.file.MaxBackupIndex=5log4j.appender.file.layout=org.apache.log4j.PatternLayoutlog4j.appender.file.layout.ConversionPattern=[%d{ISO8601}] [%p] [%c]:%x %m%n



log4j.logger.datapipeline=INFO, datapipelinelog4j.additivity.datapipeline=false

# set the logging level to INFO to turn on audit logginglog4j.logger.datapipeline.audit=ERROR, datapipeline-auditlog4j.additivity.datapipeline.audit=false

log4j.appender.datapipeline=org.apache.log4j.RollingFileAppenderlog4j.appender.datapipeline.File=${util.logservice.log4j.directory}/datapipeline-main.loglog4j.appender.datapipeline.MaxFileSize=1MBlog4j.appender.datapipeline.MaxBackupIndex=5log4j.appender.datapipeline.layout=org.apache.log4j.PatternLayoutlog4j.appender.datapipeline.layout.ConversionPattern=%d{ISO8601}/%c{2}: %m%n

log4j.appender.datapipeline-audit=org.apache.log4j.RollingFileAppenderlog4j.appender.datapipeline-audit.File=${util.logservice.log4j.directory}/datapipeline-audit.loglog4j.appender.datapipeline-audit.MaxFileSize=1MBlog4j.appender.datapipeline-audit.MaxBackupIndex=5log4j.appender.datapipeline-audit.layout=org.apache.log4j.PatternLayoutlog4j.appender.datapipeline-audit.layout.ConversionPattern=%d{ISO8601}/%m%n

# message logging

log4j.logger.mb.messages=INFO, messageslog4j.additivity.mb.messages=false

log4j.appender.messages=org.apache.log4j.RollingFileAppenderlog4j.appender.messages.File=${util.logservice.log4j.directory}/mb-messages.loglog4j.appender.messages.MaxFileSize=1MBlog4j.appender.messages.MaxBackupIndex=5log4j.appender.messages.layout=org.apache.log4j.xml.XMLLayout

To set the verbosity of the various logs, search for the following parameters:

Change the logging level to any of the following levels:

Log Parameter

mb-app.log log4j.rootLogger = ERROR, file

datapipeline-main.log log4j.logger.datapipeline=INFO, datapipeline

datapipeline-audit.log log4j.logger.datapipeline.audit=ERROR, datapipeline-audit

mb-messages.log log4j.logger.mb.messages=INFO, messages



To set the number and size of any rolling log files, search for the following parameters:

Set the MaxFileSize and MaxBackupIndex values as desired.

Two parameters affect the size and number of files you see in the logs directory, a file size parameter and a backup index parameter. The file size parameter specifies the size of the log file and the backup index parameter specifics the number of backup files that will be created in the logs directory, as illustrated below:

FATAL This level designates very severe error events that will presumably lead the application to abort. Messages from these events are the most terse. FATAL is ideal for critical messages generated after an application quits abnormally.

ERROR This level designates error events that might still allow the application to con-tinue running. ERROR inherits the priority of FATAL. You might set the ERROR level to capture application error messages when the application can still hobble along.

WARN This level designates potentially harmful situations. WARN inherits the priority of ERROR and FATAL. You might use WARN to log warning messages an application generates when it is able to run without problems.

INFO This level designates informational messages that highlight the progress of the application at coarse-grained level. INFO inherits the priority of WARN, ERROR, and FATAL. You could use INFO for messages that are similar to the "verbose" mode of many applications.

DEBUG This level designates fine-grained informational events that are most useful to debug an application. DEBUG inherits the priority of the previous four levels. Setting the level to DEBUG will place the greatest burden on system resources. You might use DEBUG to write debugging messages that should not be printed when the application is in production.

Log Parameter

mb-app.log log4j.appender.file.MaxFileSize=valuelog4j.appender.file.MaxBackupIndex=value

datapipeline-main.log log4j.appender.datapipeline.MaxFileSize=valuelog4j.appender.datapipeline.MaxBackupIndex=value

mb-messages.log log4j.appender.messages.MaxFileSize=valuelog4j.appender.messages.MaxBackupIndex=value



These parameters specify that when a log file reaches its maximum size, it becomes a backup file. There is a limit to the number of backup files that can be stored on the disk.

Save and close the file.

The logging verbosity and file changes take effect approximately 60 seconds after you save the file.

Note: The 60 seconds are defined with the log.log4j.watchDelay parameter in systems configuration directory.

WORKING WITH THE CONFIG.PROPERTIES FILE

The config.properties file controls the characteristics of the mb-broker.log file. To set values in this file, use the following procedure:

Log in to the server where the LMB software is installed as the administrative user.

Open a command window and change to the following directory:

Note: On Windows you may use the Explorer to access this directory.


From within this directory, use a text editor to open the following file:

config.properties

Locate the following parameters associated with logging and adjust as appropriate:

File size parameter Backup parameter

log4j.appender.file.MaxFileSize=1MBlog4j.appender.file.MaxBackupIndex=5

log4j.appender.file=org.apache.log4j.RollingFileAppenderlog4j.appender.file.File=${util.logservice.log4j.directory}/mb-app.loglog4j.appender.file.MaxFileSize=1MBlog4j.appender.file.MaxBackupIndex=5log4j.appender.file.layout=org.apache.log4j.PatternLayoutlog4j.appender.file.layout.ConversionPattern=[%d{ISO8601}] [%p] [%c]:%x %m%n



Save the config.properties file.

You will need to shut down and restart the Broker to effect changes. To do so, use the mbtool stop broker and mbtool start broker commands.

Note: You can also reset the log.level, log.file.rolloverbytes, and log.file.rolloversecs properties without restarting the system using the mbtool update broker command. For more information on using this command, refer to the chapter of this guide that outlines the mbtool command line interface.

MONITORING OTHER SYSTEM LOGS

The third-party products integrated into the Luminis Message Broker also provide logs that you should monitor periodically. These third-party products include the following:

• Directory Server

• Web Server

Parameter Effect

imq.log.file.dirpath=/pipeline/logs Sets the location where the mb-broker.log file will be written. The value of this parameter is automatically set upon installation to write into the /logs directory containing other Message Broker log files. You should not have to change this value.

imq.log.file.filename=mb-broker.log Sets the name of the log file. You should not have to change this value.

imq.log.file.rolloverbytes=<value> Specifies the size, in bytes, of log file at whichoutput rolls over to a new log file. A value of 0, which is the default, means no rollover based on file size.

imq.log.level=<value> Specifies the Logger level: the categories of outputthat can be written to an output channel. Includesthe specified category and all higher levelcategories as well. Values, from high to low, are:ERROR, WARNING, INFO. Default: INFO

imq.log.file.rolloversecs=<value> Specifies the age, in seconds, of a log file at whichoutput rolls over to a new log file. A value of 0 means no rollover based on age of file. The default is 604800 (one week).

Note: There are a number of other parameters that can be added to this file to set behavior of the MQ log file; however, in a typical LMB installation you should not need to use them. For more information on these and other properties, refer to the Sun ONE Message Queue Administrator’s Guide.



This section lists the logs these products generate, their locations on the LMB server, and provides references to the vendor documentation where you can find the details.

DIRECTORY SERVER

The Directory Server generates access, error, and audit logs. These logs are located in the following directories:

You should monitor logs regularly as they provide important information for both the Directory Server and the LDAP database. The Sun documentation explains how to do monitor and use the logs. See the Sun Directory Server 5.2 Administrator's Guide.

WEB SERVER

The Web Server generates error logs that are located in the following directory:

$CP_ROOT/products/tomcat/tomcat-mb/logs

You may want to periodically review the standard error (stderr) and standard output (stdout) logs.

Table 2–1.

Name Linux/UNIX Windows

opt/products/ds... Sun\Server-Root...

Access Log .../slapd-serverID/logs/access ...\slapd-serverID\logs\access

Error Log .../slapd-serverID/logs/error ...\slapd-serverID\logs\error

Audit Log .../slapd-serverID/logs/audit ...\slapd-serverID\logs\audit


BACKING UP THE SYSTEM AND ITS DATA

The Luminis Message Broker (LMB) utilizes the Sun ONE Message Queue (MQ) server for its JMS implementation and the iPlanet Directory Server for its LDAP reposi-tory. The messages that are routed through the system are temporarily maintained in a persistent message store under the MQ file system. Some information about the destina-tions and objects that you create through LMB are also maintained in this filestore, as well as in the LDAP repository. Both the LDAP repository and the file system should be backed up regularly and in unison.

BACKING UP THE LDAP REPOSITORY

To ensure that you can recover from server failures such as a crashed disk, and to help with your upgrades to future versions of LMB, you should frequently export the LDAP directory as a Lightweight Directory Information Format (LDIF) file.

An LDIF file contains a snapshot of the entire LDAP directory that can be reimported into the LDAP database if you have to rebuild it during a disaster recovery or a software upgrade. One advantage of this approach is that LDIF is database-independent. You can use any LDAP directory browser to connect to the LDAP server as the administrative user and export the entire directory as an LDIF file. In addition, you can use the Sun ONE Directory Server console application itself to export the directory.

The Directory Server also includes two scripts that can be used to back up the LDAP store in LDIF format and recover it:

• db2ldif. A backup script

• ldif2db. A restore script

These scripts are located in the following directory depending on your operating system:

Linux/UNIX

opt/<MB installation directory>/products/ds/slapd-<DS server id>

Windows

<installation drive>:Sun\Server-Root\slapd-<DS server id>

To export the LDAP data as an LDIF file, do the following:


The installation process gives the administrative user permission to modify the LDAP directory.



Backing up the system and its data

Stop the Message Broker system and its environment by typing the following:

stopcp -a

Change to the directory that contains the db2ldif script:

The script is located in the following directory depending on your operating system:

Linux/UNIX


Windows


Use the db2ldif script to export the critical LDAP components to LDIF files.

Use the following syntax for each LDIF that you will create:

Note: On Windows, use a .bat extension with the script (db2ldif.bat).

db2ldif -n userRoot -a <path to output file>db2ldif -n internetdb -a <path to output file>db2ldif -n messaging -a <path to output file>db2ldif -n NetscapeRoot -a <path to output file>db2ldif -n luminisconfig -a <path to output file>db2ldif -n PiServerDbdb2 -a <path to output file>

Note that these commands use the typical backend instance for each LDAP compo-nent (i.e. userRoot, pabdb, etc.). To determine the backend instance, you can type the following for each suffix outlined below: “suffix2instance -s <suffix>”

o=<your root DN>o=interneto=LISo=NetscapeRooto=luminisconfigo=PiServerDbdb2

Alternately, you could create an LDIF that stores multiple suffixes in a single file using a -s switch and the specific suffix for each component. The command would look similar to the following:

Note: On Windows use a .bat extension with the script (db2ldif.bat).

db2ldif -s “<suffix>” -s “<suffix>” -s “<suffix n>” -a <path to output file>

For example, typing the following will export the entire Wasatch College database as an LDIF file called “export.ldif” and store it in the $CP_ROOT directory:

db2ldif -s “o=wasatch” “o=internet” “o=messaging” “o=NetscapeRoot” “o=luminisconfig” “o=PiSErverDbdb2” -a $CP_ROOT/export.ldif


Backing up the system and its data

Restart the Message Broker typing the following from a command window (on Windows use Cygwin):

startcp

If you need to recreate the database from a backup that has been stored in LDIF format use the following procedure:



Stop the Message Broker and its environment by typing the following:

stopcp -a

Change to the directory that contains the ldif2db script:

The script is located in the following directory depending on your operating system:

Linux/UNIX


Windows


Use the ldif2db script to import an LDIF file.

Note: On Windows, use a .bat extension with the script (ldif2db.bat).

ldif2db -s “<suffix>” -s “<suffix>” -s “<suffix n>” -i <path to input file>

The example for this command should read:

ldif2db -i -s “o=wasatch” -s “o=internet” -s “o=messaging” -s “o=NetscapeRoot” -s “o=luminisconfig” -s “o=PiSErverDbdb2” $CP_ROOT/export.ldif

Note: If you have backed up each LDAP component separately using the -n option and the backend instance, you will need to import each LDIF using a -n switch and the name of the backend instance.

Restart the Message Broker by typing the following from a command window (on Windows use Cygwin):

startcp


BACKING UP THE PERSISTENT MESSAGE STORE AND CONFIGURATIONS

Additional information about the objects and destinations created through LMB and the messages routed through the system are also located in the Message Queue file system under the following path:

$IMQ_VARHOME/instances/imqbroker/fs350

Note: The IMQ_VARHOME variable is typically under the products/MQ directory within the Luminis Message Broker installation root; however, this may differ if you have installed the system on a UNIX server.

The number of messages that can be contained in this persistent filestore and their com-bined size is configured through the Message Broker Administration Tool, so you do not need to manually administer this directory or its contents in any way. However, you should include this directory and the following directory that contains configuration data for the system in a file system backup routine:


The file system backup should be timed to coincide with the backup of the LDAP data store outlined in the previous section.


CHANGING ADMINISTRATIVE CREDENTIALS

During installation, credentials for the administrative user associated with the Luminis Message Broker were defined by supplying specific values to the following parameters:


To facilitate interaction of the Luminis Message Broker software with other system components, like the Directory Server, the value of these credentials are also written into other areas of the system. If you need to change the password for the Message Broker administrator, an mbtool command is provided. You can change the credentials using the following procedure:



At the prompt type the following command, replacing the variable with the new password that you want to use:

mbtool change adminpassword -credential <new password>

The configuration directory also contains the following properties that are used to facili-tate authentication free terminal access to mbtool commands:

mbtool.password={messaging.admin.credential}mbtool.username={messaging.admin.id}

If you wish to change the behavior to require the system to prompt for authentication with each mbtool session or to pass the mbtool credentials at the command line, you can use the configman -s command to set the these properties to invalid values:

configman -s mbtool.password <invalid password>configman -s mbtool.username <invalid username>

When the properties are set to use values that do not match those set for the mesag-ing.admin.credential and messaging.admin.id properties during installation, the system will prompt to supply correct passwords when mbtool is executed.

Note: To execute the configman script on Windows you must use Cygwin.


REALLOCATING MEMORY TO THE JVM

Sun recommends allocating twice the amount of memory to the JVM as the maximum size of messages that can be contained in the system. For example, if you reset the maxi-mum size of messages from 150 MB, which is the default, to 200 as outlined in the following illustration, you will need to increase the memory allocated to the JVM from 300 MB to 400 MB.

To determine the maximum amount of memory allocated to the JVM and to adjust this value, you can use two scripts provided with the LMB software: mbgetmaxheap and mbsetmaxheap. Both scripts are contained in the system’s bin directory and can be run from the command line (Cygwin on Windows). The following sections provide proce-dures for determining and resetting the memory allocated to the JVM.

DETERMINING THE MEMORY ALLOCATED TO THE JVM

To determine how much memory is allocated to the JVM, use the following procedure:

Log in to the server as the administrative user.

Open a command window (on Windows use Cygwin)

At the prompt, type the following command:

mbgetmaxheap

You see the amount of memory allocated to the JVM in megabytes.

RESETTING MEMORY ALLOCATED TO THE JVM

To reset the amount of memory allocated to the JVM, use the following procedure:

Caution: Sun recommends allocating twice the memory to the JVM as the amount of space allocated to messages in the system.


Reallocating memory to the JVM

On Windows, log in to the server as the administrative user. On UNIX, log in as root.

Open a command window (on Windows use Cygwin)

At the prompt, type the following command replacing the variable as appropriate:

mbsetmaxheap <value>

The value you stipulate is in megabytes. For example, to reset the memory allocated to the JVM to 400 MB, you would type the following:

mbsetmaxheap 400

Using the following commands, shut down and restart the Broker for changes to take effect:

mbtool stop brokermbtool start broker


RESETTING THE MESSAGE BROKER ADMINISTRATION TOOL TIMEOUT

By default, the timeout for the Message Broker Administration Tool Web client is set to 30 minutes. However, you can change this timeout by adding a configuration parameter to the following file:

$CP_ROOT/webapps/msgbroker/WEB-INF/web.xml

To edit this file and reset timeouts for the Message Broker Administration Tool, do the following:


Change to the following directory

$CP_ROOT/webapps/msgbroker/WEB-INF

Using an editor, open the web.xml file

Locate the following section of the file:

<servlet-mapping> <servlet-name>outgoing</servlet-name> <url-pattern>/secure/outgoing</url-pattern> </servlet-mapping>

<welcome-file-list> <welcome-file>index.html</welcome-file> </welcome-file-list>

After the last </servlet-mapping> tag, enter a space and then add the following:

<session-config> <session-timeout>30</session-timeout> </session-config>

Set the timeout value as appropriate to your needs.

For example, if you wanted to reset the default 30 minute timeout to 60 minutes, your web.xml file should look like this:

<servlet-mapping> <servlet-name>outgoing</servlet-name> <url-pattern>/secure/outgoing</url-pattern> </servlet-mapping>

<session-config> <session-timeout>60</session-timeout> </session-config>

<welcome-file-list>


Resetting the Message Broker Administration Tool timeout

<welcome-file>index.html</welcome-file> </welcome-file-list>

Using the following commands, shut down and restart the Broker for changes to take effect:

mbtool stop brokermbtool start broker

It is important to note that the changes you have made in the web.xml file will not be preserved with subsequent system patches or upgrades.

Creating and managing administered objects

CHAPTER 3 CONTENTS

This chapter provides information about creating new administered objects to support custom integration efforts and managing the administered objects resident in the system.

• Creating and managing administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.2

• Creating administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.3

• Managing administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.13

Modifying object properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.13

Deleting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.14

CHAPTER 3


CREATING AND MANAGING ADMINISTERED OBJECTS

To facilitate portability, the information needed for clients to interact with the system are stored independent of the clients and their adapters as objects. In the JMS model, these are referred to as administered objects, of which there are two types: destination and connection. Destination objects provide the information required for clients to lookup and use the physical destinations that store the messages. Connection objects provide the information necessary for clients to access the system and actually send and receive messages.

The Luminis Message Broker stores these objects in the Sun Directory Server. This chapter provides information about creating and administering objects using the Message Broker Administration Tool.

Note: Many of the same operations can be performed using the mbtool command line interface. For more details on the commands and options available through the mbtool interface, refer to the chapter of this guide that outlines the mbtool command line interface.

Version E Feb 2, 2007 Creating and managing administered objects 3.3

CREATING ADMINISTERED OBJECTS

Administered objects are created to support client interaction with the Luminis Message Broker (LMB). Typically, creation of administered objects is done in conjunction with custom integration projects where adapters are being written for clients who will interact with the system. During the course of these projects, the individuals developing the adapt-ers will anticipate the objects that they will need. Before the client adapters can be plugged into the system, the anticipated objects will need to be created to the specifica-tions defined by the adapter developers.

In general, there are two basic objects required to support each client: a destination object, which defines the properties of the topic or queue that will be used by the client to hold messages that are to be submitted or retrieved; and a connection object, which defines how the client will be able to access the system and actually send or receive mes-sages. By defining and storing the properties of each destination and connection as objects that are independent of the applications that are using them, the system ensures portability and extensibility. For example, if a single connection object is used by a num-ber of clients, you can make changes to the object to adjust things like flow control or connection attempts without going into the code for each client adapter and making modifications.

The properties of each object are defined by the Java Messaging Service specification and, for LMB, created and stored in an LDAP-based directory server. The properties for both destination and connection objects are outlined in the table below:

Note: The definitions provided for the following attributes have for the most part been derived from information provided in the Sun Message Queue Developers Guide, Ver-sion 3.6. SunGard Higher Education recommends that if you are creating or modifying administered objects, you refer to this guide and to the Sun Message Queue Administrators Guide. Both documents can be obtained from the following Web site: http://docs.sun.com/.

Object Type Property Description

Destination imqDestinationName This is the name you assign to the physi-cal destination that corresponds to the topic or queue administered object. The name you supply here is stored as an attribute of the object, but is not related to the object name that you used to create the object (e.g. cn=ObjectName). Desti-nation names can contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the underscore ( _ ) or dollar sign ( $ ).

Destination imqDestinationDescription A description of the object that can be retrieved through the Java code of the adapter that uses the object.


Creating administered objects

Connection Factory imqOverrideJMSPriority Specifies whether the JMSPriority field set by the client can be overridden. The default is false.

imqFlowControlLimit When the value of imqFlowControlIsLim-ited is enabled, this parameter specifies a limit on the number of unconsumed mes-sages that can be delivered to a client. When the number of JMS messages delivered to the client (in accordance with the flow metering governed by imqFlow-ControlCount) exceeds the limit, message delivery stops. It is resumed only when the number of unconsumed messages drops below the value set with this property. This limit prevents a con-suming client that is taking a long time to process messages from being over-whelmed with pending messages that might cause it to run out of memory. The default is 1000.

imqOverrideJMSExpiration Specifies whether the client-set JMSExpi-ration field can be overridden. The default is false.

imqConnectionType Specifies the transport protocol of the connection service used by the client. Supported types are TCP (default), TLS, and HTTP. Note that this is not the same as the LMB HTTP client setup.

imqLoadMaxToServerSes-sion

Used only for JMS application server facilities. This property specifies whether a Message Queue connection consumer should load up to the maximum number of messages into a server session, value=true, or load only a single mes-sage at a time, value=false. The default is true.

imqReconnectDelay If the imqReconnect parameter is set to true, this parameter specifies the time between successive attempts of the client to reconnect to the Message Queue server. The default is 30000 milliseconds.

Connection Factory imqSetJMSXUserID Specifies whether Message Queue should set the JMSXUserID property on produced messages to the identity of the user sending the message. The default is false.




imqConfiguredClientID Specifies the value of an administratively configured ClientID used to provide a unique identity for each user. The default is null.

imqJMSDeliveryMode Specifies the override value of the JMS-DeliveryMode property. Values are 1 for non-persistent, and 2 for persistent. The default is 2.

imqConnectionURL If imqConnectionType is set to HTTP, this property specifies the URL that will be used to connect to the Message Queue server. The default is http://localhost/imq/tunnel. HTTPS connections are also sup-ported, with a typical URL similar to the following: https://hostName:port/imq/tun-nel. This property should not be confused with the HTTP URL that you can provide for HTTP clients created through the Luminis Message Broker.

imqJMSPriority Specifies an override value of the mes-sage priority using an integer from 0 to 9. The default is 4, meaning normal.

imqBrokerHostName If the imqConnectionType is either TCP or TLS, this property specifies the broker host name for the connection. The default is localhost; however, you should set this value as the fully qualified domain name (FQDN) of the server on which the Lumi-nis Message Broker is installed.

imqJMSExpiration Specifies the override value of JMSExpi-ration in milliseconds. The default is 0, which means it does not expire.

Connection Factory imqFlowControlCount Specifies the number of JMS messages in a metered batch so that Message Queue control messages are not blocked by heavy JMS message delivery. When this number of JMS messages is deliv-ered to the client, delivery is temporarily suspended, allowing any control mes-sages that had been held up to be delivered. Payload message delivery is resumed upon notification by the client, and continues until the count is again reached. If the count is set to 0, then there is no restriction on the number of JMS messages in a metered batch. The default is 100.




imqAckOnProduce If set to true, the broker acknowledges receipt of all JMS messages (persistent and non-persistent) from the producing client, and the producing client thread will block waiting for those acknowledge-ments. If set to false, the broker does not acknowledge receipt of any JMS mes-sage (persistent or non-persistent) from the producing client, and the producing client thread will not block waiting for bro-ker acknowledgements. If not specified, broker acknowledges receipt of persis-tent messages only, and producing client thread will block waiting for those acknowledgements. The default is not specified.

imqFlowControlIsLimited If enabled with a value of true, this parameter is used to control message flow. The default is false.

imqAckTimeout Specifies the maximum time in millisec-onds that the client will wait for any broker acknowledgement before throw-ing an exception. For example, the first time a broker authenticates a user against an LDAP repository over a secure (SSL) connection, it can take upwards of 30 seconds to complete authentication. If the value of imqAckTim-eout is set too small, the client can time out. A value of 0, which is the default, means there is no timeout.

Connection Factory imqReconnectRetries If imqReconnect is set to true, this parameter specifies the number of attempts the client will make to recon-nect to the broker. A value of 0, which is the default, indicates that the number of retries is not limited.




imqAckOnAcknowledge If set to true, the broker acknowledges all consuming client acknowledgements, and the consuming client thread will block waiting for such broker acknowledge-ments. If set to false, the broker does not acknowledge any consuming client acknowledgements, and the consuming client thread will not block waiting for such broker acknowledgements. If not specified, the broker acknowledges con-suming client acknowledgements for AUTO_ACKNOWLEDGE and CLIENT_ACKNOWLEDGE modes, whereby the consuming client thread will block waiting for such broker acknowl-edgements. However, when not specified, the broker does not acknowl-edge consuming client acknowledgements for DUPES_OK_ACKNOWLEDGE mode, whereby the consuming client thread will not block. The default is not specified.

imqDefaultPassword Specifies the default password that will be used to authenticate with the broker. The default is guest.

imqQueueBrowserMaxMes-sagesPerRetrieve

Specifies the maximum number of mes-sages that the client will retrieve at one time when browsing the contents of a queue destination. The default is 1000.

imqDefaultUsername Specifies the default user name that will be used to authenticate with the broker. The default is guest.

imqSetJMSXAppID Specifies whether the Message Queue should set the JMSXAppID property on produced messages to the identity of the application sending the message. The default is false.

Connection Factory imqSetJMSXRcvTimestamp Specifies whether the Message Queue should set the JMSXRcvTimestamp prop-erty on consumed messages to the time the message is delivered to the con-sumer. The default is false.




Connection Factory imqBrokerServicePort If the imqConnectionTypevalue is either TCP or TLS, this parameter specifies a port on which a connection should be attempted, bypassing a connection through the broker host port. This attribute is used mainly to provide for connections through a firewall, in which case you want to minimize the number of open ports. To use this feature, you have to start a specific service on a specific port using the broker’s connection ser-vice configuration properties. The default is 0, which indicates that it is not used.

imqDisableSetClientID Specifies whether the client is prevented from changing the ClientID using the set-ClientID() method in the JMS API. The default is false.

imqSetJMSXConsumeTXID Specifies whether the Message Queue should set the JMSXConsumerTXID property on consumed messages to the transaction identifier of the transaction within which the message was con-sumed. The default is false.

imqOverrideJMSDelivery-Mode

Specifies whether the client-set JMSDe-liveryMode field can be overridden. The default is false.

imqBrokerHostPort If the value of imqConnectionType is either TCP or TLS, this parameter speci-fies the broker host port. The default is 7676; however, if you installed the Lumi-nis Message Broker using another port, update the value of this parameter to match.

imqReconnect Specifies whether the client will attempt to reconnect to the broker if the connec-tion is lost. The default is false.

imqQueueBrowserRetrie-veTimeout

Specifies the maximum time that the cli-ent will wait to retrieve messages when browsing the contents of a queue desti-nation before throwing an exception. The default is 60000 milliseconds.




The Message Broker Administration Tool provides an easy way to create destination and connection objects and to define their specifications. To create an object, use the fol-lowing procedure:

Note: In most cases, you will be creating objects to match specifications given you buy the individual who created the client adapters that will use the objects. These specifi-cations will outline the object name and other attributes from the list above that must be set. If you’ve been given such instructions, make sure you have them before con-tinuing with this procedure.



The URL for the login page should be similar to the following, where the variable information represents the fully qualified domain name or IP address of the server upon which the broker was installed and the port under which the Web server is run-ning (typically 7677):







admin.id

Connection Factory imqSetJMSXProducerTXID Specifies whether the Message Queue should set the JMSXProducerTXID prop-erty on produced messages to the transaction identifier of the transaction within which this message was pro-duced. The default is false.

imqSSLIsHostTrusted If the value of imqConnectionType is TLS, this parameter specifies whether the host is trusted. The default is true and the JMS code does not currently support another option.

imqOverrideJMSHeadersTo-TemporaryDestinations

Specifies whether overrides apply to tem-porary destinations. The default is false.




admin.password


Click the Administered Objects option.

You see an Administered Objects window similar to the following that lists the objects maintained by the system and their type:

From below the list of objects, click the New Object Button.

You see a New Administered Object window similar to the following that allows you to specify the name and type of object that you are creating:



In the Name field, enter a JNDI lookup name for the object.

The name must be preceded by the following notation:

cn=

Additionally, the name cannot contain spaces and should consist only of letters and digits. You should avoid special characters and symbols, as many of these will cause errors or must be escaped properly to be used. For example, to create a queue object for a WebCT client you could enter the following:

cn=WebCTQueue

From the options provided, click the radio button for the type of object that you are creating.

You can create five types of objects, as outlined below:– Queue. A destination type that supports a queue used in a point-to-point

implementation.– Topic. A destination type that supports a topic used in a publish/subscribe

implementation.– Connection Factory. A connection object that can be used when implementing

JMS 1.1 to set up either queue or topic connections.– Queue Connection Factory. A queue connection object provided for backward

compatibility for JMS connections where the types (queue and topic) were required to be in separate domains.

– Topic Connection Factory. A topic connection object provided for backward compatibility for JMS connections where the types (queue and topic) were required to be in separate domains.

Click Next.

You are presented with a Create Administered Object window that allows you to specify the attributes that can be set for the object based upon its type, either desti-nation or connection factory.

Fill in the fields as appropriate for the type of object you are creating and the properties that it should have.

For a Destination object you only need to provide a name and description. For Con-nection Factory objects there are two critical properties that you must verify or adjust: the imqBrokerHostName, which should by default be the fully qualified



domain name of the machine on which LMB is installed; and imqBrokerHostPort, which should be the port specified during installation for LMB to run on (7676 by default).

For a list of the additional properties supported by Connection Factory objects and how they can be set, refer to the table on page 3.3.

When you are finished setting properties, click Create.

The object as you have defined it is created. You are returned to the Administered Objects window where you see the new object that you created in the list of those maintained by the system.


MANAGING ADMINISTERED OBJECTS

Occasionally you may need to adjust the properties of an administered object to change the way it behaves for the clients that are using it. In some instances, if the clients who are using the objects are no longer participants in the messaging system, you may need to delete the objects that had been created for them. This section provides information for modifying or deleting objects.

MODIFYING OBJECT PROPERTIES

With the exception of the name that was used to create the object in the directory server, all object properties that were used to initially create an object can be changed using the Message Broker Administration tool. To do so, use the following procedure:


From the options provided, click Administered Objects.

You see an Administered Objects window that lists all of the administered objects maintained by the system and their type.

From the Administered Objects list that appears, locate the object for which you want to change properties and click the radio button next to its name.

Click the Modify button located below the list.

You see a Modify Administered Object window that allows you to reset the attributes available for the object’s type, either destination or connection factory.

Update information in the fields as appropriate for the type of object you are modifying.

For a list of the properties supported by administered objects and how they can be set, refer to the table on page 3.3.

Caution: While objects are created to be independent of the clients or adapters that are employing them, some changes to the object properties may cause unforeseen problems for clients or adapters that have not employed the JMS specification accu-rately enough to support complete extensibility. After making changes to an object, you should verify that the clients that rely on the object can still send and receive messages.

When you are finished updating properties, click Modify.

The object is redefined as you specified. You are returned to the Administered Objects window.


Managing administered objects

DELETING OBJECTS

To delete an object no longer required by any external or internal clients, use the fol-lowing procedure:


From the options provided, click Administered Objects.

You see an Administered Objects window that lists all of the administered objects maintained by the system and their type.

From the Administered Objects list that appears, click the radio button next to the object that you want to delete.

Click the Delete button and respond appropriately to any additional prompts.

The selected object is permanently removed from the system.

Caution: If you delete an object upon which active clients rely, they will no longer be able to send or receive messages. Before deleting an object, verify that it is no longer used by any of the clients that interact with the system.


You are returned to the Message Broker Administration Tool options.

Using mbtool

CHAPTER 4 CONTENTS

This chapter provides information about administering the Luminis Message Broker (LMB) soft-ware, the destinations that it maintains, and the clients who use it to share messages using the mbtool command line interface.

• Using mbtool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.2

• mbtool commands and options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.3

• Executing mbtool commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.13

CHAPTER 4


USING MBTOOL

In addition to the Luminis Message Broker Administration Tool, the system provides a command line utility called mbtool that you can use to:

• Monitor, start, stop, and configure the broker

• Create and manage destinations and their access policies

• Create and manage connection access policies

• Create and manage HTTP clients

When executed through mbtool these activities are the same as when executed through the Broker Administration Tool. In these instances, use of mbtool or the Message Broker Administration Tool is a matter of preference. However, as indicated in previous chapters of this guide, the mbtool interface is the only tool that provides the capability to add a user to the system’s LDAP store to support client connection and destination access policies.

This chapter provides a comprehensive list of the commands and options provided by the mbtool interface and a general procedure for running them. Prior to using the informa-tion in this chapter, you should review the other chapters in this book to understand how the mbtool interface mirrors the administrative commands available through the Message Broker Administration Tool.

Version E Feb 2, 2007 Using mbtool 4.3

MBTOOL COMMANDS AND OPTIONS

The following table outlines the commands and options provided by the mbtool interface.

Action Subject Arguments Effect

add adminobj -rdn=<name>

-obj=(topic|queue|tcf| qcf)

[-property=<JMS prop-erty name>:<value>]

Adds the specified administered object to the system. The rdn value is the distinguished name that will be used in LDAP to create the object. It must take the form cn=name. The obj argument defines the type of object: topic, queue, topic connec-tion factory (tcf) or queue connection factory (qcf). The optional property argument allows you to pass a value for one or more specific JMS proper-ties, such as imqBrokerHostName.

destination -dest=<name>

-type=<topic|queue>

Adds the specified destination to the system. The value of the dest argu-ment is the destination name. The name must start with a letter, under-score ( _ ) or dollar sign ($). It cannot contain spaces and all remaining characters must be letters, digits, or the above listed symbols. The type argument allows you to define whether the destination is a topic or queue.


mbtool commands and options

add httpclient -client=<client id>

-http.username=<http username>

-http.password=<http-password>

-http.url=<http[s]://<host>[:<port>][/uri]

-enabled=(true|false)

-http.stopDeliveryOn-Error=(true|false)

-username=<jms username>

-credential=<jms user password>

-mes-sage.source.name=<destination name>

-mes-sage.source.type=<(topic|queue)

-message.selec-tor=(NONE|<message selector>

-durable=(true|false)

Adds the specified HTTP client to the system. The client argument sets the name of the client. The name must start with a letter, underscore ( _ ) or dollar sign ($). It cannot contain spaces and all remaining characters must be letters, digits, or the above listed symbols. The http.username and http.password arguments allow you to pass in any authorization cre-dentials you want a client to use to gain access to the destination URL, which is set by the http.url parame-ter. The enabled parameter allows you to set whether the broker will post messages for the client. The http.stopDeliveryOnError parame-ter sets whether the broker will stop delivery if it encounters errors. The username and credential argu-ments allow you to pass in the name and password for the user contained in the system’s LDAP store that is associated with the client so that the client can get an authorized connec-tion to its destination. The destination is defined by message.source.name, which should be the value of an exist-ing destination created in the system. The message.source.type argu-ment allows you to define the destination’s type, either topic or queue. The message.selector argu-ment allows you to stipulate whether the broker will filter messages for the client, either setting no (NONE) or specifying JMS-compliant query strings to use. the durable argument allows you to specify whether mes-sages are preserved for the client even when inactive.




add user -id=<username>

-desc=<description>

-credential=<pass-word>

Allows you to create a user in the system’s LDAP store to associate with a JMS client. The id parameter is the name. The name must start with a letter, underscore ( _ ) or dollar sign ($). It cannot contain spaces and all remaining characters must be let-ters, digits, or the above listed symbols. The desc argument allows you to add a description, which can be pulled from the LDAP store by any properly coded adapter. The creden-tial argument is used to create a password.

change adminpassword -credential <pword> Changes the Message Broker admin-istrator password set during installation.

Note: This command is only avail-able in LMB 3.2 or higher systems.

delete adminobj -rdn=<value> Allows you to delete an administered object from the system by using the rdn value to specify the object. The value must be in the format cn=name.

destination -dest=<name>

-type=(topic|queue)

Allows you to delete a destination from the system using the dest argu-ment to specify its name and type argument to specify whether the des-tination to delete is a topic or queue.

httpclient -client=<client id> Allows you to delete a defined HTTP client using the client argument to specify its unique client id (name).

subscription -dest=<destination name>

-sub=<subscription name>

-client=<client id>

Allows you to delete a durable sub-scription from a topical destination. The dest argument allows you to specify the destination from which the subscription will be deleted. The sub argument allows you to specify the subscription. The client argu-ment allows you specifically identify the client.

user -id=<username> Allows you to delete a user that has been previously created in the LDAP store to support authentication of a JMS client. The id argument is used to specify the name.




list adminobj -rdn=<value> Allows you to list a specific adminis-tered object maintained by the system by using the rdn value to specify the object. The value must be in the format cn=name. The return contains the object’s distinguished name, Java class, version, whether it is read only, and the values of the specific JMS properties that have been set for it, such as imqBrokerHostName.

adminobjs Allows you to list all administered objects maintained by the system including their distinguished name, their Java classes, versions, whether they are read only, and the values of the specific JMS properties that have been set for them, such as imqBrokerHostName.

brokerstatus Allows you to list details about the broker’s status, including the current number of messages in system, the maximum size allowed for all mes-sages in system, the maximum number of messages allowed in the system, the current size of mes-sages in system, and the maximum size allowed for each individual message.

clientaccess -policy=(allow|deny)

-entity=(user|group)

-conn=(normal|admin)

Allows you to list connection policies implemented by the system for the users or groups contained in the LDAP store that are associated with JMS clients. The policy argument allows you to filter the output for con-nection policies that are either allowed or denied. The entity argu-ment allows you to specify whether to list users or groups. The conn argu-ment allows you to list those connections that either have normal or admin access. The return lists the clients that meet the stipulation of all three parameters.




list destaccess -policy=(allow|deny)


-access=(con-sume|produce|browse)

-dest=<destination name>

-type=(topic|queue)

Allows you to list destination access policies implemented by the system for the users or groups contained in the its LDAP store that are associ-ated with JMS clients. The policy argument allows you to filter the out-put for access policies that are either allowed or denied. The entity argu-ment allows you to specify whether to list users or groups. The access argument allows you to list clients that can be consume, produce, or browse messages for a given desti-nation. The dest parameter allows you to stipulate the destination for which you want to list policies. The type parameter allows you to specify the type of destination, either topic or queue. The return lists the clients that meet the stipulation of all three parameters.

destinations Allows you to list all destinations maintained by the system including their name and type.

deststatus -dest=<destination name>

-type=(topic|queue)

Allows you to list the status of a spe-cific destination as defined by the destination name provided through the dest argument and whether it is a topic or queue as defined by the type argument. The return lists the total size of messages currently con-tained in the destination, the maximum size per message, the number of consumers it has, and the number of messages it contains.

httpclients Allows you to list the HTTP clients maintained by the system and their attributes including names, the URL to which messages are posted, whether they are durable clients, the credentials used for access to the URL, the destination setup for the cli-ent, the credentials held for the user or group created in the system’s LDAP store to support the authoriza-tion for the associated JMS client, whether the client is enabled, and whether message delivery is set to stop on errors.




list subscriptions -dest=<destination name>

Allows you to list information about all subscriptions maintained for a given destination using the dest argument to specify the name of the destina-tion. The return lists information about each subscription including the number of messages held, whether the subscription is active or inactive, the subscription name, and its unique client id.

substatus -dest<destination name>


-client=<client id>

Allows you to list information about a specific subscriptions maintained for a given destination. The dest argu-ment is used to specify the name of the destination. The sub argument is used to specify the subscription name. The client argument is used to specify the subscription’s unique client ID. The return lists information about the number of messages held by the subscription and whether the subscription is active or inactive.

user -id=<user identifier> Allows you to list information about a user contained in the system’s LDAP store that is associated with a JMS client. The id argument allows you to specify the user name. The return lists a description of the user.

pause broker Allows you to pause the Luminis Message Broker.

purge destination -dest=<destination name>

-type=(topic|queue)

Allows you to purge all messages contained in a destination. The dest argument allows you to specify the destination from which you want to purge the messages. The type argu-ment allows you to specify the destination type, either topic or queue.

subscription -dest<destination name>


-client=<client id>

Allows you to purge messages con-tained in a durable subscription maintained for a given topical desti-nation. The dest argument is used to specify the name of the destination. The sub argument is used to specify the subscription name. The client argument is used to specify the sub-scription’s unique client ID.




resume broker Allows you to restart the Luminis Message Broker after it has been paused.

start broker Allows you to start up the Luminis Message Broker process. This com-mand does not start the system’s directory server. To completely start all Message Broker components, you should use the startcp shell command.

stop broker Allows you to shut down the Luminis Message Broker process. This com-mand does not stop the system’s directory server. To completely stop all Message Broker components, you should use the stopcp shell command.

update adminobj -rdn=<name>

[-property=<JMS prop-erty name>:<value>]

Allows you to update attributes of an administered object maintained by the system. The rdn value is the dis-tinguished name in LDAP by which the object is identified. It must take the form cn=name. The property argument allows you to pass updated values for one or more specific JMS properties, such as imqBrokerHostName.

broker [-property=<MQ prop-erty name>:<value>]

Allows you to pass values into the Message Queue config.properties file to control the behavior of the Luminis Message Broker. Typically, you would only need to adjust the message lim-its imposed on the broker. These include the maximum number of messages that can be contained in the system (imq.system.max_count), the maximum size of all combined messages (imq.system.max_size), and the maximum size of each indi-vidual message (imq.message.max_size). However, you can set others through the mbtool update broker command. For a list of properties that can be set and their associated MQ property names, refer to the Sun ONE Message Queue Administrator’s Guide.




update clientaccess -policy=(allow|deny)


-id=<user id>

-conn=(normal|admin)

-op=(add|delete)

Allows you to set connection policies implemented by the system for the users or groups contained in the its LDAP store that are associated with JMS clients. The policy argument allows you to set whether the policy allows or denies access. The entity argument allows you to specify whether the policy applies to a user or group. The id argument allows you to specify the LDAP username in the format cn=name. The conn argu-ment allows you to set the connection policy for normal or admin access. The op parameter allows you to add or delete the policy. For example, you could create a new normal connec-tion policy for a WebCT client with associated WebCTUser in the LDAP store by executing the following:

mbtool update clientaccess -pol-icy=allow -entity=user -id=WebCTUser -conn=normal -op=add

You could subsequently remove this connection policy by executing the same command, but changing the op value to delete.




update destaccess -policy=(allow|deny)


id=<user id>

-access=(con-sume|produce|browse)

-dest=<destination name>

-type=(topic|queue)

-op=(add|delete)

Allows you to set destination access policies implemented by the system for the users or groups contained in the LDAP store that are associated with JMS clients. The policy argu-ment allows you to set whether the policy will allow or deny a specific type of access. The entity argument allows you to specify whether the pol-icy applies to a user or group. The id argument allows you to specify the LDAP username in the format cn=name. The access argument allows you to specify whether the pol-icy applies to the client’s ability to consume, produce, or browse mes-sages for a given destination. The dest parameter allows you to stipu-late the destination for which you want to set policies. The type param-eter allows you to specify the type of destination, either topic or queue. The op parameter allows you to add or delete the policy. For example, you could create a new consumer access policy for a WebCT client with associ-ated WebCTUser in the LDAP for a topical destination called studentinfo by executing the following:

mbtool update destaccess -pol-icy=allow -entity=user -id=WebCTUser -access=consume -dest=studentinfo -type=topic -op=add

You could subsequently remove this destination access policy by execut-ing the same command but changing the op value to delete..




update httpclient -client=<client id>

[-http.username=<http username>]

[-http.password=<http-password>]

[-http.url=<http[s]://<host>[:<port>][/uri]]

[-enabled=(true|false)]

[-http.stopDeliveryOn-Error=(true|false)]

[-username=<jms username>]

[-credential=<jms user password>]

[-mes-sage.source.name=<destination name>]

[-mes-sage.source.type=<(topic|queue)]

[-message.selec-tor=(NONE|<message selector>]

[-durable=(true|false)]

Updates the attributes associated with the specified HTTP client in the system. The client argument sets the name of the client. The http.user-name and http.password arguments allow you to reset any authorization credentials you want a client to use to gain access to the destination URL, which is set by the http.url parameter. The enabled parameter allows you to reset whether the broker will post mes-sages for the client. The http.stopDeliveryOnError parame-ter allows you to reset whether the broker will stop delivery if it encoun-ters errors. The username and credential arguments allow you to reset the name and password for a user contained in the system’s LDAP store that is associated with the cli-ent so that the client can get an authorized connection to its destina-tion. The destination can be reset by message.source.name, which should be the value of an existing destina-tion created in the system The message.source.type argument allows you to specify the destination’s type, either topic or queue. The mes-sage.selector argument allows you to reset whether the broker will filter messages for the client, either set-ting no (NONE) or specifying JMS-compliant query strings to use. The durable argument allows you to reset whether messages are pre-served for the client even when inactive.

user -id=<user id>

[-desc=<user description]

[-credential=<pass-word>]

Allows you to reset attributes of a user contained in the system’s LDAP store that is associated with a JMS client. The id argument allows you to specify the user for which attributes will be reset. The desc argument allows to reset a description of the user. The credential argument allows you to reset the user’s password.



EXECUTING MBTOOL COMMANDS

To execute any of the mbtool commands listed in the table in the previous section, use the following procedure:




mbtool <action> <subject> <arguments>

For example, to list the destinations maintained by the system, you would type:

mbtool list destinations

From this command, you would see output similar to the following:

Destination Name: CPInternalDispatch

Destination Type: Topic

Destination Name: CPInternalHotBackup


Destination Name: CPMainDispatch


Destination Name: MBInternalAdminTopic


Destination Name: MBInternalLoggingTopic


Destination Name: MyNewDestination


To get status about the Message Broker, you could type the following

mbtool list brokerstatus

You would see output similar to the following:

The broker state is: running


Executing mbtool commands

Current Number of Messages in System: 0

Max Size of Messages in System: 200m

Max Number of Messages in System: 100000

Current Size of Messages in System (bytes): 0

Max Message Size: 100k

Timezone and country codes

APPENDIX A CONTENTS

This appendix provides a list of the timezone and country codes that need to be used for some properties in your installation configuration file.

• Timezone and country codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2

timezones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A.2

Country codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A.5

APPENDIX A

A.2 LMB Installation and Administration Guide Version E Feb 2, 2007

TIMEZONE AND COUNTRY CODES

When you install the LMB software, you are required to define the timezone and coun-try in which your school is located. To define these, you need to use specific formats, which are outlined in the following sections.

TIMEZONES

When setting up the lmb.conf file, you need to stipulate a timezone for the school.time-zone property. The following list outlines the timezones that are supported:

Africa/Amman

Africa/Cairo

Africa/Casablanca

Africa/Johannesburg

Africa/Lagos

Africa/Tripoli

Africa/Windhoek

America/Adak

America/Anchorage

America/Buenos_Aires

America/Caracas

America/Chicago

America/Costa_Rica

America/Cuiaba

America/Denver

Version E Feb 2, 2007 Timezone and country codes A.3

America/Godthab

America/Grand_Turk

America/Halifax

America/Havana

America/Indianapolis

America/Los_Angeles

America/Miquelon

America/New_York

America/Phoenix

America/Port-au-Prince

America/Santiago

America/Sao_Paulo

America/St_Johns

Asia/Alma-Ata

Asia/Anandyr

Asia/Aqtau

Asia/Aqtobe

Asia/Baku

Asia/Bangkok

Asia/Beirut

Asia/Bishkek

Asia/Calcutta

Asia/Dacca

Asia/Irkutsk

Asia/Jerusalem

Asia/Kabul

Asia/Kamchatka


Asia/Karachi

Asia/Katmandu

Asia/Krasnoyarsk

Asia/Magadan

Asia/Novosibirsk

Asia/Rangoon

Asia/Riyadh

Asia/Shanghai

Asia/Tokyo

Asia/Ulan_Bator

Asia/Vladivostok

Asia/Yakutsk

Asia/Yekaterinburg

Asia/Yerevan

Atlantic/Azores

Atlantic/Cape_Verde

Atlantic/South_Georgia

Atlantic/Stanley

Australia/Adelaide

Australia/Brisbane

Australia/Darwin

Australia/Hobart

Australia/Lord_Howe

Australia/Sydney

Europe/Bucharest

Europe/Istanbul

Europe/London


Europe/Minsk

Europe/Moscow

Europe/Paris

Europe/Riga

Europe/Samara

Europe/Simferopol

Europe/Warsaw

Pacific/Apia

Pacific/Auckland

Pacific/Chatham

Pacific/Easter

Pacific/Fiji

Pacific/Gambier

Pacific/Guadalcanal

Pacific/Honolulu

Pacific/Kiritimati

Pacific/Marquesas

Pacific/Norfolk

Pacific/Noumea

Pacific/Pitcairn

Pacific/Rarotonga

Pacific/Tongatapu

COUNTRY CODES

When setting up the lmb.conf file, you need to stipulate a code for the school.counrty property. The following list outlines the country codes that are supported:


af = Afghanistan

al = Albania

dz = Algeria

as = American Samoa

ad = Andorra

ao = Angola

ai = Anguilla

aq = Antarctica

ag = Antigua and Barbuda

ar = Argentina

am = Armenia

aw = Aruba

au = Australia

at = Austria

az = Azerbaijan

bs = Bahamas

bh = Bahrain

bd = Bangladesh

bb = Barbados

by = Belarus

be = Belgium

bz = Belize

bj = Benin

bm = Bermuda

bt = Bhutan

bo = Bolivia

ba = Bosnia and Herzegovina

bw = Botswana

bv = Bouvet Island

br = Brazil


io = British Indian Ocean Territory

bn = Brunei Darussalam

bg = Bulgaria

bf = Burkina Faso

bi = Burundi

kh = Cambodia

cm = Cameroon

ca = Canada

cv = Cape Verde

ky = Cayman Islands

cf = Central African Republic

td = Chad

cl = Chile

cn = China

cx = Christmas Island

cc = Cocos (Keeling) Islands

co = Colombia

km = Comoros

cg = Congo

cd = Congo, The Democratic Republic of the

ck = Cook Islands

cr = Costa Rica

hr = Croatia

cu = Cuba

cy = Cyprus

cz = Czech Republic

ci = Côte D'ivoire

dk = Denmark

dj = Djibouti

dm = Dominica


do = Dominican Republic

ec = Ecuador

eg = Egypt

sv = El Salvador

gq = Equatorial Guinea

er = Eritrea

ee = Estonia

et = Ethiopia

fk = Falkland Islands (Malvinas)

fo = Faroe Islands

fj = Fiji

fi = Finland

fr = France

gf = French Guiana

pf = French Polynesia

tf = French Southern Territories

ga = Gabon

gm = Gambia

ge = Georgia

de = Germany

gh = Ghana

gi = Gibraltar

gr = Greece

gl = Greenland

gd = Grenada

gp = Guadeloupe

gu = Guam

gt = Guatemala

gn = Guinea

gw = Guinea-bissau


gy = Guyana

ht = Haiti

hm = Heard Island and Mcdonald Islands

va = Holy See (Vatican City State)

hn = Honduras

hk = Hong Kong

hu = Hungary

is = Iceland

in = India

id = Indonesia

ir = Iran, Islamic Republic of

iq = Iraq

ie = Ireland

il = Israel

it = Italy

jm = Jamaica

jp = Japan

jo = Jordan

kz = Kazakhstan

ke = Kenya

ki = Kiribati

kp = Korea, Democratic People's Republic of

kr = Korea, Republic of

kw = Kuwait

kg = Kyrgyzstan

la = Lao People's Democratic Republic

lv = Latvia

lb = Lebanon

ls = Lesotho

lr = Liberia


ly = Libyan Arab Jamahiriya

li = Liechtenstein

lt = Lithuania

lu = Luxembourg

mo = Macao

mk = Macedonia, The Former Yugoslav Republic of

mg = Madagascar

mw = Malawi

my = Malaysia

mv = Maldives

ml = Mali

mt = Malta

mh = Marshall Islands

mq = Martinique

mr = Mauritania

mu = Mauritius

yt = Mayotte

mx = Mexico

fm = Micronesia, Federated States of

md = Moldova, Republic of

mc = Monaco

mn = Mongolia

ms = Montserrat

ma = Morocco

mz = Mozambique

mm = Myanmar

na = Namibia

nr = Nauru

np = Nepal

nl = Netherlands


an = Netherlands Antilles

nc = New Caledonia

nz = New Zealand

ni = Nicaragua

ne = Niger

ng = Nigeria

nu = Niue

nf = Norfolk Island

mp = Northern Mariana Islands

no = Norway

om = Oman

pk = Pakistan

pw = Palau

ps = Palestinian Territory, Occupied

pa = Panama

pg = Papua New Guinea

py = Paraguay

pe = Peru

ph = Philippines

pn = Pitcairn

pl = Poland

pt = Portugal

pr = Puerto Rico

qa = Qatar

ro = Romania

ru = Russian Federation

rw = Rwanda

re = Réunion

sh = Saint Helena

kn = Saint Kitts and Nevis


lc = Saint Lucia

pm = Saint Pierre and Miquelon

vc = Saint Vincent and the Grenadines

ws = Samoa

sm = San Marino

st = Sao Tome and Principe

sa = Saudi Arabia

sn = Senegal

cs = Serbia and Montenegro

sc = Seychelles

sl = Sierra Leone

sg = Singapore

sk = Slovakia

si = Slovenia

sb = Solomon Islands

so = Somalia

za = South Africa

gs = South Georgia and the South Sandwich Islands

es = Spain

lk = Sri Lanka

sd = Sudan

sr = Suriname

sj = Svalbard and Jan Mayen

sz = Swaziland

se = Sweden

ch = Switzerland

sy = Syrian Arab Republic

tw = Taiwan, Province of China

tj = Tajikistan

tz = Tanzania, United Republic of


th = Thailand

tl = Timor-leste

tg = Togo

tk = Tokelau

to = Tonga

tt = Trinidad and Tobago

tn = Tunisia

tr = Turkey

tm = Turkmenistan

tc = Turks and Caicos Islands

tv = Tuvalu

ug = Uganda

ua = Ukraine

ae = United Arab Emirates

gb = United Kingdom

us = United States

um = United States Minor Outlying Islands

uy = Uruguay

uz = Uzbekistan

vu = Vanuatu

ve = Venezuela

vn = Viet Nam

vg = Virgin Islands, British

vi = Virgin Islands, U.S.

wf = Wallis and Futuna

eh = Western Sahara

ye = Yemen

zm = Zambia

zw = Zimbabwe

ax = Åland Islands

Version E Feb 2, 2007 Glossary G.1

As you set up and manage the Luminis Message Broker (LMB) through the mbtool interface or through the Message Broker Administration Tool, you will encounter a num-ber of terms with which you should be familiar. This glossary provides a list of these terms with definitions relative to the Java Messaging Service (JMS) specification and its implementation through LMB.

Note: For comprehensive information about the JMS specification or using an imple-mentation of its API to set up peer to peer messaging, refer to the following documents published by Sun Microsystems, Inc.:

Java Messaging Service API TutorialJava Messaging Service API version 1.1

Many of the definitions included in this glossary were derived in total or in part from information included in these publications.

ACCESS POLICY

Used to impose access restrictions on the clients that can connect to the Luminis Mes-sage Broker or produce and consume messages. The access policies are configured at the user or group level, based upon entries created in the system's LDAP store.

ADMINISTERED OBJECTS

Are preconfigured objects used by clients of the Java Messaging Service (JMS) pro-vider (in this case Luminis Message Broker). There are two general types of administered objects: destination and connection factory.

BROKER

Another name for a Java Messaging Service (JMS) provider, which is a service that implements the JMS specification.

BROWSE

The act of viewing the messages in a given queue or topic without removing (consum-ing) them.

GLOSSARY

G.2 LMB Installation and Administration Guide Version E Feb 2, 2007

CONNECTION FACTORY

The administered object that a client uses to create a connection with a provider. The connection factory encapsulates a set of predefined connection parameters. There are two general types of connection factories that you will work with in the Luminis Message Broker: queue and topic.

CONSUMER

A JMS client who receives messages sent to a destination. The term consume is used generically within the JMS model to mean the receipt of a message by a client. For exam-ple, a WebCT system might be the consumer of messages produced by the Banner system.

DESTINATION

The target of the messages a client produces and the source of the messages it consumes.

DURABLE SUBSCRIPTION

Typically in a publish/subscribe messaging model a client that subscribes to a topic can consume messages published after its subscription and the subscriber must be active in order to consume messages. Durable subscriptions allow subscribers to receive messages even when inactive (offline, down, etc.). When the subscriber for a durable subscription is not active, the provider retains the subscription's messages until they are received by the subscription or until they are set to expire.

HTTP CLIENT

Typically the clients that consume messages in the Java Service Messaging model are themselves Java applications. To enable wider use models, SunGard Higher Education has configured the Luminis Message Broker to support clients interacting with the desti-nations via the Hypertext Transfer Protocol (HTTP).

MQ

The Luminis Message Broker is implemented through integration with the Sun Message Queue software. The Message Queue software provides the framework and engine for the Java Messaging Service.

Version E Feb 2, 2007 Glossary G.3

JMS

Java Message Service (JMS) is a programming interface (API) for connecting Java pro-grams to messaging middleware, thereby providing a method for disparate software systems or applications to communicate. Using the JMS API, applications can create, send, receive, and read messages that are delivered asynchronously, meaning that they are delivered without clients overtly requesting them. This is typically done through message listeners registered by each client. The JMS API supports two primary message delivery models: point to point, in which clients send messages to queues that have single sub-scribers that must acknowledge receipt of the message; and publish/subscribe, in which clients publish messages to topics that can have many subscribing clients.

JMS MESSAGE SELECTOR

Allows a consumer to filter messages by message header using a query string to specify those in which it is interested. Message selectors assign the work of filtering messages to the Java Messaging Service provider rather than to the application.

PRODUCER

A client that sends messages to a destination. The term produce is used generically in the JMS model to mean sending a message for subsequent delivery.

PROVIDER

A messaging system that implements the Java Messaging Service (JMS) API and pro-vides administrative capabilities. The Luminis Message Broker and its administrative interfaces (mbtool and the Message Broker Administration Tool) are considered a pro-vider in the JMS model.

PUBLISH

The act of pushing a message into a topic for delivery to subscribing applications.

PURGE

Cleaning the queues or topics (destinations) of the messages that they contain. When messages are purged, they are no longer available for clients to receive them and will have to be resent.

G.4 LMB Installation and Administration Guide Version E Feb 2, 2007

QUEUE

The intermediary destination of messages consumed in a point to point model. Each message is addressed to a specific queue by the sending client, from which specific receiving clients extract their messages. Queues are always durable, meaning that they retain all messages sent to them until the messages are consumed or until the messages expire.

SECURE SOCKET LAYER (SSL)

A security protocol that uses encryption to transmit data between a browser and a server. This form of security is supported in messages that are consumed by HTTP clients.

SUBSCRIPTION

The act of connecting to a topic for the purpose of receiving messages published by other clients.

TOPIC

In a publish/subscribe model, clients send their messages to a topic. A topic can have multiple subscribers who receive the message. The messages are retained by the topic only as long as it takes to distribute them to current subscribers. If there are clients set up as durable subscribers, the messages will be held until consumed.

TRANSPORT GATEWAY

Typically the Java Messaging Service (JMS) protocol is used for communication between clients and providers. However, the Luminis Message Broker also supports HTTP communication. The Transport Gateway is used to expose the broker to HTTP communication.

sungard higher education luminis message broker … · what can we help you achieve? sungard higher...

Documents