ibmwebsphereapplication server v8.5.next beta · starting and stopping a server by using developer...

IBM WebSphere Application ServerVersion 8 Release 5

IBM WebSphere Application ServerV8.5.Next Beta

��

NoteBefore using this information and the product it supports, read the information in “Notices” on page 575.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

© Copyright IBM Corporation 2011, 2013.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Chapter 1. IBM WebSphere ApplicationServer Developer Tools for Eclipse,Version 9.0 Beta overview . . . . . . . 2

Chapter 2. The Liberty profile . . . . . 5Liberty profile: Architecture . . . . . . . . . 5

Programming model support . . . . . . . . 8Liberty profile externals support . . . . . . 11

Liberty profile: Server configuration . . . . . . 12Liberty profile: Feature management . . . . . . 13

Liberty features . . . . . . . . . . . . 14Liberty profile: Shared libraries . . . . . . . . 21Liberty profile: Product extension . . . . . . . 22Liberty profile: Security . . . . . . . . . . 25

Liberty profile: Quick overview of security . . . 29Liberty profile: Authentication . . . . . . . 29Liberty profile: Authorization . . . . . . . 40Liberty profile: Security public APIs . . . . . 43Configuration differences between the full profileand Liberty profile: security . . . . . . . . 46Liberty profile: The limits to protection throughpassword encryption . . . . . . . . . . 47

Liberty profile: Messaging . . . . . . . . . 48Liberty profile: High Performance ExtensibleLogging (HPEL) . . . . . . . . . . . . . 51

LogViewer command-line tool . . . . . . . 55MongoDB databases . . . . . . . . . . . 58

Chapter 3. End-to-end paths for theLiberty profile. . . . . . . . . . . . 59Enabling JMS messaging for the Liberty profile . . 59

Enabling JMS messaging for a single Libertyprofile server . . . . . . . . . . . . . 59Enabling JMS messaging between two Libertyprofile servers . . . . . . . . . . . . 62

Chapter 4. Migrating applications to theLiberty profile. . . . . . . . . . . . 67Migrating data access applications to the Libertyprofile . . . . . . . . . . . . . . . . 67

Configuration differences between the full profileand Liberty profile: dataSource and jdbcDriverelements . . . . . . . . . . . . . . 67Configuration differences between the full profileand Liberty profile: connectionManager element . 68Migrating a DB2 data source to the Libertyprofile . . . . . . . . . . . . . . . 69Migrating a Derby embedded data source to theLiberty profile . . . . . . . . . . . . 71

Chapter 5. Installing the Liberty profile 73Installing the Liberty profile developer tools and(optionally) the Liberty profile . . . . . . . . 73

Installing the developer tools from a remoterepository . . . . . . . . . . . . . . 74Installing the developer tools from downloadedinstallation files . . . . . . . . . . . . 76Configuring the developer tools installation . . 77Installing Maven Integration for Eclipse . . . . 79System requirements for WebSphere ApplicationServer Developer Tools for Eclipse. . . . . . 80

Installing the Liberty profile by extracting anarchive file . . . . . . . . . . . . . . 83Applying a fix pack to a Liberty profile archiveinstallation . . . . . . . . . . . . . . 84

Removing a fix pack from a Liberty profilearchive installation . . . . . . . . . . . 86

Applying an interim fix to a Liberty profile archiveinstallation . . . . . . . . . . . . . . 86

Removing an interim fix from a Liberty profilearchive install . . . . . . . . . . . . 87

Chapter 6. Setting up the Liberty profile 89Liberty profile: Directory locations and properties 89Verifying the integrity of Liberty profile installation 91

Liberty profile: productInfo command . . . . 92Creating a Liberty profile server by using developertools . . . . . . . . . . . . . . . . . 93Creating a Liberty profile server manually . . . . 95Specifying Liberty profile bootstrap properties. . . 95

Chapter 7. Administering the Libertyprofile . . . . . . . . . . . . . . . 97Liberty profile: Configuration elements in theserver.xml file . . . . . . . . . . . . . 97

activationSpec . . . . . . . . . . . . 101activedLdapFilterProperties. . . . . . . . 101administrator-role . . . . . . . . . . . 102application . . . . . . . . . . . . . 103application-bnd. . . . . . . . . . . . 104applicationMonitor . . . . . . . . . . 106authCache . . . . . . . . . . . . . 107authData . . . . . . . . . . . . . . 108authenticated . . . . . . . . . . . . 109authentication . . . . . . . . . . . . 110automaticLibraries . . . . . . . . . . . 110baseEntry. . . . . . . . . . . . . . 110basicRegistry . . . . . . . . . . . . 111binaryLog . . . . . . . . . . . . . 112binaryTrace . . . . . . . . . . . . . 114bundleRepository . . . . . . . . . . . 116channelfw . . . . . . . . . . . . . 116classloader . . . . . . . . . . . . . 117client . . . . . . . . . . . . . . . 119clientManager . . . . . . . . . . . . 120config . . . . . . . . . . . . . . . 121connectionManager . . . . . . . . . . 123contextService . . . . . . . . . . . . 125

© Copyright IBM Corp. 2011, 2013 iii

customLdapFilterProperties. . . . . . . . 126databaseStore . . . . . . . . . . . . 127dataSource . . . . . . . . . . . . . 128disk . . . . . . . . . . . . . . . 132domino50LdapFilterProperties . . . . . . . 134edirectoryLdapFilterProperties. . . . . . . 135ejbContainer. . . . . . . . . . . . . 135executor . . . . . . . . . . . . . . 136featureManager. . . . . . . . . . . . 138federatedRepository . . . . . . . . . . 139fileset . . . . . . . . . . . . . . . 141fileTransfer . . . . . . . . . . . . . 142group . . . . . . . . . . . . . . . 143groupDisplayNameMapping . . . . . . . 143groupSecurityNameMapping . . . . . . . 144hostAuthInfo . . . . . . . . . . . . 145httpClassification . . . . . . . . . . . 147httpDispatcher . . . . . . . . . . . . 148httpEncoding . . . . . . . . . . . . 149httpEndpoint . . . . . . . . . . . . 158httpOptions . . . . . . . . . . . . . 160httpSession . . . . . . . . . . . . . 162httpSessionDatabase . . . . . . . . . . 167idsLdapFilterProperties . . . . . . . . . 172include . . . . . . . . . . . . . . 173iplanetLdapFilterProperties . . . . . . . . 174jaasLoginContextEntry . . . . . . . . . 175jaasLoginModule . . . . . . . . . . . 176jdbcDriver . . . . . . . . . . . . . 178jmsCommsEndpoint . . . . . . . . . . 178jmsCommsOutbound . . . . . . . . . . 180jmsConnectionFactory . . . . . . . . . 181jmsQueue . . . . . . . . . . . . . 181jmsQueueConnectionFactory . . . . . . . 181jmsTopic . . . . . . . . . . . . . . 181jmsTopicConnectionFactory. . . . . . . . 181jndiEntry . . . . . . . . . . . . . . 181jpa . . . . . . . . . . . . . . . . 182jspEngine. . . . . . . . . . . . . . 183keyStore . . . . . . . . . . . . . . 185ldapRegistry. . . . . . . . . . . . . 186library. . . . . . . . . . . . . . . 192localStore. . . . . . . . . . . . . . 194logging . . . . . . . . . . . . . . 195ltpa. . . . . . . . . . . . . . . . 197managedExecutorService . . . . . . . . 198managedServer . . . . . . . . . . . . 199managementRepository . . . . . . . . . 199managementRepositoryConnection . . . . . 200member . . . . . . . . . . . . . . 201messagingEngine . . . . . . . . . . . 202messagingSecurity . . . . . . . . . . . 207mimeTypes . . . . . . . . . . . . . 208mongo . . . . . . . . . . . . . . 208mongoDB . . . . . . . . . . . . . 212monitor . . . . . . . . . . . . . . 213nativeTransactionManager . . . . . . . . 213netscapeLdapFilterProperties . . . . . . . 214oauthProvider . . . . . . . . . . . . 215oauthRoles . . . . . . . . . . . . . 220permission . . . . . . . . . . . . . 221

pluginConfiguration . . . . . . . . . . 221properties . . . . . . . . . . . . . 223properties.datadirect.sqlserver . . . . . . . 223properties.db2.i.native . . . . . . . . . 231properties.db2.i.toolbox . . . . . . . . . 238properties.db2.jcc . . . . . . . . . . . 250properties.derby.client . . . . . . . . . 262properties.derby.embedded . . . . . . . . 265properties.informix . . . . . . . . . . 267properties.informix.jcc . . . . . . . . . 275properties.jms.ActivationSpec . . . . . . . 282properties.jms.ConnectionFactory . . . . . . 284properties.jms.Queue . . . . . . . . . . 286properties.jms.QueueConnectionFactory . . . 288properties.jms.Topic . . . . . . . . . . 290properties.jms.TopicConnectionFactory . . . . 292properties.microsoft.sqlserver . . . . . . . 294properties.oracle . . . . . . . . . . . 298properties.sybase . . . . . . . . . . . 300quickStartSecurity . . . . . . . . . . . 302realm . . . . . . . . . . . . . . . 302remoteAccess . . . . . . . . . . . . 305role. . . . . . . . . . . . . . . . 306safAuthorization . . . . . . . . . . . 307safCredentials . . . . . . . . . . . . 308safRegistry . . . . . . . . . . . . . 308safRoleMapper . . . . . . . . . . . . 309securewayLdapFilterProperties . . . . . . 309serverCommand . . . . . . . . . . . 310ssl . . . . . . . . . . . . . . . . 311sslDefault. . . . . . . . . . . . . . 311sslOptions . . . . . . . . . . . . . 312supportedEntityType . . . . . . . . . . 312syncToOSThread . . . . . . . . . . . 313tcpOptions . . . . . . . . . . . . . 313textLog . . . . . . . . . . . . . . 314transaction . . . . . . . . . . . . . 316trustAssociation . . . . . . . . . . . 319uniqueGroupIdMapping. . . . . . . . . 321uniqueUserIdMapping . . . . . . . . . 322user . . . . . . . . . . . . . . . 323userDisplayNameMapping . . . . . . . . 323userSecurityNameMapping . . . . . . . . 323variable . . . . . . . . . . . . . . 324virtualHost . . . . . . . . . . . . . 324webAppSecurity . . . . . . . . . . . 325webContainer . . . . . . . . . . . . 329wimRegistry. . . . . . . . . . . . . 336wlmClassification . . . . . . . . . . . 337wsSecurityClient . . . . . . . . . . . 337wsSecurityProvider . . . . . . . . . . 340

Administering the Liberty profile by usingdeveloper tools . . . . . . . . . . . . . 344

Editing the Liberty profile configuration byusing developer tools. . . . . . . . . . 344Starting and stopping a server by usingdeveloper tools . . . . . . . . . . . . 345Defining a utility project as a shared library . . 345Exploring the runtime environment by usingdeveloper tools . . . . . . . . . . . . 348

iv IBM WebSphere Application Server: V8.5.Next Beta

Displaying the server configuration in a mergedview . . . . . . . . . . . . . . . 348Viewing the schema documentation for theserver configuration . . . . . . . . . . 349Generating a Liberty profile server dump usingdeveloper tools . . . . . . . . . . . . 349Packaging a Liberty profile server by usingdeveloper tools . . . . . . . . . . . . 350Adding a data source by using developer tools 350

Administering the Liberty profile manually . . . 351Customizing the Liberty profile environment 352Administering the Liberty profile from thecommand prompt . . . . . . . . . . . 353Adding and removing Liberty features . . . . 368Using include elements, variables, and Ref tagsin configuration files . . . . . . . . . . 370Controlling dynamic updates . . . . . . . 374Configuring class loaders and libraries for JavaEE applications . . . . . . . . . . . . 376Configuring a web server plug-in for the Libertyprofile . . . . . . . . . . . . . . . 381Configuring session persistence for the Libertyprofile . . . . . . . . . . . . . . . 384Connecting to the Liberty profile by using JMX 386Establishing a JMX MBean Liberty serverconnection . . . . . . . . . . . . . 398Configuring HPEL in the Liberty Profile . . . 399Setting up the server-management environmentfor the Liberty profile . . . . . . . . . 401Administering data access applications on theLiberty profile . . . . . . . . . . . . 407Administering web applications on the Libertyprofile . . . . . . . . . . . . . . . 418

Chapter 8. Extending the Libertyprofile . . . . . . . . . . . . . . 419Developing a Liberty feature for the Liberty profile 419

Developing a Liberty feature manually . . . . 419Creating a Liberty feature by using developertools . . . . . . . . . . . . . . . 425Developing an OSGi bundle with simpleactivation. . . . . . . . . . . . . . 429Composing advanced features by using OSGiDeclarative Services . . . . . . . . . . 434Liberty profile: Resource location symbols . . . 441Monitoring local files for changes . . . . . 442Configuring tracing and logging for features inthe Liberty profile . . . . . . . . . . . 443

Chapter 9. Securing the Liberty profileand its applications. . . . . . . . . 445Getting started with security in the Liberty profile 445

Liberty profile: Quick overview of security . . 447Setting up BasicRegistry and role mapping onthe Liberty profile . . . . . . . . . . . 448

Securing communications with the Liberty profile 449Enabling SSL communication for the Libertyprofile . . . . . . . . . . . . . . . 449Creating SSL certificates for your Liberty profileusing the Utilities menu . . . . . . . . . 455

Creating SSL certificates from the commandprompt . . . . . . . . . . . . . . 455Configuring your web application and serverfor client certificate authentication . . . . . 457

Authenticating users in the Liberty profile. . . . 459Configuring a user registry for the Libertyprofile . . . . . . . . . . . . . . . 459Configuring the authentication cache on theLiberty profile . . . . . . . . . . . . 464Configuring a JAAS custom login module forthe Liberty profile . . . . . . . . . . . 465Configuring LTPA on the Liberty profile . . . 467Customizing SSO configuration using LTPAcookies for the Liberty profile . . . . . . . 468Configuring RunAs authentication in theLiberty profile . . . . . . . . . . . . 469Configuring TAI for the Liberty profile . . . . 470

Authorizing access to resources in the Libertyprofile . . . . . . . . . . . . . . . . 472

Configuring authorization for applications onthe Liberty profile . . . . . . . . . . . 472OAuth. . . . . . . . . . . . . . . 474

Configuring secure JMX connection to the Libertyprofile . . . . . . . . . . . . . . . . 492Configuring web security related properties for theLiberty profile . . . . . . . . . . . . . 493

Customizing SSO configuration using LTPAcookies for the Liberty profile . . . . . . . 494Configuring your web application and serverfor client certificate authentication . . . . . 494

Configuring authentication aliases for the Libertyprofile . . . . . . . . . . . . . . . . 495Setting up a Liberty profile to run in SP800-131 496Developing extensions to the Liberty profilesecurity infrastructure . . . . . . . . . . 497

Developing a custom TAI for the Liberty profile 498Developing JAAS custom login modules for asystem login configuration . . . . . . . . 499Customizing an application login to perform anidentity assertion using JAAS . . . . . . . 503Developing a custom user registry for theLiberty profile . . . . . . . . . . . . 504

Securing web services . . . . . . . . . . 505Securing web services at the message level . . 505Web services security HTTPS transport policyassertions. . . . . . . . . . . . . . 516

Chapter 10. Deploying applications tothe Liberty profile . . . . . . . . . 517Adding and running an application on the Libertyprofile by using developer tools . . . . . . . 519

Publishing your application by using developertools . . . . . . . . . . . . . . . 520

Packaging a Liberty profile server from thecommand prompt . . . . . . . . . . . . 522Using JNDI binding for constants from the serverconfiguration files . . . . . . . . . . . . 523Deploying OSGi applications to the Liberty profile 524

Sharing common OSGi bundles for the Libertyprofile . . . . . . . . . . . . . . . 524

Contents v

Deploying data access applications to the Libertyprofile . . . . . . . . . . . . . . . . 525

Deploying an existing JDBC application to theLiberty profile . . . . . . . . . . . . 525Enabling JDBC Tracing for the Liberty profile 526

Deploying a web application to the Liberty profile 529Deploying a JPA application to the Liberty profile 530Deploying web services applications to the Libertyprofile . . . . . . . . . . . . . . . . 531

Deploying JAX-RS applications to the Libertyprofile . . . . . . . . . . . . . . . 531

Deploying a messaging application to the Libertyprofile . . . . . . . . . . . . . . . . 534

Chapter 11. Monitoring the Libertyprofile . . . . . . . . . . . . . . 537Liberty profile: JVM monitoring . . . . . . . 537Liberty profile: Web application monitoring . . . 538Liberty profile: ThreadPool monitoring . . . . . 539Liberty profile: JAX-WS monitoring . . . . . . 540Liberty profile: Sessions monitoring . . . . . . 541

Chapter 12. Tuning the Liberty profile 543

Chapter 13. Liberty profile:Troubleshooting tips . . . . . . . . 547Liberty profile: Trace and logging . . . . . . 552Liberty profile: Timed operations and JDBC calls 554Liberty profile: High Performance ExtensibleLogging (HPEL) . . . . . . . . . . . . 556

LogViewer command-line tool. . . . . . . 560Configuring HPEL in the Liberty Profile . . . 563

Liberty profile: Runtime environment knownrestrictions . . . . . . . . . . . . . . 566Liberty profile: Developer Tools known restrictions 570Liberty profile: Messages . . . . . . . . . 571

Notices . . . . . . . . . . . . . . 575Trademarks . . . . . . . . . . . . . . 577

Sending your comments to IBM . . . 579

vi IBM WebSphere Application Server: V8.5.Next Beta

Chapter 1. IBM WebSphere Application Server DeveloperTools for Eclipse, Version 9.0 Beta overview

Distributed operating systems

IBM® WebSphere® Application Server Developer Tools for Eclipse is a lightweightset of tools for developing, assembling, and deploying Java™ EE, OSGi, Web 2.0,and mobile applications to WebSphere Application Server.

When combined with WebSphere Application Server Version8.5.Next Beta Liberty Profile, the WebSphere Application Server Developer Toolsfor Eclipse V9.0 Beta provides a fast and lightweight environment for the rapiddevelopment and testing of Java EE web profile, Web 2.0, mobile, and OSGiapplications.

For more information about IBM WebSphere Application Server Developer Toolsfor Eclipse, see:

v “What's new in Version 9.0 Beta”v “Supported programming models” on page 2

v “Supported server tasks” on page 3v “Advanced support” on page 3v “Getting started” on page 3v “Getting help” on page 3

What's new in Version 9.0 Beta

Tools are available in this release to support:v Developing JAX-WS applications for the WebSphere Application Server Version

8.5 Next Beta Liberty Profile.v Integrating OSGi bundles with Maven.v Improved validation of JCDI managed beans.v Simplified installation by dragging and dropping WebSphere Application Server

Version 8.5 Next Beta Liberty Profile.v Improved support for developing User Features for extending the Liberty profile

server functions.

© Copyright IBM Corp. 2011, 2013 1

Supported programming models

The following table lists the programming models that are available in IBM WebSphereApplication Server Developer Tools for Eclipse and indicates the application servers thatthey are supported on.

Programmingmodel

WebSphereApplicationServer V8.5Next BetaLibertyProfile

WebSphereApplicationServer V8.5LibertyProfile

WebSphereApplicationServer V8.5



Develop JavaEEapplications

Yes Yes Yes Yes Yes

Develop EJBapplications

YesNote: Thetools fordevelopingEJBapplicationssupport EJB3.0 and 3.1.

No Yes Yes Yes

Develop CDIapplications

Yes No Yes Yes No

DevelopJAX-RSapplications

Yes Yes Yes Yes Yes

DevelopJAX-WSapplications

Yes No Yes Yes Yes

Develop Web2.0 andMobile webapplications

Yes Yes Yes Yes Yes

DevelopOSGiapplications

YesNote: Thetools fordevelopingOSGiapplicationssupport thefollowingtechnologies:

v Web 2.5

v Web 3.0

v JPA

v JAX-RS

v JSF

v EJB Lite


v Web 2.5

v Web 3.0

v JPA

v JAX-RS

v JSF


v Web 2.5

v Web 3.0

v JPA

v JAX-RS

v JSF

v EJB


v Web 2.5

v Web 3.0

v JPA

v JAX-RS

v JSF

No

2 IBM WebSphere Application Server: V8.5.Next Beta

Supported server tasks

The following features are supported on all WebSphere Application Servers, exceptthe Liberty profile:v Migrate the server when importing applications targeted to an invalid server.v Start and stop a remote server.v Run and debug administrative script files on the server.

Note: The workbench does not support WebSphere Application Server V7.0 featurepacks and managed (federated) WebSphere Application Server NetworkDeployment environments.

Advanced support

The following features are supported on the WebSphere Application Server fullprofile, but not on the Liberty profile:v Migrate the server when importing applications targeted to an invalid server.v Start and stop a remote server.v Run and debug administrative script files on the server.

Note: The workbench does not support WebSphere Application Server V7.0 featurepacks and managed (federated) WebSphere Application Server NetworkDeployment environments.

Getting started

To get started, see “Installing the Liberty profile developer tools and (optionally)the Liberty profile” on page 73.

Visit the WASdev community site:v To participate in or post questions in the forum.v To learn more about the workbench from the collection of articles and sample

code.v To get community news through blog entries.v To help improve the workbench by reporting defects and requesting feature

enhancements.

Getting help

WebSphere Application Server Developer Tools for Eclipse provides you withaccess to the Rational® Application Developer documentation.

Note: Some documented features are available only with the full RationalApplication Developer for WebSphere Software product.For details about how to integrate the workbench with the server, see Testing andpublishing on a server.

Additional features available with Rational Application Developerfor WebSphere Software

For enterprise-level development, consider using Rational Application Developeras your integrated development environment. Rational Application Developer

Chapter 1. IBM WebSphere Application Server Developer Tools for Eclipse, Version 9.0 Beta overview 3

http://www.ibm.com/wasdev

http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.servertools.doc/topics/cservertool_usergoalcontainer.html

http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.servertools.doc/topics/cservertool_usergoalcontainer.html

provides a complete environment for Java, Java EE, web, web services, SOA, OSGi,Web 2.0, mobile, and portal designers and developers, including the serverdevelopment tools. It also provides integration and support for the followingapplication servers and associated feature packs:v WebSphere Application Server V8.5 Liberty Profilev WebSphere Application Server V8.5v WebSphere Application Server V8.0v WebSphere Application Server V7.0

Rational Application Developer is designed to accelerate development and unit testto ensure delivery of higher quality applications. It offers tools for teams that areusing the emerging trends of Web 2.0, SOA, OSGi, and Cloud computing that helpaccelerate adoption and software delivery.

For more information about this product, see Rational Application Developer forWebSphere Software or Rational Application Developer overview.


http://www-01.ibm.com/software/awdtools/developer/application/

http://www-01.ibm.com/software/awdtools/developer/application/

http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.rad.install.doc/topics/rad_overview.html

Chapter 2. The Liberty profile

The Liberty profile is a highly composable, fast to start, dynamic application serverruntime environment.

You can install the server as described in Chapter 5, “Installing the Liberty profile,”on page 73. Because the Liberty profile does not include a Java runtimeenvironment (JRE), you must install a JRE provided by either IBM or Oraclebeforehand. For more information about supported Java environments, and whereto get them, see “Minimum supported Java levels” on page 566.

This server supports two models of application deployment:v Deploy an application by dropping it into the dropins directory.v Deploy an application by adding it to the server configuration file.

The Liberty profile supports a subset of the following parts of the full WebSphereApplication Server programming model:v Web applicationsv OSGi applications

v Enterprise JavaBeans (EJB) applications1

Associated services such as transactions and security are only supported whenrequired by these application types and by JPA.

Features are the units of functionality by which you control the pieces of theruntime environment that are loaded into a particular server. For a list of the mainLiberty features, see “Liberty features” on page 14.

You can also create your own features, as described in Chapter 8,“Extending the Liberty profile,” on page 419.

Distributed operating systems You can work with the runtime environment directly, oruse the WebSphere Application Server Developer Tools for Eclipse.

On distributed platforms, the Liberty profile provides both a development and anoperational environment. On the Mac, it provides a development environment.

Liberty profile: ArchitectureThe Liberty profile is a highly composable and dynamic runtime environment.OSGi services are used to manage component lifecycles, and the injection ofdependencies and configuration. The server process comprises a single JVM, theLiberty kernel, and any number of optional features. The feature code and most ofthe kernel code runs as OSGi bundles within an OSGi framework. Featuresprovide the programming models and services that are required by applications.

1. The Liberty profile is limited to EJB Lite 3.1.


The kernel launcher bootstraps the system and starts the OSGi framework. Theconfiguration is parsed, and then the configured features are loaded by the featuremanager. The kernel extensively uses OSGi services to provide a highly dynamicruntime environment. The OSGi Configuration Admin service manages systemconfiguration, and an OSGi Declarative Services component manages the lifecycleof system services. The file monitor service detects application and configurationfile changes, and the logging service writes messages and debug information to thelocal file system.

OSGiframework(runtime)

Java 6+

Kernel

monitor-1.0

jsp-2.2jsf-2.0

appSecurity-1.0

servlet-3.0

Features

Container

Applications

Figure 1. Liberty profile architecture

server.xml

webapp.war trace.log

Service

Feature Manager

OSGi ConfigurationAdmin

File Monitor

OSGi DeclarativeServices

Logging service

Feature bundle

Figure 2. Liberty profile kernel


Features are specified in the system configuration files that are the server.xml fileand any other included files. The server configuration files populate the OSGiConfiguration Admin service, which injects the feature configuration into thefeature manager service. The feature manager maps each feature name to a list ofbundles that provide the feature. The bundles are installed into the OSGiframework and started. The feature manager responds to configuration changes bydynamically adding and removing features while the server is running.

Runtime services provide configuration default settings so that the configurationyou need to specify is kept to a minimum. You specify the features you need,along with any additions or overrides to the system default settings, in aserver.xml file. You might choose to structure your configuration into a number ofseparate files that are linked to the parent server.xml file by using an “include”syntax. At server startup, or when the user configuration files are changed, thekernel configuration management parses your configuration and applies it over thesystem default settings. The set of configuration properties that belongs to eachservice is injected into the service each time the configuration is updated.

useful-api-3.2.jaruseful-core-3_.useful-extras-3.2_.

**

/lib/features/useful-3.2.mf

<featureManager><feature>useful-3.2</feature>

</featureManager>

server.xml

installs and startsbundles in OSGi

framework

reads bundlelist

readsconfig

injects config

Feature Manager


Feature bundle

Figure 3. Feature management

Chapter 2. The Liberty profile 7

The OSGi Declarative Services component is used so that function can bedecomposed into discrete services, which are activated only when needed. Thisbehavior helps the runtime environment to be “late and lazy”, keeping thefootprint small and the startup fast. Declared services are added to the OSGiservice registry, and dependencies between services can be resolved withoutloading implementation classes. Service activation can be delayed until a service isused: when the service reference is resolved. Configuration for each service isinjected as the service is activated, and is reinjected if the configuration is latermodified.

Programming model supportThis set of tables shows the extent to which each of the major server profilessupports the full WebSphere Application Server programming model.

Java EE 6 technologies

Table 1. Java EE 6 support by profile.

A list of Java EE technologies, subdivided into sections for web services, web applications, enterprise applications,management and security, and Java EE-related specifications in Java SE. For each technology there is aspecification reference, and an indication of whether the technology is supported by the full profile, and by the Libertyprofile.

Technology Specification reference Full profile Liberty profile

Java Platform, EnterpriseEdition 6 (Java EE 6)

JSR 316 �

Java Platform, EnterpriseEdition 6 Web Profile

JSR 316 ��

Web services technologies

Java API for RESTful WebServices (JAX-RS) 1.1

JSR 311 � �

Implementing Enterprise WebServices 1.3

JSR 109 ��

<include location="more.xml"/><include location="evenmore.xml"/>

extra.xml

more.xml

evenmore.xml

<include location="extra.xml"/>

server.xml

Config defaultsConfig metadata

injects mergedconfig into bundles

reads defaultconfig from bundles

merges userconfig over

defaults

optionalincludes

Kernel bundle


Config defaultsConfig metadata

Feature bundle

Figure 4. Configuration management


Table 1. Java EE 6 support by profile (continued).



Java API for XML-Based WebServices (JAX-WS) 2.2

JSR 224 ��

Java Architecture for XMLBinding (JAXB) 2.2

JSR 222 ��

Web Services Metadata for theJava Platform

JSR 181 ��

Java API for XML-based RPC(JAX-RPC) 1.1

JSR 101 �

Java APIs for XML Messaging1.3

JSR 67 �

Java API for XML Registries(JAXR) 1.0

JSR 93 �

SOAP with Attachments APIfor Java (SAAJ) 1.3

JSR 67 ��

Web application technologies

Java Servlet 3.0 JSR 315 � �

JavaServer Faces 2.0 JSR 314 � �

JavaServer Pages2.2/Expression Language 2.2

JSR 245 � �

Standard Tag Library forJavaServer Pages (JSTL) 1.2

JSR 52 � �

Debugging Support for OtherLanguages 1.0

JSR 45 � �

Enterprise applicationtechnologies

Contexts and DependencyInjection for Java (Web Beans1.0)

JSR 299 ��

Dependency Injection for Java1.0

JSR 330 ��

Bean Validation 1.0 JSR 303 � �

Enterprise JavaBeans 3.1(includes Interceptors 1.1)

JSR 318 ��(The Liberty

profile supports only the EJBLite subset and MessageDriven Beans.)

Java EE Connector Architecture1.6

JSR 322 �

Java Persistence 2.0 JSR 317 � �

Common Annotations for theJava Platform 1.1

JSR 250 � �(The Liberty profile does notsupport @ManagedBean.)

Java Message Service API 1.1 JSR 914 ��

Java Transaction API (JTA) 1.1 JSR 907 � �

JavaMail 1.4 JSR 919 �


Table 1. Java EE 6 support by profile (continued).



Management and securitytechnologies

Java Authentication ServiceProvider Interface forContainers

JSR 196 �

Java Authorization Contract forContainers 1.3

JSR 115 �

Java EE ApplicationDeployment 1.2

JSR 88 �

J2EE Management 1.1 JSR 77 �

Java EE-related specificationsin Java SE

Java API for XML Processing(JAXP) 1.3

JSR 206 � �

Java Database Connectivity 4.0 JSR 221 � �

Java Management Extensions(JMX) 2.0

JSR 255 � �

JavaBeans ActivationFramework (JAF) 1.1

JSR 925 � �

Streaming API for XML (StAX)1.0

JSR 173 � �

Enterprise OSGi technologies

Table 2. Enterprise OSGi support by profile.

A list of enterprise OSGi technologies, subdivided into sections for blueprint, web, and other enterprise technologies.For each technology there is a specification reference, and an indication of whether the technology is supported bythe full profile, and by the Liberty profile.

Technology Specification reference full profile Liberty profile

Blueprint-related technologies

Blueprint Container R4.2 Enterprise Chapter 121 � �

Blueprint Transactions � �

Blueprint Managed JPA � �

Blueprint Security �

Blueprint Resource References �

Web-related technologies

Web Application Bundles R4.2 Enterprise Chapter 128 � �

JNDI R4.2 Enterprise Chapter 126 � �

JSP � �

JSTL � �

JSF � �


Table 2. Enterprise OSGi support by profile (continued).

A list of enterprise OSGi technologies, subdivided into sections for blueprint, web, and other enterprise technologies.For each technology there is a specification reference, and an indication of whether the technology is supported bythe full profile, and by the Liberty profile.

Technology Specification reference full profile Liberty profile

JAX-RS � �

Other enterprise technologies

EJB Bundles �(EJB levels earlier than 3.0 arenot supported.)

Remote Services R4.2 Compendium Chapter 13 �

SCA Configuration TypeSpecification

R4.2 Enterprise Chapter 129 �

Remote Bundle Repositories �

SIP �(SIP annotations are notsupported.)

Liberty profile externals supportExternal functions and resources of the Liberty profile can be used directly, andcan be relied on to be in the next release. Internal or incidental aspects of theprofile might change when you apply service, or upgrade to a future release.

What can I use directly in the profile and rely on being in thenext release?

The following resources can be used directly and will continue to be available inthe next release:v The documented application programming interfaces (APIs).

– Write your code in accordance with the Liberty API documentation.2

– Compile your code against the JAR files in the wlp/dev directories.– At run time, the application class loader has visibility to the API that is

documented for the features in your server configuration. See the Libertyfeature API documentation.2

v The server configuration, including features.v Commands and scripts in the wlp/bin and wlp/bin/tools directories.v Client utilities in the wlp/clients directory.

What should I avoid dependencies on?

Do not build dependencies on incidental aspects of the product, or you might beimpacted when you apply service or upgrade to future releases. Examples ofproduct internals that you should avoid relying on include, but are not restrictedto, the following scenarios:v The names of product binary jars, for example those in the wlp/dev directory.

Compile your code against these JAR files by using the tools or the javac-extdirs option. See “Overriding classes from the Java SDK” on page 567.

2. The Java API documentation for each Liberty profile API is available in a separate JAR file under the /dev/ibm-api/javadocdirectory of the server image.


v Direct use of the product binaries in the /lib directory. The only JAR files thatcan be directly invoked are in the wlp/bin/tools directory.

v Message texts that are output by the server at run time.v The layout of the product installation, other than the /wlp/bin and /wlp/dev

directories.v Examples and template files in the wlp/templates directory. These files might be

modified when you apply services to your installation.v Private or third party Java packages that are not explicitly exposed as APIs.

These are not visible to the application class loader at run time.

What might be modified by applying service or an upgrade?

The contents of the following directories and their subdirectories might bemodified when service or upgrade is applied. Do not make your ownmodifications to files in these locations, or they might be overwritten by productmaintenance or upgrade:v wlp/bin

v wlp/clients

v wlp/dev

v wlp/lib

v wlp/templates

No modifications are made to the contents of the following directories. These areyour files, and applying service or upgrade will not modify them:v wlp/etc (where you might have added a server.env or jvm.options file).v wlp/usr (the default location for user configuration and applications).v Any non-default directory that you designate through the WLP_USER_DIR

environment variable.

Third-party APIs might change over time without consideration to backwardcompatibility. These are Java packages that are considered part of theimplementation of features developed in open source communities and deliveredas part of the Liberty profile. Third-party APIs are not visible to applications bydefault; Java EE applications with a classloader configuration that explicitly allowsthird-party access will have visibility to those packages on the application classloader, and OSGi applications must explicitly import the packages. Consider theimpact of incompatible changes before deciding to use third-party APIs.

Liberty profile: Server configurationThe Liberty profile is configured by exception. The runtime environment operatesfrom a set of built-in configuration default settings, and you only need to specifyconfiguration that overrides those default settings. You do this by editing either theserver.xml file or another XML file that is included in server.xml at run time.

The configuration has the following characteristics:v Described in XML files.v Human-readable, and editable in a text editor.v Small, easy to back up, and easy to copy to another system.v Shareable across an application development team.v Composable, so that features can easily add their own configuration to the

system.


v Extensibly-typed, so you don't have to modify the current configuration to workwith later versions of the runtime environment.

v Dynamically responsive to updates.v Forgiving, so that missing values are assumed and unrecognized properties are

ignored.

Features are the units of functionality by which you control the pieces of theruntime environment that are loaded into a particular server. They are the primarymechanism that makes the server composable. The list of features that you specifyin the server configuration provides a functional server. See “Liberty features” onpage 14.

When you first install and start the server, a feature manager and a default serverconfiguration are available:v By default, a server contains the jsp-2.2 feature, to support servlet and JSP

applications. You can use the feature manager to add the features that you need.v Server configuration is by exception. When you specify the features that you

need, the default configuration of those features provides a rich environmentthat is designed to cover most common requirements, therefore you only need tospecify changes from the default configuration.

For a full list of the elements that you can configure to complement or modify theconfiguration provided by Liberty features, see “Liberty profile: Configurationelements in the server.xml file” on page 97.

You can also use a bootstrap.properties file to specify properties that are neededbefore the main configuration is processed, and to define variables that are used inthe main configuration.

Service author perspective: Runtime management ofconfiguration

The Liberty profile configuration service parses the primary server.xml file andany files it includes, merges the contents over the default configuration valuesprovided by the installed bundles, then feeds the resulting property sets into theOSGi Configuration Admin Service (CA). CA injects each set of properties into theservice that owns the set, if it is registered with CA.

The ordering of these steps is flexible. Services can register with CA before or afterthe initial property sets are established. Properties can be updated in CA after theinitial injection, at which time the updated properties are injected into the owningservice. It is therefore important that the services can receive, and respondappropriately to, updates to their configuration at any time that the service isactive. Specifically, if a service delays its activation until its configuration isavailable, it must still be able to activate.

To enable a service to receive configuration data, there are a number of stepsinvolved. See “Enabling a service to receive configuration data” on page 436.

Liberty profile: Feature managementFeatures are the units of functionality by which you control the pieces of theruntime environment that are loaded into a particular server.


Use the configuration file server.xml to declare which features you want to load.The set of features is enclosed within the <featureManager> element, and eachfeature within the <feature> subelement. For example:<server>

<featureManager><feature>servlet-3.0</feature><feature>localConnector-1.0</feature>

</featureManager></server>

You can specify any feature in the server configuration file. Some features includeother features within them. The same feature can be included in one or more otherfeatures. At run time, the feature manager computes the combined list of contentthat is required to support the requested set of features.

For information about the main available features, see “Liberty features.” Forinformation about the restrictions that apply to each feature, see “Liberty profile:Runtime environment known restrictions” on page 566.

Dynamic changes to feature configuration

When you change the feature configuration, the feature manager recalculates thelist of required bundles, stops and uninstalls those bundles that are no longerrequired, and installs and starts any additions. All features are therefore designedto cope with other features that are being dynamically added or removed.

Superseded feature

The superseded label on a feature indicates that a new feature or a combination offeatures might provide an advantage over using the superseded feature. Forexample, new, finer-grained features might be used in place of the superseded onein order to reduce the server footprint by excluding content that might not benecessary. The new feature or features might not completely replace the function ofthe superseded feature, so you must consider your scenario before decidingwhether to change your configuration. Superseded features remain completelysupported and valid for use in your configuration; the superseded label justprovides an indication that you might be able to improve your configuration.

Liberty featuresFeatures are the units of functionality by which you control the pieces of theruntime environment that are loaded into a particular server.

The following list contains information about the main available features. Includinga feature in the configuration might cause one or more additional features to beloaded automatically. For example, if you include the wab-1.0 feature, theservlet-3.0 and blueprint-1.0 features are loaded automatically. Each featureincludes a brief description, and an example of how the feature is declared withinthe <featureManager> element inside the server.xml file. For example:<server>



For a full list of available features, see the .mf files under the lib/featuresdirectory of the server root installation location. The feature information is given in


the Subsystem-Content element in the .mf file. Each .mf file represents a feature inthe Liberty profile. The file name matches the feature name. For example, theservlet-3.0 feature is defined in a file called servlet-3.0.mf.

Bean validation<feature>beanvalidation-1.0</feature>

The beanvalidation-1.0 feature provides validations for JavaBeans at eachlayer of an application.

The validation can be applied to all layers of JavaBeans in an applicationby using annotations or a Validation.xml deployment descriptor.

See also “beanvalidation-1.0 feature restrictions” on page 568.

Blueprint<feature>blueprint-1.0</feature>

The blueprint-1.0 feature enables support for deploying OSGiapplications that use the OSGi blueprint container specification.

With the OSGi Applications support in WebSphere Application Server, youcan develop and deploy modular applications that use Java EE and OSGitechnologies.

CDI<feature>cdi-1.0</feature>

The cdi-1.0 feature enables support for the Contexts and DependencyInjection 1.0 specification on the Liberty profile.

The supported entry point into CDI is through an expression languagelookup of an @Named CDI style bean, with other CDI beans injected intoit. See also “cdi-1.0 feature restrictions” on page 568.

Collective controller<feature>collectiveController-1.0</feature>

The collectiveController-1.0 feature enables controller functionality for amanagement collective and includes a management repository MBean thatis accessible using the JMX/REST connector that is provided by therestConnector-1.0 feature. The collective controller acts as a storage andcollaboration mechanism to which collective members can connect. ThecollectiveController-1.0 feature includes a ServerCommandMbean thatcan be used to remote start or stop servers that are managed by thecollective controller.

See “Setting up the server-management environment for the Libertyprofile” on page 401.

Collective member<feature>collectiveMember-1.0</feature>

The collectiveMember-1.0 feature enables a server to be a member of amanagement collective, allowing it to be managed by the collectivecontroller.

See “Setting up the server-management environment for the Libertyprofile” on page 401.

Enterprise JavaBeans (EJB) Lite subset<feature>ejblite-3.1</feature>


The ejblite-3.1 feature provides support for EJB applications written to theEJB Lite subset of the EJB 3.1 specification.

The following functions are supported:v An EJB module packaged in an EAR file.v EJBs packaged in a WAR file.v The @Stateful, @Stateless, @Singleton, and @EJB annotations.v The javax.annotation.security annotations.v Injection of JPA EntityManager, EntityManagerFactory, and JDBC

DataSource into all types of session bean types.v ejb-jar.xml.v EJB interceptors.v No-Interface View.v Bean managed transactions (UserTransaction).

See also “ejblite-3.1 feature restrictions” on page 569.

Java API for RESTful Web Services (JAX-RS)<feature>jaxrs-1.1</feature>

The jaxrs-1.1 feature provides support for the Java API for RESTful WebServices on the Liberty profile.

See also “jaxrs-1.1 feature restriction” on page 569.

Java API for XML-Based Web Services (JAX-WS)<feature>jaxws-2.2</feature>

The jaxws-2.2 feature provides support for the Java API for XML-BasedWeb Services on the Liberty profile.

v For web applications that use the jaxws-2.2 serverfeature, you must enable the servlet-3.0 and jsp-2.2 features in theserver.xml file.

v For EJB applications that use the jaxws-2.2 server feature,you must enable the ejblite-3.1 and servlet-3.0 features in theserver.xml file.

v For JAX-WS client applications, you can use bothunmanaged thin clients and managed application clients.

See also “jaxws-2.2 feature restrictions” on page 569.

Java Architecture for XML Binding (JAXB)<feature>jaxb-2.2</feature>

The jaxb-2.2 feature provides support for the Java Architecture for XMLBinding (JAXB) on the Liberty profile.

See also JAXB.

See also “jaxb-2.2 feature restriction” on page 569.

Java Database Connectivity (JDBC)<feature>jdbc-4.0</feature>


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxwsthinclient

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=cwbs_jaxb

The jdbc-4.0 feature provides support for applications that access adatabase. You can take an existing application that uses Java DatabaseConnectivity (JDBC) and a data source, and deploy the application to aserver.

See also “Deploying an existing JDBC application to the Liberty profile” onpage 525.

Java Naming and Directory Interface (JNDI)<feature>jndi-1.0</feature>

The jndi-1.0 feature provides support for a single JNDI entry definition inthe server configuration of the Liberty profile.

Java Persistence API (JPA)<feature>jpa-2.0</feature>

The jpa-2.0 feature provides support for applications that useapplication-managed and container-managed JPA written to the JPA 2.0specification.

The support is built on top of Apache OpenJPA with extensions to supportthe container-managed programming model.

Extended Persistence Context is now available for use withStateful Session beans.

See also “Deploying a JPA application to the Liberty profile” on page 530and “jpa-2.0 feature restrictions” on page 570.

Java Server Faces (JSF)<feature>jsf-2.0</feature>

The jsf-2.0 feature provides support for web applications that use the JSFframework. This framework simplifies the construction of user interfaces.

If you include the jsf-2.0 feature, you also include the jsp-2.2 feature,because the JSF framework is an extension of the JSP framework.

See also “jsf-2.0 feature restrictions” on page 570.

Java Server Pages (JSP)<feature>jsp-2.2</feature>

The jsp-2.2 feature provides support for JSPs that are written to the JSP2.2 specification.

If you include the jsp-2.2 feature, you also include the servlet-3.0feature.

See also “jsp-2.2 feature restrictions” on page 570.

JavaScript Object Notation (JSON4J) Library<feature>json-1.0</feature>

The json-1.0 feature provides access to the JSON4J library that provides aset of JSON handling classes for Java environments. The JSON4J libraryprovides a simple Java model for constructing and manipulating data to berendered as JSON data.

See also Using JSON content in JAX-RS application requests and responsesand JSON4J Libraries API.

Local JMX Connector<feature>localConnector-1.0</feature>


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_jsoncontent

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=json4jjd

The localConnector-1.0 feature provides a local JMX connector that isbuilt into the JVM. The JMX connector can be used only on the same hostmachine by someone running under the same user ID and the same JDK. Itenables local access by JMX clients such as jConsole, or other JMX clientsthat use the Attach API.

See “Connecting to the Liberty profile by using JMX” on page 386.

Messaging<feature>jmsServer-1.0</feature>

The wasJMSServer-1.0 feature enables the JMS messaging engine run timeto be initialized. The messaging run time is responsible for providing theapplication connectivity, managing the state of destinations such as topicsor queues, and handling Quality of Service, security, and transactions.

<feature>jmsMessaging-1.1</feature>

The wasJMSClient-1.1 feature enables support for JMS resourceconfiguration required by the messaging applications to connect to the JMSServer on the Liberty profile

<feature>jmsComms-1.0</feature>

The jmsComms-1.0 feature provides support for inbound connections fromthe remote messaging application. The remote messaging applications canconnect to the JMS messaging engine through TCP/IP. The applicationscan also connect securely using SSL. To connect using SSL, you mustenable the SSL feature.

See “Enabling JMS messaging for the Liberty profile” on page 59.

Messaging security<feature>jmsSecurity-1.0</feature>

The wasJMSSecurity-1.0 feature supports secure connections to themessaging engine. When the wasJMSSecurity-1.0 feature is enabled, itstarts authenticating and authorizing the users who are trying to connect tothe messaging engine. The user is authenticated against the registry that isdefined in the server.xml file. When the user wants to access a destinationsuch as a topic or a queue for a particular role, the user must have theaccess to that destination. The access to the destination is defined in the<messagingSecurity> element in the server.xml file. If thewasJMSSecurity-1.0 feature is added and the <messagingSecurity> elementis missing in the server.xml file, then the users can neither connect to themessaging engine nor perform any messaging action (for example, sendingor receiving messages from the destinations).

Notes:

v Configuring the user registry is a prerequisite for the jmsSecurity-1.0feature. Ensure that a user registry is configured before thejmsSecurity-1.0 feature is enabled.

v When you enable the jmsSecurity-1.0 feature, you must also configurethe <messagingSecurity> element in the server.xml file. This enablesauthorized users to access messaging destinations.

See “Enabling secure JMS messaging for the Liberty profile” on page 60.

MongoDB<feature>mongo-2.0</feature>


The mongo-2.0 feature provides support for MongoDB instances andassociated database connections. Access to MongoDB connections isavailable either by JNDI lookup or resource injection. The nativecom.mongodb API performs the database manipulation.

See “Creating Liberty applications that use MongoDB” on page 415.

Monitoring<feature>monitor-1.0</feature>

The monitor-1.0 feature provides Performance Monitoring Infrastructure(PMI) support on the Liberty profile.

See Chapter 11, “Monitoring the Liberty profile,” on page 537.

OSGi JPA<feature>osgi.jpa-1.0</feature>

The osgi.jpa-1.0 feature provides JPA support for OSGi applications onthe Liberty profile.

REST connector<feature>restConnector-1.0</feature>

The restConnector-1.0 feature provides a secure JMX connector that canbe used locally or remotely using any JDK. It enables remote access byJMX clients through a REST-based connector and requires SSL and basicuser security configuration.

See “Connecting to the Liberty profile by using JMX” on page 386.

Secure Sockets Layer (SSL)<feature>ssl-1.0</feature>

The ssl-1.0 feature provides support for Secure Sockets Layer (SSL)connections. To use the secure HTTPS listener, you must enable thisfeature.

The Liberty profile provides a dummy keystore and a dummy truststore,which are the same as those provided by previous versions of WebSphereApplication Server.

The secure HTTPS listener is not started unless the ssl-1.0 feature isenabled. If the feature is unavailable, the HTTPS listener is stopped.

To specify the SSL certificates, add a pointer in the server.xml file; see“Securing communications with the Liberty profile” on page 65.

To change the HTTPS port, set the <httpsPort> attribute of the<httpEndpoint> element in the server.xml file; see “Specifying Libertyprofile bootstrap properties” on page 95.

Security<feature>appSecurity-2.0</feature>

This version of the appSecurity feature secures onlyapplications that are based explicitly on the presence of other features. Ifthe servlet-3.0 feature is present with the appSecurity-2.0 feature, webapplications are secured. If the servlet-3.0 feature is not present, thenweb applications are not secured. If the ejblite-3.1 feature is present withthe appSecurity-2.0 feature, EJB applications are secured. If theejblite-3.1 feature is not present, EJB applications are not secured.

Note:


v The appSecurity-1.0 feature is superseded by appSecurity-2.0. You canchoose to use the appSecurity-2.0 version instead in your serverconfiguration. See “Superseded feature” on page 14.

The appSecurity-1.0 feature provides support for securing the serverruntime environment and applications. The following aspects aresupported:v Basic user registryv Lightweight Directory Access Protocol (LDAP) user registryv Basic authorizationv Web application security

– Basic authentication login– Form-login Form-logout– Programmatic APIs: getRemoteUser; getUserPrincipal; isUserInRole;

authenticate; logout; login

v EJB application security– All security annotations and all security elements that can be

specified in the ejb-jar.xml file.– Programmatic APIs: getCallerPrincipal, isCallerInRole, and

getCallerIdentity3.

When you add the appSecurity-1.0 or appSecurity-2.0 feature to yourserver, you must also configure a user registry, such as the basic userregistry or the LDAP user registry.

See also Chapter 9, “Securing the Liberty profile and itsapplications,” on page 445 and “ appSecurity-2.0 feature restrictions” onpage 568.

Server status<feature>serverStatus-1.0</feature>

The serverStatus-1.0 feature enables Liberty profile servers toautomatically publish their status to WebSphere Application Serverdeployment managers and job managers that are aware of the server as aresource in their Job configuration. The known states are Started andStopped.

See Submitting jobs to manage Liberty profile servers and InstallingLiberty profile server resources using the job manager.

Servlet<feature>servlet-3.0</feature>

The servlet-3.0 feature provides support for HTTP Servlets written to theJava Servlet 3.0 specification.

See also Chapter 9, “Securing the Liberty profile and its applications,” onpage 445.

Session Persistence<feature>sessionDatabase-1.0</feature>

The sessionDatabase-1.0 feature provides session affinity and failoversupport on the Liberty profile.

3. The getCallerIdentity API is not supported for Singleton session beans.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tagt_jobmgr_comp_server

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tagt_jobmgr_install_comp_server

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tagt_jobmgr_install_comp_server

See “Configuring session persistence for the Liberty profile” on page 384.

Web application bundle (WAB)<feature>wab-1.0</feature>

The wab-1.0 feature provides support for WABs that are inside enterprisebundles.This feature supports the following resources packaged inside a WAB:v Static web content and JSPs.v HTTP servlets written to the Servlet 3.0 specification.v Blueprint applications.

If you include the wab-1.0 feature, you also include the servlet-3.0 andblueprint-1.0 features.

Web services security<feature>wssecurity-1.0</feature>

The wssecurity-1.0 feature provides support for securing web services atthe message level. To secure web services messages, you must enable thisfeature. Web services security policies defined in a WSDL file are ignoredand are not enforced unless the wssecurity-1.0 feature is enabled.

Liberty profile: Shared libraries

Shared libraries are files used by multiple applications. You can use sharedlibraries, global libraries, and automatic shared libraries to reduce the number ofduplicate library files on your system.

Library elements

Liberty profile libraries have three elements; <folder>, <file>, and <fileset>. Forexample:<library><folder dir="..." /><file name="..." /><fileset dir="..." includes="*.jar" scanInterval="5s" /><//library>

A specified file must be a container for the resource (for example a JAR file) ratherthan the resource itself.

If an element in the list is a file, the contents of that JAR or compressed .zip file aresearched. If a folder is specified then resources are loaded from that directory.

Global libraries

Global libraries can be used by any application. JAR files are placed in a globallibrary directory, and then are specified in the class loader configuration for eachapplication.

You can place global libraries in two locations:v ${shared.config.dir}/lib/global

v ${server.config.dir}/lib/global


If there are files present in these locations at the time an application is started, andthat application does not have a <classloader> element configured, the applicationuses these libraries. If a class loader configuration is present, these libraries are notused unless the global library is explicitly referenced.

For more information, see “Providing global libraries for all Java EE applications”on page 378.

Automatic shared libraries

Automatic shared libraries are created automatically, and given an ID that is thesame as the directory name. When creating automatic shared libraries, only areference to the directory name of the library is required.

Resource files and JAR files are picked up and made available from the automaticshared library.

You can place automatic shared libraries in two locations:v ${shared.config.dir}/lib

v ${server.config.dir}/lib

Automatic shared libraries are dynamically created and removed, unless theautomatic monitoring of the automatic libraries location is disabled:<automaticLibraries monitorEnabled="false"/>

For more information, see “Creating an automatic shared library” on page 378.

Liberty profile: Product extension

You can expand the capability of the Liberty profile by writing product extensions.

You can write your own Liberty features and install them onto an existing Libertyprofile server, or you can package them for delivery to your users.

The Liberty profile provides various System Programming Interfaces (SPIs) thatyou can use to extend the runtime environment; you can also use more advancedfeatures such as operating the Liberty profile server from your Java applicationsprogrammatically.

Product extension

A product extension is a directory on disk that is structured like the Liberty profileinstallation directory, wlp. It is defined to the Liberty installation through a file inthe wlp/etc/extensions directory called extension-name.properties. The contentsof the product extension directory are then used to extend the Liberty profile.Multiple product extensions can be installed together but they must have uniquenames; this is enforced through the naming of the properties files. The defaultproduct extension location, wlp/usr/extension, does not require a properties file;content under this location is automatically detected and is known to the runtimeas the “usr” product extension.


Product extensions usually contain one or more Liberty features but can have anycontent that extends the Liberty profile environment, for example scripts orresources.

Feature

A Liberty feature consists of a definition file (feature manifest), and a collection ofOSGi bundles that provide classes and services corresponding to a particularcapability in the Liberty profile runtime environment.

Scenarios for using a Liberty feature instead of a regularapplication

Implementing a function as a Liberty feature instead of as an application might beappropriate in a number of scenarios. The following list describes some of thebenefits of using a feature:v Features are controlled through feature manager configuration, so they are

separate from user application management.v Feature code has access to the liberty profile SPI, which allows deeper

integration with the runtime environment.v Features can receive user-specified configuration from the server.xml file, and

expose their configuration settings in the development tools without the toolshaving to be changed.

v Features can easily expose classes and services to each other and to userapplications.

v Features can be extremely lightweight with no application containerdependencies.

v Features can be used to augment a particular programming model. For example,a User Feature can add support for custom Blueprint namespace handlers orBlueprint annotations to the OSGi Application programming model.

Note: Features cannot generally be directly portable to other application servers; ifportability is important you should use specification-compliant applications.

Developing a simple feature

See “Developing a Liberty feature manually” on page 419, “Creating a Libertyfeature by using developer tools” on page 425, and “Liberty feature manifest files”on page 421.

Using a feature in the server

To use a user-written feature in the Liberty profile server, you must install it into aproduct extension directory. This might be the predefined “user product extension”location or an extension that is located outside the Liberty profile installationdirectory. Then you can add the feature name into the server configuration.

The user product extension is a predefined directory where the server looks foradditional features. The feature definition .mf file must be copied into the${wlp.user.dir}/extension/lib/features directory and the bundle .jar files mustbe copied into the ${wlp.user.dir}/extension/lib directory.

User-written features are added to the server configuration in the same way asproduct features. To avoid name clashes with features from different providers,


features that are part of a product extension must be prefixed with the extensionname. For features in the usr/extension/lib directory, the default prefix is usr:.

For example, if you have installed a feature called simple-1.0 into the${wlp.user.dir}/extension/lib directory, you must configure that feature into theserver.xml as follows:<featureManager>

<feature>usr:simple-1.0</feature></featureManager>

If you have installed a feature called myFeature into your own location, anddefined a product extension in the wlp/etc/extensions/myExt.properties file, youmust configure that feature into the server.xml file as follows:<featureManager>

<feature>myExt:myFeature</feature></featureManager>

When you start the server, the feature is detected by the feature manager and thebundles are installed into the OSGi framework and started.

See also “Adding and removing Liberty features” on page 368 and “Liberty profile:Feature management” on page 13.

Programmatically using a feature from applications

Features can expose classes and services to applications.

To expose Java classes for application use, you must list the class packages in theIBM-API-Package header in the feature manifest. Listing the class packages in theIBM-API-Package header makes the classes visible to the application class loaders.Visibility of API packages can be controlled through the API visibility type. See“Specifying API and SPI packages for a Liberty feature project” on page 427.

To allow services to be used by OSGi applications, you must list them in theIBM-API-Service header in the feature manifest. A feature provides OSGi servicesso that you can refer to those services programmatically from your applications.

Services should generally be registered into the OSGi Service Registry (SR) to allowapplications (or other features) to locate them. OSGi applications and other featurescan perform a direct lookup from the SR, or can use capabilities such as Blueprintor OSGi Declarative Services to inject their service dependencies. Java EEapplications are more likely to locate services through JNDI; in the Liberty profilethere is a federation of the SR and JNDI that allows Java EE applications to useJNDI to locate services in the SR. For more information, see “Working with theOSGi service registry” on page 431.

Exposing a feature as a web application

To expose a Liberty feature as a web application, you can publish the OSGibundles in the feature as web application bundles (WABs). In addition to the OSGiheaders that a bundle requires, you can specify the web application context pathby using the Web-ContextPath header.

For example:Web-ContextPath: myWABappWebapp-Context: myWABappBundle-ClassPath: WEB-INF/classes


Configuration injection and processing

A major benefit of using features is that they can be easily configured by the userin the server.xml file (and included files). The configuration files are monitoredand parsed by the Liberty profile kernel and the resulting sets of properties can beinjected into the relevant component each time they change.

Liberty profile configuration is managed by the OSGi Configuration Admin (CA)service in the kernel and can be accessed according to that specification. Sets ofconfiguration properties are identified by a persisted identity (PID) that is used toassociate the element in the server.xml file with the component that registers toreceive the properties.

For example, if you register your feature with the CA service using a PID ofcom.acme.console, a user can specify the following configuration in the server.xmlfile:<com.acme.console color="blue" size="17"/>

And your feature will receive the properties:v color="blue"

v size="17"

You can optionally provide metadata that describes your configuration propertiesby using OSGi Metatype descriptors. The use of descriptors causes yourconfiguration metadata to be included in the configuration schema that isgenerated by the liberty profile and is used by the Developer Tools, so yourconfiguration properties are automatically presented to application developers asthey configure their server.

For more details on receiving and describing configurationproperties, see “Enabling a service to receive configuration data” on page 436.

Declarative Services in the Liberty profile

Larger or more complex features often benefit from the use of OSGi DeclarativeServices (DS) to enable the feature to be composed of multiple services, and tomanage the injection of dependencies and configuration properties. The use of DSallows lazy activation of services, deferring the loading of Java classes until theservice is used, and ordering the activation of services based on dependencies.Most of the features in the Liberty profile product are managed by DS.

See also “Composing advanced features by using OSGi DeclarativeServices” on page 434.

Liberty profile: SecurityLiberty profile security provides protection for web resources as per the Servlet 3.0specification, and protection for the JMX connections when you are using the RESTconnector.

The following diagram shows a typical security process involved when accessing aprotected web resource. To make the security process work, you must configurethe appropriate security features and the configurations that are required for the


authentication and authorization.

1. An HTTP client requests a web resource in the WebContainer.2. The WebContainer delegates the security check to the WebSecurity Collaborator.3. The WebSecurity Collaborator prompts the user to enter credentials if absent,

and uses the Authentication service to authenticate the user.4. The Authentication service authenticates, creates, and returns the subject if

authenticated successfully. Otherwise, the Authentication service reports anexception for the authentication failure.

5. The WebSecurity Collaborator uses the Authorization service to perform a userauthorization check.

6. The Authorization service returns the authorization result to the WebSecurityCollaborator.

7. The WebSecurity Collaborator returns the result of the security check aboutwhether the user is authorized.

8. The WebContainer serves or rejects the requested resource.

The following sections provides a summary of the primary security components inthe Liberty profile:v “Quick start” on page 27v “Authentication” on page 27v “Authorization” on page 27v “Secure Socket Layer (SSL)” on page 27v “Single Sign-On (SSO)” on page 27v “Web security-related properties” on page 27v “Security public APIs” on page 28v “Management security” on page 28v

2

1

7

8

36

45

WebContainer

WebSecurityCollaborator

Authenticationservice

Authorizationservice

Browser/HTTP client

Figure 5. Typical security flow for web resources


v “Authentication aliases” on page 28v “Configuration examples and samples” on page 28v “Security compatibility and differences” on page 28v “Troubleshooting” on page 28

vDistributed operating systems “Tools” on page 28

Quick start

With the quickStartSecurity element, you can configure a single user securityenvironment in the Liberty profile. See “Liberty profile: Quick overview ofsecurity” on page 29 for details of how the security workflow is when you use thequickStartSecurity element, and “Getting started with security in the Libertyprofile” on page 445 for a sample task.

Authentication

Authentication confirms the identity of a user. The most common form ofauthentication is user name and password, such as through either basicauthentication or form login for web applications. When a user is authenticated,the source of a request is represented as a Subject object at the run time. Thisprocess involves performing access control checks when a user accesses a resource,based on the authorization rules configured for the resource. See “Liberty profile:Authentication” on page 29 for more concepts and “Authenticating users in theLiberty profile” on page 459 for detailed tasks.

Authorization

Authorization determines whether to grant a user access to resources within thesystem. The Java EE model uses subjects, resources, and roles to determine whatcan and cannot be allowed. This process involves checking the user credentialssuch as the user ID and password, certificates, and tokens, and creating a subjectbased on the authenticated user. See “Liberty profile: Authorization” on page 40for more concepts and “Authorizing access to resources in the Liberty profile” onpage 472 for detailed tasks.

Secure Socket Layer (SSL)

SSL provides transport level security. See “Enabling SSL communication for theLiberty profile” on page 449 for detailed tasks.

Single Sign-On (SSO)

SSO enables access to applications without the user being prompted to loginmultiple times. See Concept of SSO for more details and “Customizing SSOconfiguration using LTPA cookies for the Liberty profile” on page 468 for thedetailed task.

Web security-related properties

There are many configuration properties that you can configure as part of websecurity, such as SSO and client certificate authentication, for your applications. See“Liberty profile: Configuration elements in the server.xml file” on page 97 foravailable attributes and see “Configuring web security related properties for theLiberty profile” on page 493 for some examples.


Security public APIs

The Liberty profile contains public APIs that you can use to implement securityfunctions. The security public APIs in the Liberty profile are a subset of the fullprofile security public APIs. The main classes are WSSecurityHelper, WSSubject,and RegistryHelper. These classes contain a subset of the methods that areavailable in the full profile versions. There is also a new class WebSecurityHelper.See “Liberty profile: Security public APIs” on page 43.

The Java API documentation for each Liberty profile API is available in a separateJAR file under the /dev/ibm-api/javadoc directory of the server image.

See “Developing extensions to the Liberty profile security infrastructure” on page497 for some examples.

Management security

Management security means that you can manage the Liberty profile by using aremote JMX client. To secure remote connections using the REST connector, see“Connecting to the Liberty profile by using JMX” on page 386. You can alsodevelop your own JMX client application as described in “Developing a JMX Javaclient for the Liberty profile” on page 389.

Authentication aliases

Authentication data aliases provide the security support for database connectivity.See “Configuring authentication aliases for the Liberty profile” on page 495.

Configuration examples and samples

Several security configuration examples are available in the ${wlp.install.dir}/templates/config directory to help you understand and develop common securityconfigurations. You can refer to those examples when you configure security foryour application in the Liberty profile.

Security compatibility and differences

You can learn about the main differences in the security capability between the fullprofile and the Liberty profile. See “Configuration differences between the fullprofile and Liberty profile: security” on page 46.

Troubleshooting

Use the troubleshooting information to solve security-related problems when youuse the Liberty profile. See “Troubleshooting security” on page 547 and“Troubleshooting LDAP” on page 549.


Tools

Configure security by using the Eclipse-based developer tools for the Libertyprofile. See “Editing the Liberty profile configuration by using developer tools” onpage 344. Specific information about tools and security configuration is available in“Configuring TAI on the Liberty profile by using developer tools” on page 471 and“Configuring JAAS on the Liberty profile by using developer tools” on page 466.


Liberty profile: Quick overview of securityThis topic describes some common security terms, along with an example thathelps you understand the basic workflow of security in the Liberty profile.

Security key terms

AuthenticationAuthentication confirms the identity of a user. The most common form ofauthentication is user name and password, such as through basicauthentication or form login for web applications. When a user isauthenticated, the source of a request is represented as a Subject object atrun time.

AuthorizationAuthorization determines whether a user has access to a given role withinthe system. The Java EE model uses subjects, roles, and role mappings todetermine if access is allowed.

Role A role is defined within the Java EE application. Some roles, such as theAdministrator role, are predefined by the system. Other roles are definedby the application developer. In Java EE, subjects are usually granted ordenied access to a role based on the roles they perform within theapplication.

SubjectA subject is both a general term and a Java object:javax.security.auth.Subject. Generally, the term subject means activeentities within the system, such as users on the system, and even thesystem process itself.

Security workflow example

The following example demonstrates how the security is applied when a userrequests access to a resource. For example, a user Bob wants to access a servletmyWebApp. See the code samples in “Getting started with security in the Libertyprofile” on page 445.

To access the servlet myWebApp, the following conditions must be true:1. Bob must be able to log in to the system because the servlet is protected.2. Bob must be in the testing role because the servlet is restricted by using an

auth-constraint element in the deployment descriptor.

If Bob cannot log in to the system, or Bob is not in the testing role, then the accessto the servlet myWebApp is denied.

Another user Alice can log in to the system because Alice is a valid user. ButAlice is not in the testing role. An HTTP 403 error (Access Denied/Forbidden)displays when Alice logs in.

Liberty profile: AuthenticationAuthentication in the Liberty security is to confirm the identity of a user.

When a protected web resource is accessed, the user must provide credential data,such as user ID and password, to access the resource. The authentication processinvolves collecting this user credential information (based on how the webapplication was configured to collect this data) and validating it against the


configured registry. When the credential information is verified, a JAAS subject iscreated for that user. The subject contains additional information about the user,such as the groups that the user belongs to, and the tokens created for the user.The information in this subject is then used during the authorization process todetermine whether the user can access the resource.

The following diagram illustrates a typical authentication process flow for a webresource.

The authentication process involves gathering credential data from the user,checking the cache to see whether the subject exists for that user and in its absencecalling the JAAS service to perform the authentication to create a subject. TheJAAS service calls a set of login modules to handle the authentication. One ormore of the login modules creates the subject depending on the credential data.The login module then calls the registry that is configured to validate thecredential information. If the validation is successful, the authentication processcollects and creates relevant information for that user, including the groups that theuser belongs to and the single sign-on (SSO) token used for SSO capability, andstores them in the subject as relevant credentials. You can also customize theinformation saved in the subject by plugging in custom login modules during thisprocess.

When the authentication is successful, the SSO token that is created during theprocess is sent back to the browser in a cookie. The default name of theconfigurable cookie is ltpaToken2. On subsequent calls, the token information is

Authenticationservice

AuthCacheservice

JAASservice

Subject

permit/deny

ID/passwordSSOTokencertificate

Browser/HTTP client

UserRegistryservice

Credentialservice

Tokenservice

Figure 6. Overview of authentication process


used to authenticate the user. If this authentication fails, the authentication servicetries to use other authentication data, such as the user ID and password, if theystill exist in the request.

The following sections describe these concepts in detail:v “User registries”v “Authentication cache”v “JAAS configuration”v “JAAS login modules” on page 32v “Callback handler” on page 33v “Credentials and tokens” on page 33v “LTPA” on page 33v “Single sign-on (SSO)” on page 34v “Pluggable authentication” on page 35v “Identity assertion” on page 35v “RunAs() authentication” on page 37v “Proxy login module” on page 37v “Certificate login” on page 37v “Hash table login module” on page 38

User registries

When validating the authentication data of a user, the login modules call the userregistry that is configured to validate the user information. The Liberty profilesupports both a simple configuration-based user registry and a more robustLDAP-based repository. For more information, see “Configuring a user registry forthe Liberty profile” on page 459.

Authentication cache

Because creating a subject is relatively expensive, the Liberty profile provides anauthentication cache to store a subject after the authentication of a user issuccessful. The default expiration time for the cache is 10 minutes. If the user doesnot log back in within 10 minutes, the subject is removed and the process ofauthentication repeats to create a subject for that user. Changes to the configurationthat affect the creation of the subject, such as adding a login module or changingthe LTPA keys, will cause the authentication cache to be cleared. If the subject iscached and the information in the registry changes, the cache is updated with theinformation in the registry. You can configure the cache timeout period, and thecache size, and you can also disable or enable caching. For more information, see“Configuring the authentication cache on the Liberty profile” on page 464.

JAAS configuration

JAAS configuration defines a set of login modules to create the subject. The Libertyprofile supports the following JAAS configurations:

system.WEB_INBOUNDUsed when accessing web resources such as servlets and JSPs.

WSLoginUsed by applications when using the programmatic login.


system.DEFAULTUsed for login when no JAAS configuration is specified.

The system.WEB_INBOUND and system.DEFAULT configurations have thesedefault login modules in this order: hashtable, userNameAndPassword,certificate, and token. The WSLogin configuration has the proxy login module asthe default login module, and the proxy delegates all the operations to the reallogin module in system.DEFAULT.

No explicit configuration is required unless you want to customize by using thecustom login modules. Depending on the requirement, you can customize specificlogin configurations. For example, if you want all the web resource logins to becustomized, you must add custom login modules only to the system.WEB_INBOUNDconfiguration. See “Configuring a JAAS custom login module for the Libertyprofile” on page 465.

JAAS login modules

JAAS configuration uses a set of login modules to create the subject. The Libertyprofile provides a set of login modules in each of the login configurations.Depending on the authentication data, a particular login module creates thesubject. The authentication data is passed to the login modules by using thecallback handler, as specified in the JAAS specification. For example, if the user IDand password callback handler is being used for authentication, theuserNameAndPassword login module handles the authentication. If aSingleSignonToken credential is presented as the authentication data, only thetoken login module handles the authentication.

The following default login modules are supported in the Liberty profile:

userNameAndPasswordHandles the authentication when user name and password are used as theauthentication data.

certificateHandles the authentication when an X509 certificate is used as theauthentication data of mutual SSL.

token Handles the authentication when an SSO token is presented as theauthentication data. During the authentication process, an SSO token iscreated and sent back to the HTTP client (browser) in a cookie. Onsubsequent requests, this cookie is sent back by the browser and the serverextracts the token from the cookie to authenticate the user when the singlesign-on is enabled.

hashtableUsed when the authenticated data is sent through a predefined hash table.For more information about the hash table login, see “Hash table loginmodule” on page 38. This login module is also used by the security runtime when authentication is performed using identity only; for example, inthe case of runAs.

proxy The default login module for WSLogin. See “Proxy login module” on page37.

The login modules are called in the order that they are configured. The defaultorder is hashtable, userNameAndPassword, certificate, token. If you mustcustomize the login process by using custom login modules, you can provide them


and configure them in the order you need. Typically, place a custom login modulefirst in the list of login modules so that it is called first. When a custom loginmodule is used, you must specify all the login module information in theconfiguration along with the custom login module in the required order.

When a login module determines that it can handle the authentication, it firstmakes sure that the authentication data that is passed in is valid. For example, foruser name and password authentication, the configured user registry is called toverify the authentication information. For token authentication, the token must bedecrypted and valid for the verification to succeed.

When the authentication data is validated, the login modules create credentialswith additional data for the user including the groups and the SSO token. Acustom login module can add additional data to the subject by creating its owncredentials. For the Liberty profile authorization to work, the subject must containthe WSCredential, WSPrincipal, and SingleSignonToken credentials. TheWSCredential credential contains the groups information, with additionalinformation that is required by the security runtime environment.

Callback handler

The Liberty profile supports various callback handlers for providing data to thelogin modules during the JAAS authentication process. A custom login module canuse the callback handler information to authenticate itself. For example, if thecallback handler needs to access some information in an HttpServletRequestobject, it can do so by using that specific callback handler.

The following callback handlers and factories for programmatic JAAS login aresupported in the Liberty profile:v com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl

v com.ibm.wsspi.security.auth.callback.WSCallbackHandlerFactory


See “Developing JAAS custom login modules for a system login configuration” onpage 499.

Credentials and tokens

As mentioned in the loginModule section, credentials are created as part of thesubject creation process. The Liberty profile creates the WSCredential,SingleSignonToken, and WSPrincipal credentials. The SingleSignonToken credentialcontains the token that is sent back to the browser in a cookie for SSO to work.This token contains the user information and an expiration time. It is signed andencrypted by using the Lightweight Third Party Authentication (LTPA) keys thatare generated during the first server startup. The default expiration time is 2 hoursand is an absolute time, not based on user activities. After the 2 hours, the tokenexpires and the user must log in again to access the resource.

LTPA

LTPA is intended for distributed and multiple application server environments. Inthe Liberty profile, LTPA supports SSO and security in a distributed environment


through cryptography. This support enables LTPA to encrypt, digitally sign, andsecurely transmit authentication-related data, and later decrypt and verify thesignature.

Application servers can securely communicate using the LTPA protocol. Theprotocol also provides the SSO feature, whereby a user is required to authenticateonly when connecting to a domain name system (DNS). Then the user can accessresources in other Liberty profile servers in the same domain without gettingprompted. The realm names on each system in the DNS domain are case-sensitiveand must match identically.

The LTPA protocol uses cryptographic keys to encrypt and decrypt user data thatpasses between the servers. These keys must be shared between different serversfor the resources in one server to access resources in other servers, assuming thatall the servers involved use the same user registry. LTPA requires that theconfigured user registry must be a centrally shared repository so that users andgroups are the same, regardless of the server.

When using LTPA, a token is created that contains the user information and anexpiration time, and is signed by the keys. The LTPA token is time sensitive. Allparticipating servers must have their time and date synchronized. If not, LTPAtokens are prematurely expired and cause authentication or validation failures.Coordinated Universal Time (UTC) is used by default, and all other servers musthave the same UTC time. See your operating system documentation forinformation about how to ensure the same UTC time among servers.

The LTPA token passes to other servers through cookies for web resources whenSSO is enabled.

If the receiving servers use the same keys as the originating server, the token canbe decrypted to obtain the user information, which then is validated to make surethat the token is not expired and that the user information in the token is valid inits registry. On successful validation, the resources in the receiving servers areaccessible after the authorization check.

Each server must have valid credentials. When the credentials expire, the server isrequired to communicate to the user registry to authenticate. Extending the timethat the LTPA token remains cached presents a slightly increased security risk to beconsidered when defining your security policies.

If key sharing is required between different Liberty profile servers, copy the keysfrom one server to another. For security purposes, the keys are encrypted with arandomly-generated key, and a user-defined password is used to protect the keys.This same password is needed when importing the keys into another server. Thepassword is used only to protect the keys, and is not used to generate the keys.

When security is enabled, LTPA is configured by default during the Liberty profileserver start time. For more information about the LTPA support, see “ConfiguringLTPA on the Liberty profile” on page 467.

Single sign-on (SSO)

SSO enables users to log in in one place (one server for example) and accessapplications on other servers without getting prompted again. To make SSO work,the LTPA keys must be exchanged across different Liberty profile servers, the userregistries must be the same, and the token must not have expired. To exchange the


LTPA keys, you can copy the ltpa.keys file from one server to another and restartthe server to use the new LTPA keys. The registries that are used by all the serversparticipating in the SSO domain must be the same.

When a user is authenticated in one Liberty profile server, the SSO token createdfor the user during the authentication process is put in the cookie that is sent tothe HTTP client, for example a browser. If there is another request from that clientto access another set of applications on a different server, but in the same DNS thatwas configured as part of the SSO configuration in the first server, the cookie issent along with the request. The receiving server tries to authenticate the userusing the token in the cookie. If both conditions are met, the receiving servervalidates the token and creates a subject based on the user in this server, withoutprompting the user to log in again. If the token cannot be validated (for example,it cannot decrypt or verify the token because of LTPA key mismatch), the user isprompted to enter the credential information again.

Any application that is configured to use the Form-login attribute must have SSOto be configured for that server. When the user is authenticated for a form-login,the token is sent back to the browser that will be used for authorizing the userwhen the resource is accessed.

See “Customizing SSO configuration using LTPA cookies for the Liberty profile” onpage 468.

Pluggable authentication

Use the following ways to customize the authentication process:v Provide a custom login module. Most of the authentication process is built

around JAAS login modules, so you can plug in custom login modules before,after, or between the login modules provided by the Liberty profile. See“Configuring a JAAS custom login module for the Liberty profile” on page 465.

v Implement Trust Association Interceptor (TAI) to handle all web resource-basedauthentication. See “Developing a custom TAI for the Liberty profile” on page498.

For more details about the JAAS login module and TAI, see Advancedauthentication in WebSphere Application Server.

Identity assertion

Besides authentication that requires a requesting entity to prove its identity, theLiberty profile also supports identity assertion. This is a relaxed form ofauthentication that does not require identity proof, but rather accepts the identitybased on a trust relationship with the entity that vouches for the asserted identity.

Use the following ways to assert identities in the Liberty profile1. Use the hash table login. See “Developing JAAS custom login modules for a

system login configuration” on page 499.2. Use IdentityAssertionLoginModule. You can allow an application or system

provider to assert an identity with trust validation. To useIdentityAssertionLoginModule, use the JAAS login framework, where trustvalidation is accomplished in one custom login module and credential creationis accomplished in IdentityAssertionLoginModule. You can use the two loginmodules to create a JAAS login configuration that can be used to assert anidentity.


http://www.ibm.com/developerworks/websphere/techjournal/0508_benantar/0508_benantar.html

http://www.ibm.com/developerworks/websphere/techjournal/0508_benantar/0508_benantar.html

The following two custom login modules are required:

User implemented login module (trust validation)The user implemented login module performs whatever the userrequires in trust verification. When trust is verified, the trustverification status and the login identity must be put into a map in theshare state of the login module, so that the credential creation loginmodule can use the information. Store this map in the followingproperty:com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.state

This property consists of the following properties:v

com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.trusted

This property is set to true if trusted and false if not trusted.v

com.ibm.wsspi.security.common.auth.module.IdenityAssertionLoginModule.principal

This property contains the principal of the identity.v

com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certificates

This property contains the certificate of the identity.

Identity assertion login module (credential creation)The following module creates the credential:com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule

This module relies on the trust state information in the shared state ofthe login context.

The identity assertion login module looks for the trust information inthe shared state property:com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.state

This property contains the trust status and the identity to log in, andmust include the following property:v

com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.trusted

This property is set to true when trusted and false when nottrusted.

v

com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.principal

This property contains the principal of the identity to log in if aprincipal is used.

v

com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certificates

This property contains an array of a certificate chain that contains theidentity to log in if a certificate is used.

A WSLoginFailedException message is returned if the state, trust, oridentity information is missing. The login module then logs in with theidentity, and the subject contains the new identity.


See “Customizing an application login to perform an identity assertion usingJAAS” on page 503.

RunAs() authentication

When you have successfully authenticated after calling a servlet, the servlet canmake subsequent calls, for example to other servlets. These subsequent calls arenormally made under the same security identity that you originally used to log into the servlet. This identity is known as the caller identity. Alternatively, you canchoose to delegate to a different identity by using the RunAs specification, so thatany subsequent calls that the servlet makes run under this other identity. Tosummarize, you have two options to propagate the security identity:v Propagate the caller identity, which is the default behavior.v Delegate to the RunAs identity that you can specify by using the RunAs

specification.

After the server authenticates the original user, the server then authenticates theRunAs user. If this authentication fails, the server falls back to propagate the calleridentity.

To use the RunAs specification, you must update the deployment descriptor ofyour application to include the run-as element or @RunAs annotation. Set thiselement to the security role that you want to delegate to.

See “Configuring RunAs authentication in the Liberty profile” on page 469.

Proxy login module

The proxy login module class loads the application server login module anddelegates all the operations to the real login module implementation. The real loginmodule implementation is specified as the delegate option in the optionconfiguration. The proxy login module is required because the application classloaders do not have visibility of shared library class loaders of the applicationserver product. With an application programmatic login that uses the Login()method of the LoginContext class with JAAS login context entry WSLogin, theproxy login module delegates all the work to the JAAS login context entrysystem.DEFAULT.

Certificate login

With the certificate login feature, you can authenticate web requests such asservlets by using client side X509 certificates instead of supplying a user ID andpassword.

Certificate authentication works by associating a user in the user registry with thedistinguished name in the client certificate of a web request. Trust is established byhaving the client certificate trusted by the server, for example the signer of theclient certificate must be in the trust store of the server. This mechanism eliminatesthe need for users to supply a password to establish trust.

See “Securing communications with the Liberty profile” on page 65.


Hash table login module

Look up the required attributes from the user registry, put the attributes in a hashtable, and then add the hash table to the shared state. If the identity is switched inthis login module, you must add the hash table to the shared state. If the identityis not switched, but the value of the requiresLogin code is true, you can create thehash table of attributes. You do not have to create a hash table in this situation,because the Liberty profile handles the login for you. However, you might considercreating a hash table to gather attributes in special cases. For example, if you areusing your own special user registry, then creating a UserRegistry implementation,using a hash table, and letting the server gather the user attributes for you, mightbe a simple solution.

The following rules define in more details about how a hash table login iscompleted. You must use a java.util.Hashtable object in either the Subject (publicor private credential set) or the shared-state HashMap. Thecom.ibm.wsspi.security.token.AttributeNameConstants class defines the keys thatcontain the user information. If the Hashtable object is put into the shared state ofthe login context using a custom login module that is listed before the hashtablelogin module, the value of the java.util.Hashtable object is searched using thefollowing key within the shared-state hashMap:

Propertycom.ibm.wsspi.security.cred.propertiesObject

Reference to the propertyAttributeNameConstants.WSCREDENTIAL_PROPERTIES_KEY

ExplanationThis key searches for the Hashtable object that contains the requiredproperties in the shared state of the login context.

Expected resultA java.util.Hashtable object.

If a java.util.Hashtable object is found inside the Subject or within the sharedstate area, verify that the following properties are present in the hash table:v com.ibm.wsspi.security.cred.uniqueId

Reference to the propertyAttributeNameConstants.WSCREDENTIAL_UNIQUEID

Returnsjava.util.String

ExplanationThe value of the property must be a unique representation of the user.For the Liberty profile default implementation, this property representsthe information that is stored in the application authorizationconfiguration. The information is in the application deploymentdescriptor after it is deployed and the user-to-role mapping isperformed. See the expected format examples if the user to role mappingis performed by looking up a user registry implementation of the Libertyprofile.

Expected format examples


Table 3. Format examples for uniqueId. This table gives expected format examples.

User Registry Format (UniqueUserId) value

LDAP ldapRegistryRealm/cn=kevin,o=mycompany,c=use

Basic basicRegistryRealm/kelvin

The com.ibm.wsspi.security.cred.uniqueId property is required.v com.ibm.wsspi.security.cred.securityName

Reference to the propertyAttributeNameConstants. WSCREDENTIAL_ SECURITYNAME

Returnsjava.util.String

ExplanationThis property searches for securityName of the authentication user. Thisname is commonly called the display name or short name. The Libertyprofile uses the securityName attribute for the getRemoteUser,getUserPrincipal, and getCallerPrincipal application programminginterfaces (APIs). To ensure compatibility with the defaultimplementation for the securityName value, call the public StringgetUserSecurityName(String uniqueUserId) UserRegistry method.


Table 4. Format examples for securityName. This table gives expected format examples.

User Registry Format (securityName) value

LDAP kevin

Basic kevin

The com.ibm.wsspi.security.cred.securityname property is required.v com.ibm.wsspi.security.cred.group

Reference to the propertyAttributeNameConstants. WSCREDENTIAL_GROUP

Returnsjava.util.ArrayList

ExplanationThis key searches for the array list of groups to which the user belongs.The groups are specified in the realm_name/user_name format. The formatof these groups is important because the groups are used by the Libertyprofile authorization engine for group-to-role mappings in thedeployment descriptor. The format that is provided must match theformat expected by the Liberty profile default implementation. Whenyou use a third-party authorization provider, you must use the formatthat is expected by the third-party provider. To ensure compatibility withthe default implementation for the unique group IDs value, call thepublic List getUniqueGroupIds(String uniqueUserId) UserRegistrymethod.


Table 5. Format examples for group. This table gives some format examples whenconfiguring inbound identity mapping.

User Registry Format (group) value

LDAP ldapRegistryRealm/cn=group1,o=Groups,c=US


Table 5. Format examples for group (continued). This table gives some format exampleswhen configuring inbound identity mapping.

User Registry Format (group) value

Basic basicRegistryRealm/group1

The com.ibm.wsspi.security.cred.group property is required. A user isnot required to be associated groups.

v com.ibm.wsspi.security.cred.cacheKey

Reference to the propertyAttributeNameConstants. WSCREDENTIAL_CACHE_KEY

Returnsjava.lang.Object

ExplanationThis key property can specify an object that represents the uniqueproperties of the login, including the user-specific information and theuser dynamic attributes that might affect uniqueness. For example, whenthe user logs in from location A, which might affect their access control,the cache key must include location A so that the received Subject is thecorrect Subject for the current location.

This com.ibm.wsspi.security.cred.cacheKey property is not required.When this property is not specified, the cache lookup is the value that isspecified for WSCREDENTIAL_UNIQUEID. When this information isfound in the java.util.Hashtable object, the Liberty profile creates aSubject similar to the Subject that goes through the normal login process,at least for LTPA. The new Subject contains a WSCredential object and aWSPrincipal object that is fully populated with the information found inthe Hashtable object.

Liberty profile: AuthorizationAuthorization in the Liberty profile determines whether a user has access to agiven role within the system.

Authorization specifies access rights to resources. It usually follows authenticationthat confirms an identity. Whereas authentication answers the question: "Are youwho you say you are?"; authorization answers the question: "Do you havepermission to do what you are trying to do?"

The following sections describe these concepts in detail:v “Authorization for administrative functions”v “Authorization for applications” on page 41v “Special subjects” on page 42v “Access IDs and authorization” on page 42

Authorization for administrative functions

When an entity attempts to access a resource, the authorization service determineswhether that entity has the required rights to access the resource. This conceptholds true whether an entity is accessing an application or performingadministrative functions. The main difference between authorizing access to anapplication and access to an administrative function lies in how the users aremapped to roles. For authorization of applications, use the application-bndelement in the server.xml file or the ibm-application-bnd.xml/xmi file to map the


users to roles. For authorization of administrative functions, use theadministrator-role element in the server.xml file to map the users to theadministrator role. For more information about administrative security, See“Connecting to the Liberty profile by using JMX” on page 386.

Authorization for applications

The following diagram describes how authorization works for applications:

1. Authorization is performed when an entity attempts to access a resource in anapplication served by the Liberty profile. The web container calls theauthorization service to determine whether a user has permission to access acertain resource, given a set of one or more required roles. The required rolesare determined by the auth-constraint elements in the deployment descriptorand @ServletSecurity annotations.

2. The authorization service determines what objects the required role is mappedto. This step is accomplished by processing the mappings defined in theibm-application-bnd.xmi file or the ibm-application-bnd.xml file, and theapplication-bnd element of the server.xml file. The mappings from these twosources are merged. If the same role is present in both sources, only the rolemapping in the server.xml file is used. The advantage of using the server.xmlfile for mapping roles to users is that your application does not need to bepackaged into an EAR file and it is easier to update. Alternatively, using theibm-application-bnd.xmi/xml file makes your application portable to otherservers and other full profile servers that do not support the server.xml file.

3. If the required role is mapped to the EVERYONE special subject, then theauthorization service returns immediately to allow anyone access. If the role ismapped to the ALL_AUTHENTICATED_USERS special subject and the user isauthenticated, then the authorization service grants access to the user. If noneof these conditions are met, then the authorization service determines what

1

4

2 3

22

web container

Roles

AllRole EVERYONE

Employee ALL_AUTHENTICATED_USERS

Developer Bob, Alice

Manager DevManagerGroup

Mapped objects

ibm-application-bnd.xml/xmi

server.xml<application-bnd>

</application-bnd>

Authorizationservice

Figure 7. Overview of authorization process


users and groups are mapped to the required role. The authorization servicegrants access to the resource if the user is mapped to the required role or if theuser is part of a group that is mapped to the role.

4. The authorization service returns a result back to the web container to indicatewhether the user is granted or denied access.

Special subjects

When you map entities to roles, you can map a special subject instead of a specificuser or group. A special subject is an extension to the concept of a subject. Aspecial subject can represent a group of users that fall under a specific category.

The following two types of special subjects are available:v EVERYONE: represents any entity on the system, which means that no security is

available because everyone is allowed access and you are not prompted to entercredentials.

v ALL_AUTHENTICATED_USERS: represents any entity that has successfullyauthenticated to the server.

To map a special subject to a user, update either the ibm-application-bnd.xmi/xmlfile or the server.xml file. In this example, the role named AllAuthenticated ismapped to the special subject ALL_AUTHENTICATED_USERS:

<application-bnd><security-role name="AllAuthenticated">

<special-subject type="ALL_AUTHENTICATED_USERS" /></security-role>

</application-bnd>

See “Configuring authorization for applications on the Liberty profile” on page472.

Access IDs and authorization

When authorizing a user or group, the server needs a way to uniquely identifythat user or group. The unique ID of the user and group serve this purpose andare used to build the authorization configuration. These IDs are determined by theuser registry implementation: the unique user ID is the value ofgetUniqueUserId(), and the unique group ID is the value of getUniqueGroupId().You can also choose to explicitly specify an access ID for the user or group in theauthorization configuration. These explicit access IDs are used instead of the valuesreturned by the user registry implementation. To specify an access ID in theibm-application-bnd.xml/xmi file or the server.xml file, use the access-idattribute for the user or group element.

In this example, an access ID is specified for the user Bob and the groupdevelopers:

<application-bnd><security-role name="Employee">

<user name="Bob" access-id="user:MyRealm/Bob"/><group name="developers" access-id="group:myRealm/developers"/>

</security-role></application-bnd>

Avoid trouble: Specifying access IDs is not encouraged because you must code theunique IDs and realm name within your code, which causes problems when youwant to modify your user registry.


Liberty profile: Security public APIsSecurity public APIs in the Liberty profile provides a way of extending the securityinfrastructure.

The Liberty profile contains public APIs that you can use to implement securityfunctions. The security public APIs in the Liberty profile are a subset of the fullprofile security public APIs. The main classes are WSSecurityHelper, WSSubject,and RegistryHelper. These classes contain a subset of the methods that areavailable in the full profile versions. There is also a new class WebSecurityHelper.

The following sections describe those main classes. There are also other classessuch as UserRegistry, WSCredential, and other exception classes.

All the security public APIs supported by the Liberty profile are in the Java APIdocumentation. The Java API documentation for each Liberty profile API isavailable in a separate JAR file under the /dev/ibm-api/javadoc directory of theserver image.

WSSecurityHelperThis class contains only the methods isServerSecurityEnabled() andisGlobalSecurityEnabled(). They both return true if either of thefollowing features are enabled in the server.xml file:v appSecurity-2.0

v zosSecurity-1.0

Otherwise, the methods return false. These methods are carried over fromthe full profile WSSecurityHelper class for compatibility.

Note:

v There are no cells in the Liberty profile, so there is no distinction in theLiberty profile between global security and server security. Thereforeboth methods return the same value.

v The method revokeSSOCookies(javax.servlet.http.HttpServletRequestreq,javax.servlet.http.HttpServletResponse res) is not supported inthe Liberty profile. Instead you can use the Servlet 3.0 logout function.

v The method getLTPACookieFromSSOToken() has been renamed to a newpublic API class: WebSecurityHelper.

WSSubjectThis class provides utility methods for querying and setting the securitythread context. All methods from the full profile WSSubject are supportedin the Liberty profile.

Note: Java 2 security is not enabled in the Liberty profile, so the Java 2security checks in WSSubject are not performed.

RegistryHelperThis class provides access to the UserRegistry object and trusted realminformation. In the Liberty profile, it contains the following subset of thefull profile methods:

public static UserRegistry getUserRegistry(String realmName) throwsWSSecurityException

public static List<String> getInboundTrustedRealms(String realmName)throws WSSecurityException


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=rsec_secgetru

public static boolean isRealmInboundTrusted(String inboundRealm,String localRealm)

WebSecurityHelperThis class contains the renamed getLTPACookieFromSSOToken() method,which was moved from WSSecurityHelper:

public static Cookie getLTPACookieFromSSOToken() throws Exception

Security public API code examples

The following examples demonstrate how to use security public APIs in theLiberty profile to do a programmatic login and operate on the Subject.v Example 1: Create a Subject and use it for authorizationv Example 2: Create a Subject and make it as the current Subject on the threadv Example 3: Get information of the current Subject on the thread

Example 1: Create a Subject and use it for authorizationThis example demonstrates how to use WSSecurityHelper, WSSubject, andUserRegistry to do a programmatic login to create a Java Subject, thenperform an action and use that Subject for any authorization that isrequired.

Note: The following code uses WSSecurityHelper to check if security isenabled before doing further security processing. This check is usedextensively because of the modular nature of the Liberty profile: If securityis not enabled then the security run time is not loaded. WSSecurityHelperis always loaded, even if security is not enabled.import java.rmi.RemoteException;import java.security.PrivilegedAction;

import javax.security.auth.Subject;import javax.security.auth.callback.CallbackHandler;import javax.security.auth.login.LoginContext;import javax.security.auth.login.LoginException;

import com.ibm.websphere.security.CustomRegistryException;import com.ibm.websphere.security.UserRegistry;import com.ibm.websphere.security.WSSecurityException;import com.ibm.websphere.security.WSSecurityHelper;import com.ibm.websphere.security.auth.WSSubject;import com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl;import com.ibm.wsspi.security.registry.RegistryHelper;public class myServlet {

...if (WSSecurityHelper.isServerSecurityEnabled()) {UserRegistry ur = null;try {ur = RegistryHelper.getUserRegistry(null);} catch (WSSecurityException e1) {// record some diagnostic inforeturn;}String userid = "user1";String password = "user1password";try {if (ur.isValidUser(userid)) {// create a Subject, authenticating with// a userid and passwordCallbackHandler wscbh = new WSCallbackHandlerImpl(userid, password);LoginContext ctx;ctx = new LoginContext("WSLogin", wscbh);ctx.login();Subject subject = ctx.getSubject();// Perform an action using the Subject for// any required authorizationWSSubject.doAs(subject, action);}} catch (CustomRegistryException e) {// record some diagnostic inforeturn;} catch (RemoteException e) {


// record some diagnostic inforeturn;} catch (LoginException e) {// record some diagnostic inforeturn;}}...private final PrivilegedAction action = new PrivilegedAction() {@Overridepublic Object run() {// do something useful herereturn null;}};

}

Example 2: Create a Subject and make it the current Subject on the threadThe following example demonstrates how to use WSSecurityHelper andWSSubject to do a programmatic login to create a Java Subject, make thatSubject the current Subject on the thread, and finally restore the originalsecurity thread context.

Note: The following code uses WSSecurityHelper to check if security isenabled before doing further security processing.import javax.security.auth.Subject;import javax.security.auth.callback.CallbackHandler;import javax.security.auth.login.LoginContext;import javax.security.auth.login.LoginException;

import com.ibm.websphere.security.WSSecurityException;import com.ibm.websphere.security.WSSecurityHelper;import com.ibm.websphere.security.auth.WSSubject;import com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl;...if (WSSecurityHelper.isServerSecurityEnabled()) {CallbackHandler wscbh = new WSCallbackHandlerImpl("user1", "user1password");LoginContext ctx;try {// create a Subject, authenticating with// a userid and passwordctx = new LoginContext("WSLogin", wscbh);ctx.login();Subject mySubject = ctx.getSubject();Subject oldSubject = null;try {// Save a ref to the current Subject on the threadoldSubject = WSSubject.getRunAsSubject();// Make mySubject the current Subject on the threadWSSubject.setRunAsSubject(mySubject);// Do something useful here. Any authorization// required will be performed using mySubject} catch (WSSecurityException e) {// record some diagnostic inforeturn;} finally {// Put the original Subject back on the thread contextif (oldSubject != null) {try {WSSubject.setRunAsSubject(oldSubject);} catch (WSSecurityException e) {// record some diagnostic info}}}} catch (LoginException e) {// record some diagnostic inforeturn;}}

Example 3: Get information of the current Subject on the threadThe following example demonstrates how to use WSSecurityHelper,WSSubject, and WSCredential to get information about the current Subjecton the thread.

Note: The following code uses WSSecurityHelper to check if security isenabled before doing further security processing.


import java.util.ArrayList;import java.util.Iterator;import java.util.Set;

import javax.security.auth.Subject;import javax.security.auth.login.CredentialExpiredException;

import com.ibm.websphere.security.WSSecurityException;import com.ibm.websphere.security.WSSecurityHelper;import com.ibm.websphere.security.auth.CredentialDestroyedException;import com.ibm.websphere.security.auth.WSSubject;import com.ibm.websphere.security.cred.WSCredential;...if (WSSecurityHelper.isServerSecurityEnabled()) {// Get the caller’s subjectSubject callerSubject;try {callerSubject = WSSubject.getCallerSubject();} catch (WSSecurityException e) {// record some diagnostic inforeturn;}WSCredential wsCred = null;Set<WSCredential> wsCredentials =callerSubject.getPublicCredentials(WSCredential.class);Iterator<WSCredential> wsCredentialsIterator = wsCredentials.iterator();if (wsCredentialsIterator.hasNext()) {wsCred = wsCredentialsIterator.next();try {// Print out the groupsArrayList<String> groups = wsCred.getGroupIds();for (String group : groups) {System.out.println("Group name: " + group);}} catch (CredentialExpiredException e) {// record some diagnostic inforeturn;} catch (CredentialDestroyedException e) {// record some diagnostic inforeturn;}}}}

Configuration differences between the full profile and Libertyprofile: security

The configuration differences in the security capability between the Liberty profileand full profile indicates the items that you might need to know duringapplications migration.

The Liberty profile security supports only a subset of security features in the fullprofile. Unless the support is explicitly mentioned in the Liberty profiledocumentation, you must assume that the support is not available yet.

The following security features are not included in the Liberty profile:v Java EE security.v Not all public APIs and SPIs are supported. The Java API documentation for

each Liberty profile API is available in a separate JAR file under the/dev/ibm-api/javadoc directory of the server image.

v Horizontal propagation.v SecurityAdmin MBean support, therefore methods like clearing the

authentication cache are not available.v Java Authorization Contract for Container (JACC) support.v Java 2 Connector (J2C) principal mapping modules support.v Java Authentication SPI (JASPI) support.v Multiple security domain support.v Security auditing subsystem that is part of the security infrastructure of the

server.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=csec_secattributeprop

In the Liberty profile, you can configure user-to-role mappings and RunAs users inthe application-bnd element of the server.xml file. For a Run-As entry, thepassword is optional. In the full profile, you can only configure the Run-AS entryin the ibm-application-bnd.xml/xmi file. For a Run-As entry, the password isrequired. See “Configuring authorization for applications on the Liberty profile” onpage 472.

Liberty profile: The limits to protection through passwordencryption

The Liberty profile supports Advanced Encryption Standard (AES) encryption forpasswords that are stored in the server.xml file. When you use this option forprotecting system passwords in the Liberty profile configuration, you need tounderstand the limits to the protection it provides.

Encrypting a password in the Liberty profile configuration does not guarantee thatthe password is secure or protected; it only means that someone who can see theencrypted password, but does not know the encryption key, cannot easily recoverthe password. The application server process requires access to both the encryptedpassword and the decryption key, so both these data items need to be stored onthe file system that is accessible to the server runtime environment. The encryptionkey is also required by anyone who encrypts a password that is placed in theserver configuration. For an attacker that has access to exactly the same set of filesas the Liberty profile server instance, applying AES encryption to the passwordtherefore provides no additional security over and above “exclusive or” (XOR)encoding.

Nonetheless, there are still reasons why you might consider encrypting passwordsin the Liberty profile configuration. The Liberty profile configuration is designed tobe highly composable and sharable. The administration subsystem of the fullprofile (the administrative console and wsadmin scripting) prevents anadministrator from gaining access to an XOR-encoded password. The Libertyprofile is designed to be configured without an administration subsystem, and soany XOR-encoded password is visible to any administrator. Given these designfeatures, consider the following scenarios:v The passwords are not sensitive, so encoding them provides little value.v The passwords are sensitive, so either the configuration files containing the

password are security sensitive and access needs to be controlled, or thepasswords are encrypted and the encoding key is then protected as securitysensitive.

The encryption key used for decrypting can be overridden from the default bysetting the wlp.password.encryption.key property. This property should not be setin the server.xml file that stores the password, but in a separate configuration filethat is included by the server.xml file. This separate configuration file shouldcontain only a single property declaration, and should be stored outside thenormal configuration directory for the server. This ensures that the file containingthe key is not included when you are running the server dump or packagecommand. The encryption key property can also be specified as a bootstrapproperty. If you choose this option, you should put the encryption key in aseparate properties file that is included in the server bootstrap.properties file.


For information about using XOR or AES to protect your passwords see the relatedlinks, especially “Liberty profile: securityUtility command” on page 456.

Liberty profile: Messaging

Liberty messaging is a composable, flexible, and dynamic JMS messaging enginethat runs in the Liberty profile. Liberty messaging is JMS 1.1 compliant andsupports both the point-to-point and publish/subscribe messaging models.

Liberty messaging runs only in the Liberty run time, and you can use the Libertyfeature manager to enable or disable the messaging features as required. Becausethe messaging run time is highly composable, you can enable the basic messagingfeatures for the run time, and dynamically enable additional messaging features,such as security, transactions, and remote communication, based on therequirement.

Liberty messaging can be classified into two parts:v JMS Server run time: Provides all the runtime capabilities for connections,

transactions, persistence, security, and so on.v JMS Client connectivity: Provides the resource adapter support to allow JMS

clients to perform synchronous and asynchronous messaging activities.

The messaging engine runs as a singleton instance in a Liberty profile, whichmeans that at any given time there can be only one messaging engine that isrunning in a Liberty kernel.

Liberty messaging architecture

Liberty messaging is highly composable and dynamic in nature. Liberty messagingconsists of several other internal messaging subcomponents, implemented as OSGibundles, that can be enabled or disabled based on the user requirements. OSGiservices are used to manage component lifecycles and the injection ofdependencies and configurations.


The messaging run time and the other messaging subcomponents run as OSGibundles in an OSGi framework. This enables the Liberty kernel to load or unloadthe messaging bundles based on the usage. For example, if the user does not usemessaging security then the bundles that are related to messaging security are notinitialized.

Application deployment

Liberty messaging supports three types of JMS application connectivity. Theapplication can run in any of the following ways:v In a Liberty profile that is hosting the messaging engine.v In a different Liberty profile that is not hosting any messaging engine.v As a J2SE client.

Core MessagingRuntime Service

Persistence StoreService

File Store

Security Service

Transaction Service

Utility Service

Comms Service

PMI Service

Resource Adapter Service

JMS Resources Service

Liberty Messaging Service Components

Components that are not part of core

Components that are necessary for the

Figure 8. Liberty messaging architecture


Liberty messaging supports both in-process and network TCP/IP connectivity forapplications. When the JMS application is deployed in the same JVM where themessaging engine is running, the application can communicate with the in-processmessaging engine, without going over the TCP/IP layer. This provides significantperformance benefits for the applications to send and receive messages.

JMS applications that are running on the Liberty profile that is not hosting themessaging engine must connect over TCP/IP in order to communicate with themessaging engine.

Message handling

Destinations (queues or topics) are always localized to the messaging engine wherethe destinations are defined. If the application needs to send or receive a messagefrom a destination, it must always connect to the messaging engine that localizesthe destination.

Liberty server J2SE client

Liberty Server

MessagingEngine

JMS Application

JMS Application JMS Application

Figure 9. Application deployment model


Liberty profile: High Performance Extensible Logging (HPEL)

High Performance Extensible Logging (HPEL) is a log and trace facility that isprovided as a part of the product.

Overview

Note: The basic log and trace facility is enabled by default. To use HPEL you mustenable it.

Distributed operating systems HPEL provides a convenient mechanism for storing andaccessing log, trace, System.err, and System.out information produced by theapplication server or your applications. It is an alternative to the basic log andtrace facility, which provides the JVM logs and diagnostic trace files commonlynamed messages.log and trace.log.

HPEL log and trace storage

HPEL provides a log data repository, a trace data repository, and a text log file. Seethe following figure to understand how applications and the application serverstore log and trace information.

Liberty Server Liberty Server

Messaging Engine

JMS Application JMS consumer

J2SE ClientJMS consumer

Queue/Topic

JMS Application

Figure 10. Message handling in Liberty messaging


Log data repository

Trace datarepository

Text log

trace.log

console.log

messages.log

Application code Application code

com.xyz.abc.def( logger )

Log/Trace Service

Log/Trace data handler

Log/Trace service

Log/Trace handler

com.xyz.abc.ghi( logger )

root ( logger )

Tr SPI

com.xyz.abc( logger )

Legend

default logging framework

HPEL logging framework

com.ibm.ws( logger )

Service broker

HPEL

Default

WebSphere Application Server

Applications

HPEL log data repository

The log data repository is a storage facility for log records. Log data istypically intended to be reviewed by administrators. This includes anyinformation applications or the server write to System.out, System.err,OSGi logging service at level LOG_INFO or higher (including LOG_INFO,LOG_WARNING, and LOG_ERROR), or java.util.logging at level Detail orhigher (including Detail, Config, Info, Audit, Warning, Severe, Fatal, andany custom levels at level Detail or higher).

HPEL trace data repository

The trace data repository is a storage facility for trace records. Trace data istypically intended for use by application programmers or by theWebSphere Application Server support team. This includes any informationapplications or the server write to the OSGi logging service at levelLOG_DEBUG or java.util.logging at levels below level Detail (includingFine, Finer, Finest, and any custom levels below level Detail).

HPEL text log

The text log file is a plain text file for log and trace records. The text logfile is provided for convenience, primarily so that log content can be readwithout having to run the LogViewer command-line tool to convert the logdata repository content to plain text.


The text log file does not contain any content that is not also stored ineither the log data repository or trace data repository. You can disable thetext log to enhance server performance. The text log can be configured torecord trace content for debugging convenience.

Note: Writing trace to the text log is expensive from a performanceperspective.

Log and trace performance

Distributed operating systems HPEL has been designed and tested to significantlyoutperform the existing basic log and trace facility. One result is that theapplication server can run with trace enabled while causing less impact toperformance than tracing the same components using basic logging. Another resultis that applications that frequently write to the logs can run faster when usingHPEL. A number of factors contribute to the overall performance of HPEL loggingand tracing.

Log and trace events are each stored in only one place

Log events, System.out, and System.err are stored in the log datarepository. Trace events are stored in the trace data repository. If the textlog file is disabled, HPEL will only write log and trace content to theserepositories. Storing each type of event in one place ensures thatperformance is not wasted on redundant data storage.

Log events, and optionally trace events, are written to the text log filewhen it is enabled. Since this data is always also stored in the log data andtrace data repositories, the text log file content is redundant. The text log isconvenient for users who do not want to run the LogViewer command-linetool to see their logs and trace; but you can disable the text log if thisconvenience is not needed.

Data is not formatted unless it is needed

Formatting data for a user to read uses processor time. Rather than formatlog event and trace event data at run time, HPEL log and trace data isstored more rapidly in a proprietary binary representation. This improvesthe performance of the log and trace facility. By deferring log and traceformatting until the LogViewer is run, sections of the log or trace that arenever viewed are never formatted.

You can enable the text log file, which stores the log data and trace data inan already readable text format.

Note: Disable the text log when performance of your server is a keyconcern, or if the text log is not wanted.

Log and trace data is buffered before being written to disk

Writing large blocks of data to a disk is more efficient than writing thesame amount of data in small blocks. HPEL provides the capability tobuffer log and trace data before writing it to disk. By default, log and tracedata is stored in an 8 KB buffer before being written to disk. If the buffer isfilled within 10 seconds, the buffer is written to disk. If the buffer is notfilled within that time it is automatically written to disk to ensure that thelogs have the most current information.


Administration of log and trace

HPEL has been designed to be easy to configure and understand. For example,administrators can easily configure how much disk space to dedicate to logs ortrace, or how long to retain log and trace records, and leave the management oflog and trace content up to the server. As another example all log, trace,System.out, and System.err content can be accessed using one easy-to-usecommand (LogViewer), avoiding any possible confusion over which file to accessfor certain content.

Reading from the log data and trace data repositories

The log data and trace data repositories are stored in a WebSphereApplication Server proprietary format and cannot be read using text fileeditors such as Notepad or VI. You can copy the log data and trace datarepositories in to a plain text format using the LogViewer command.

HPEL LogViewer command

The HPEL LogViewer is an easy-to-use, command-line tool provided forHPEL users to work with the log data and trace data repositories. TheLogViewer provides filtering and formatting options that make findingimportant content in the log data and trace data repositories easy. Forexample, a user might filter any errors or warnings, then filter all log andtrace entries that occurred within 10 seconds of a key error message on thesame thread.

Filtering using log and trace record extension content

HPEL provides the capability for developers to add custom extensions tolog and trace records using a log record context API(com.ibm.websphere.logging.hpel.LogRecordContext). You can use theLogViewer command-line tool to filter records based on the content of logand trace record extensions.

Development resources

HPEL has been designed to make working with log and trace content more flexibleand effective than the basic logging facility. Log and trace content can be easilyfiltered to show only the records that are of interest. You can use the command line(see the description of the HPEL LogViewer command), or developers can createpowerful log handling programs using the HPEL API.

Reading the log data and trace dataDevelopers can use the com.ibm.websphere.logging.hpel API to read thelog data and trace data repositories

HPEL API

An API has been provided to make it easy for developers to develop toolsto consume content from the HPEL log and trace repositories. For example,a developer might write a Java program to search the log and trace contentto find any messages with message IDs that match a known list ofimportant message IDs. This API is in the com.ibm.websphere.logging.hpelpackage. Refer to the API documentation for details on the HPEL logreading API.

Log and trace record extensibility

As with other log and trace record fields, developers can access the recordextensions using the HPEL API. This is useful when writing tools to read


from log and trace repositories. Developers can also make use of the logrecord context API to access extensions in custom log handlers, filters, andformatters at run time.

LogViewer command-line tool

Use the LogViewer command to query the contents of the High PerformanceExtensible Logging (HPEL) log and trace repositories. You can also use theLogViewer command to view new log and trace repository entries as the serverwrites content to them.

LogViewer

The High Performance Extensible Logging (HPEL) facility writes to the log andtrace repositories in a binary format. You can view, query and filter the repositoryusing the LogViewer command. The LogViewer command provides options forquickly converting HPEL logs into a text file in various formats, including basic,advanced, and Common Base Event format. The command also provides optionsto make getting the data you need from the logs easier; for example, allowing youto filter what log records you want by level, logger name, or date and time.

Use the following command to view the full contents of your log and tracerepositories:

v Windows (Windows) logViewer.bat

Optional parameters

[Liberty profile] servernameSpecifies the name of the server whose log and trace data repositories youwant the logViewer command to use. This parameter is not needed in caseswhere there is only one Liberty profile server created nor in cases where youspecify the path to the log and trace data repository root using the-repositoryDir parameter.

-repositoryDir directory_nameSpecifies the path to the repository directory. In the case where you want toquery both the log and trace data together, provide the path to the parentdirectory, which contains both the log data and tracedata directories. If you usethe default repository location, profile_root/logs/application_server/, and runthis tool from the profile bin directory, then this argument is optional. The toolchecks the default location if one is not provided. If multiple applicationservers exist in this profile with HPEL repositories, you are prompted to selectwhich server log and trace repository you want to view.

-outLog file_nameSpecifies the file name you want the text output written to. If you do notprovide this information, the text output is displayed on the console.

-format basic | advanced | cbe-1.0.1Specifies the output format. Supported formats include basic, advanced, andthe CBE-1.0.1 format. If you do not provide this information, the output is inbasic format.

-monitor [integer]Specifies that you want the logViewer to continuously monitor the repositoryand output new log record entries as they are created. You can provide an


optional integer argument after this parameter to specify how often you wantthe LogViewer tool to query the repository for new records. By default thelogViewer queries the repository for new records every 5 seconds. When usedwith other filtering options, only those new records that match the filtercriteria are displayed.

-helpUse this parameter to have the LogViewer tool list the full set of options thatare available.

-startDate date_timeYou can filter the results that are displayed from the repository by date andtime. Use the startDate parameter to filter out log entries that occurred afterthe date or date time provided as an argument. Provide either a date or dateand time, entered in the MM/dd/yy format or the MM/dd/yy H:m:s:S:zformat, where z represents timezone.

-stopDate date_timeUse this parameter to filter out log entries that occurred before the specifieddate or date time. Provide the argument in the same format as the -startDateoption.

-level level_nameSpecifies that you want the tool to only display those log events which matchthe level name you provide as an argument. Valid values for the level nameare FINEST, FINER, FINE, DETAIL, CONFIG, INFO, AUDIT, WARNING,SEVERE, FATAL.

-minLevel level_nameSpecifies that you want the tool to only display records which are at or abovethe specified level. Valid values for the level name are FINEST, FINER, FINE,DETAIL, CONFIG, INFO, AUDIT, WARNING, SEVERE, FATAL.

-maxLevel level_nameSpecifies that you want the tool to only display records that are at or below thespecified level. Valid values for the level name are FINEST, FINER, FINE,DETAIL, CONFIG, INFO, AUDIT, WARNING, SEVERE, FATAL.

-includeLoggers logger_nameWhen this option is used, only log events from the specified loggers areincluded in the LogViewer output. Separate multiple entries with a comma.The * symbol can be used as a wild card to include all loggers below a parentlogger. When used in combination with the -excludedLoggers option, the morespecific match determines if the log event is included or excluded.

-excludeLoggers logger_nameUse this option to exclude log events from the specified loggers in theLogViewer output. Separate multiple entries with a comma. The * symbol canbe used as a wildcard to include all loggers below a parent logger. When usedin combination with the -includeLoggers option, the more specific matchdetermines if the log event is included or excluded.

-thread thread_idUse this option to restrict LogViewer output to only those log events from aspecific thread. Any log messages that were not created by the thread IDprovided as an argument to this option are not displayed. Specify the threadID in hex format.

-extractToNewRepository directory_nameThis option redirects log and trace records from a binary repository to a newbinary repository at the location that you specify. You can use this option with


other filtering options to get a subset of log and trace records into the newrepository. This option uses the directory path where the new repository mustbe written as an argument. Therefore, the directory must be empty. If thedirectory does not exist, the directory is created. However, errors that occurduring the directory creation might create extraneous directories.

-listInstancesUse this option to list the IDs of available server process instances that areavailable to use with the -instance option. After running LogViewer with the-listInstances option, you can then use the -instance option to invokeLogViewer with one of the server process instance IDs as an argument. Sincethis option does not process any log or trace records, all other options areignored when you specify this option.

-instance instance_idUse this option to retrieve the log and trace data for a given server processinstance by providing the server instance ID. Run LogViewer, along with the-listInstances option, before you use this option to obtain a valid instance ID.This option is required when viewing logs and trace from an environment thatcontains subprocesses, such as the z/OS® operating system.

If this option is combined with -latestInstance, -instance is ignored.

-latestInstanceUse this option to retrieve the log and trace data from the most recent serverinstance. If this option is used with the -instance option, the -instance option isignored.

-message match_stringUse this option to retrieve only log or trace data with a message field thatmatches the requested text.

-includeExtensions name[=value][,name[=value]]*Use this option to retrieve the log and trace data with an extension name thatmatches the requested name, and an extension value that matches therequested value. You can also use this option to retrieve the log and trace datawith an extension name that matches the requested name, and an extensionvalue that matches any value, if you omit the =value part of the option.

Any extension name shown in the advanced format can be used. Note that'source', 'class', and 'method' are not stored in the log/trace repositories asextensions, and so cannot be filtered on with this option.

Separate multiple name=value arguments with a comma. Specify '==' (twoequals signs) in place of '=' (one equals sign) in cases where the name or valuemust contain an equal sign. Specify ',,' (two commas) in place of ',' (onecomma) in cases where the name or value must contain a comma.

-encoding character_setSpecifies the character set that the LogViewer command will use for textoutput.

Filtering considerations

Be aware of LogViewer filtering optimizations. The LogViewer tool is able to filterlog and trace data most efficiently when used with the following filter options:v startDatev stopDatev thread


v levelv minLevelv maxLevel

Example usage

See the following examples of LogViewer commands used with full profile serverson UNIX-based systems. The examples show how to run LogViewer from theprofile bin directory where the repositoryDir parameter is not required.v Write all records in the default repository between July 19th, 2009 and August

2nd, 2009 to a file called /tmp/promo.logs.logViewer.sh -outLog /tmp/promo.logs -startDate 07/19/2009 -stopDate 08/02/2009

v Display new records whose specified level is WARNING or higher using theadvanced format as the server writes them to the log repository.

logViewer.sh -monitor -minLevel WARNING -format advanced

v Write only those log messages that were written to the error stream of a specificrepository to a file called logged_errors.txt.

logViewer.sh -repositoryDir /apps/server1/logs -includeLoggers SystemErr -outLog logged_errors.txt

v View events from the default repository that occurred before September 14th,2009 4:28 PM eastern daylight time.

logViewer.sh -stopDate "09/14/2009 16:28:00:000 EDT"

v Write events from the default repository that contain a 'thread' extension withvalue 'WebContainer : 6'

logViewer.sh -includeExtensions thread="WebContainer : 6" -format advanced

v Write events from the default repository that were a part of the request withrequestID a856cb2c-79ed-4d62-a3cf-a9908b2db07b.

logViewer.sh -includeExtensions requestID=a856cb2c-79ed-4d62-a3cf-a9908b2db07b

v Write events from the default repository that were created on a thread servicingthe PlantsByWebSphere application.

logViewer.sh -includeExtensions appName=PlantsByWebSphere

MongoDB databases

MongoDB (from “humongous”) is a scalable, high-performance, open sourceNoSQL database. The Liberty profile provides configuration support for MongoDBJava driver Version 2.10.0 or later.

The Liberty profile provides a mongo-2.0 feature that you can use to configureMongoDB instances and associated database connections for your applications.Access to MongoDB connections is available either by Java Naming and DirectoryInterface (JNDI) lookup or resource injection, as with other product resources. Allactual database manipulation is performed by the native com.mongodb API.

The MongoDB server and client MongoDB driver are not available with theproduct. You must download, install, and configure the MongoDB database serversand client drivers.


Chapter 3. End-to-end paths for the Liberty profile

Start here for step-by-step guidance in working with the WebSphere ApplicationServer Liberty profile. Identify the scenario that most closely matches your ownproject goal, then follow one of the paths through the scenario to reach your goal.

Procedure

“Enabling JMS messaging for the Liberty profile.”v “Enabling JMS messaging for a single Liberty profile server.”v “Enabling JMS messaging between two Liberty profile servers” on page 62.

Enabling JMS messaging for the Liberty profile

You use the jmsMessaging and jmsServer Liberty features to enable the JavaMessage Service (JMS) on a single server. To enable JMS messaging between twoservers, you also add the jmsComms feature. To make the jmsServer feature work ina secure mode, you add the jmsSecurity feature. To also use SSL when passingmessages between two servers, you add the ssl feature.

Procedurev “Enabling JMS messaging for a single Liberty profile server”v “Enabling JMS messaging between two Liberty profile servers” on page 62

Enabling JMS messaging for a single Liberty profile server

You can configure the wasJMSClient-1.1 and wasJMSServer-1.0 Liberty features inthe same server. In this scenario, the application is deployed on the same serverwhere the Messaging Engine and the JMS resources exist. You can also configurethe wasJMSSecurity-1.0 feature to make the wasJMSServer-1.0 feature work in asecure mode.

Procedurev Configure the sending and receiving of messages to and from a queue.

1. Configure the Messaging Engine to create a Queue called Queue1.<queue id="QUEUE1"

forceReliability="ReliablePersistent"exceptionDestination="SEND_TO_EXCEPTION_DESTINATION"redeliveryInterval="60"maxRedeliveryCount="20"sendAllowed="true"receiveAllowed="true"maintainStrictOrder="true"maxQueueDepth="5000">

</queue>

2. Declare a QueueConnectionFactory Resource to create a connection to theMessaging Engine.


<jmsQueueConnectionFactory jndiName="eis/queuecf" connectionManagerRef="ConMgr2"><properties.jms.QueueConnectionFactory

userName="user1"clientID="clientId"nonPersistentMapping="ExpressNonPersistent"password="password"persistentMapping="ReliablePersistent"readAhead="Default"temporaryQueueNamePrefix="tempor" />

</jmsQueueConnectionFactory><connectionManager id="ConMgr2" maxPoolSize="2"/>

3. Declare a Queue Resource to create a Producer/Consumer session to theQueue Queue1.<jmsQueue jndiName="eis/queue1">

<properties.jms.Queue queueName="QUEUE1"deliveryMode="Application"timeToLive="500000"priority="1"readAhead="AsConnection" />

</jmsQueue>

v Configure publish and subscribe messaging from a Topicspace.1. Configure the Messaging Engine to create a Topicspace called TopicSpace1.

<topicSpace id="TopicSpace1"forceReliability="ReliablePersistent"exceptionDestination="SEND_TO_EXCEPTION_DESTINATION"redeliveryInterval="60"maxRedeliveryCount="20"sendAllowed="true"receiveAllowed="true"maintainStrictOrder="true"maxQueueDepth="5000">

</topicSpace>

2. Declare a TopicConnectionFactory Resource to create a connection to theMessaging Engine.<jmsTopicConnectionFactory jndiName="eis/topiccf" connectionManagerRef="ConMgr1">

<properties.jms.TopicConnectionFactory userName="user1"clientID="clientId"nonPersistentMapping="ExpressNonPersistent"password="password"persistentMapping="ReliablePersistent"readAhead="Default"temporaryQueueNamePrefix="tempor" />

</jmsTopicConnectionFactory><connectionManager id="ConMgr1" maxPoolSize="2"/>

3. Declare a Topicspace Resource to create a Publisher/Subscriber session to theTopicSpace TopicSpace1.<jmsQueue jndiName="eis/queue1">

<properties.jms.Queue queueName="QUEUE1"deliveryMode="Application"timeToLive="500000"priority="1"readAhead="AsConnection" />

</jmsQueue>

v Optional: Make the jmsServer feature work in a secure mode.

Enabling secure JMS messaging for the Liberty profile

The JMSSecurity-1.0 Liberty feature makes the jmsServer-1.0 feature work in asecure mode.

Before you begin

The JMSSecurity-1.0 feature is always used with the jmsServer-1.0 feature.

Configuring the user registry is a prerequisite for the jmsSecurity-1.0 feature.Ensure that a user registry is configured before the jmsSecurity-1.0 feature isenabled.


About this task

The wasJMSSecurity-1.0 feature supports secure connections to the messagingengine. When the wasJMSSecurity-1.0 feature is enabled, it starts authenticatingand authorizing the users who are trying to connect to the messaging engine. Theuser is authenticated against the registry that is defined in the server.xml file.When the user wants to access a destination such as a topic or a queue for aparticular role, the user must have the access to that destination. The access to thedestination is defined in the <messagingSecurity> element in the server.xml file. Ifthe wasJMSSecurity-1.0 feature is added and the <messagingSecurity> element ismissing in the server.xml file, then the users can neither connect to the messagingengine nor perform any messaging action (for example, sending or receivingmessages from the destinations).

When you enable the jmsSecurity-1.0 feature, you must also configure the<messagingSecurity> element in the server.xml file. This enables authorized usersto access messaging destinations.

Procedure1. Configure a user registry.

Three types of registries are supported in the Liberty profile:v QuickStartSecurity (which supports only one User)v Basic user registry (which is part of the product, supports multiple Users,

and allows you to declare groups)v LDAP Registries (which are external to the product. Examples include the

Microsoft Active Directory, and the IBM Directory Server).

See “Configuring a user registry for the Liberty profile” on page 459.Here is a sample configuration for the basic user registry:<basicRegistry id="basic" realm="customRealm">

<user name="user1" password="user1pwd" /><user name="user2" password="user2pwd" /><user name="user3" password="user3pwd" /><user name="user4" password="user4pwd" /><user name="user5" password="user5pwd" /><user name="user6" password="user6pwd" /><user name="user7" password="user7pwd" /><user name="user8" password="user8pwd" /><group name="Developers">

<member name="user2" /><member name="user4" />

</group><group name="Testers">


</group></basicRegistry>

2. Configure the MessagingSecurity tag to restrict users from accessing thedestinations.By default, none of the users have any permission on any of the destinationsthat are defined in the Messaging Engine. When you configure theMessagingSecurity tag, you assign permission based on what the administratorhas defined. Regular expressions are supported for the MessagingSecurityPermission tag. Here is a sample configuration:<messagingSecurity>

<role name="developer"><permission name="QUEUE1" actions="SEND,BROWSE"/>

Chapter 3. End-to-end paths for the Liberty profile 61

<permission name="T.*" actions="ALL"/><user name="user1" /><user name="user3" /><group name="Developers" />

</role><role name="tester">

<permission name="QUEUE1" actions="BROWSE"/><permission name="TopicSpace1" actions="RECEIVE"/><user name="user5" /><user name="user6" /><group name="Testers" />

</role></messagingSecurity>

In the previous configuration, user1, user3 and Developers have SEND andBROWSE permission on QUEUE1, and ALL permission on the destinations matchingthe T.* regular expression. Similarly user5, user6 and the Testers group haveBROWSE permission on QUEUE1 and have RECEIVE permission on TopicSpace1.The following example grants user1, user3 and Developers ALL permissions onall the destinations:<messagingSecurity>

<role name="DEFAULT"><permission name=".*" actions="ALL"/><user name="user1" /><user name="user3" /><group name="Developers" />


3. Connect to the Messaging Engine using a authenticated user, and perform anoperation based on the authorization permissions which are declared by theadministrator.

4. Optional: While connecting to the Messaging Engine, specify UserName andPassword in the createConnection call.Here is the syntax:[createConnection(userName, password)]

Enabling JMS messaging between two Liberty profile servers

You can configure the wasJMSClient-1.1 Liberty feature on one server, which actsas client, and configure the wasJMSServer-1.0 feature on a different server. Forinter-server communication to work, you also have to add the JMSComms-1.0feature on the server side. You can also configure the wasJMSSecurity-1.0 featureto make the wasJMSServer-1.0 feature work in a secure mode, and configure thessl-1.0 feature to enable SSL communication between the two servers.

Procedurev Configure the client side.

To enable the wasJMSClient-1.1 feature at the client side, configure the followingtwo properties in the ConnectionFactory:

connectionName="localhost:7276:BootstrapBasicMessaging"This property specifies the server which needs to be contacted, wherethe messaging engine exists. It is declared in the following manner:<hostname>:<port>:<mode>


Where <hostname> is the name of the host where the messaging engine isrunning; <port> is the JMS inbound port which is configured at theserver side in a later step; <mode> is BootstrapBasicMessaging if SSL isnot being used, and BootStrapSecureMessaging if SSL is being used.

targetTransport="CLIENT"This property specifies the behaviour of the Client when it tries toconnect to the messaging engine. There are three options:

BINDINGSpecifies that the application should connect to a MessagingEngine which exists locally. If it does not find a MessagingEngine locally, the connection will fail.

CLIENTSpecifies that the application should connect to the MessagingEngine which is declared in the ConnectionName property (aremote Messaging Engine). If it cannot connect to the MessagingEngine, the connection will fail.

BINDING_THEN_CLIENTIn this mode, the application first tries to connect to a MessagingEngine which exists locally. If it does not find a MessagingEngine locally, the application looks up the ConnectionName thentries to connect to the remote Messaging Engine.

Note: If a value for targetTransport is not specified, then theBINDING_THEN_CLIENT option is used by default.

The Client is deployed in this server.v Configure the server side.

1. Enable the JMSComms-1.0 feature in the server.xml file. This in turn enablesthe wasJMSServer-1.0 feature.

2. Define the JMS connection port.Use the following tag: <jmsCommsEndpoint id="InboundJmsCommsEndpoint"host="*" jmsPort="7276" jmsSSLPort="7286" />

This tag defines an Inbound JMS Comms Endpoint, to which the JMS Clientapplications can connect by using the jmsPort if SSL is not being used, andby using the jmsSSLPort if SSL is being used. The port number is the onethat you specified in the connectionName property on the Client side.

The Messaging Engine runs in this server.v Optional: Make the jmsServer feature work in a secure mode.v Optional: Enable SSL communication between the two servers.

See “Securing communications with the Liberty profile” on page 65.

Enabling secure JMS messaging for the Liberty profile

The JMSSecurity-1.0 Liberty feature makes the jmsServer-1.0 feature work in asecure mode.

Before you begin

The JMSSecurity-1.0 feature is always used with the jmsServer-1.0 feature.


Configuring the user registry is a prerequisite for the jmsSecurity-1.0 feature.Ensure that a user registry is configured before the jmsSecurity-1.0 feature isenabled.

About this task

The wasJMSSecurity-1.0 feature supports secure connections to the messagingengine. When the wasJMSSecurity-1.0 feature is enabled, it starts authenticatingand authorizing the users who are trying to connect to the messaging engine. Theuser is authenticated against the registry that is defined in the server.xml file.When the user wants to access a destination such as a topic or a queue for aparticular role, the user must have the access to that destination. The access to thedestination is defined in the <messagingSecurity> element in the server.xml file. Ifthe wasJMSSecurity-1.0 feature is added and the <messagingSecurity> element ismissing in the server.xml file, then the users can neither connect to the messagingengine nor perform any messaging action (for example, sending or receivingmessages from the destinations).

When you enable the jmsSecurity-1.0 feature, you must also configure the<messagingSecurity> element in the server.xml file. This enables authorized usersto access messaging destinations.

Procedure1. Configure a user registry.

Three types of registries are supported in the Liberty profile:v QuickStartSecurity (which supports only one User)v Basic user registry (which is part of the product, supports multiple Users,

and allows you to declare groups)v LDAP Registries (which are external to the product. Examples include the

Microsoft Active Directory, and the IBM Directory Server).

See “Configuring a user registry for the Liberty profile” on page 459.Here is a sample configuration for the basic user registry:<basicRegistry id="basic" realm="customRealm">

<user name="user1" password="user1pwd" /><user name="user2" password="user2pwd" /><user name="user3" password="user3pwd" /><user name="user4" password="user4pwd" /><user name="user5" password="user5pwd" /><user name="user6" password="user6pwd" /><user name="user7" password="user7pwd" /><user name="user8" password="user8pwd" /><group name="Developers">


</group><group name="Testers">



2. Configure the MessagingSecurity tag to restrict users from accessing thedestinations.By default, none of the users have any permission on any of the destinationsthat are defined in the Messaging Engine. When you configure theMessagingSecurity tag, you assign permission based on what the administrator


has defined. Regular expressions are supported for the MessagingSecurityPermission tag. Here is a sample configuration:<messagingSecurity>

<role name="developer"><permission name="QUEUE1" actions="SEND,BROWSE"/><permission name="T.*" actions="ALL"/><user name="user1" /><user name="user3" /><group name="Developers" />

</role><role name="tester">

<permission name="QUEUE1" actions="BROWSE"/><permission name="TopicSpace1" actions="RECEIVE"/><user name="user5" /><user name="user6" /><group name="Testers" />


In the previous configuration, user1, user3 and Developers have SEND andBROWSE permission on QUEUE1, and ALL permission on the destinations matchingthe T.* regular expression. Similarly user5, user6 and the Testers group haveBROWSE permission on QUEUE1 and have RECEIVE permission on TopicSpace1.The following example grants user1, user3 and Developers ALL permissions onall the destinations:<messagingSecurity>

<role name="DEFAULT"><permission name=".*" actions="ALL"/><user name="user1" /><user name="user3" /><group name="Developers" />


3. Connect to the Messaging Engine using a authenticated user, and perform anoperation based on the authorization permissions which are declared by theadministrator.

4. Optional: While connecting to the Messaging Engine, specify UserName andPassword in the createConnection call.Here is the syntax:[createConnection(userName, password)]

Securing communications with the Liberty profileYou can configure the Liberty profile server to provide secure communicationsbetween a client and the server.

About this task

To configure secure communications, you can either specify a minimal SSLconfiguration or a detailed SSL configuration in the server.xml file. The minimalconfiguration only requires the SSL feature and a keystore entry to be specified. Inthe ${wlp.install.dir}/templates/config directory of the Liberty profile, there isan sslConfig.xml file that contains several examples of SSL configurations.

The SSL configuration that is designated as thedefault SSL configuration is used to create the process's default SSLContext usingthe SSLContext.setDefault() method. The default SSL configuration can be theminimal SSL configuration, or the configuration identified by the sslRef attributeon the sslDefault element if multiple SSL configurations are defined. Because the


default SSLContext is set on the process, the javax.net.ssl.keyStore andjavax.net.ssl.trustStore properties will not be recognized.

Procedurev Enable SSL communications between a client and a Liberty profile serverv Optional: Create a keystore from the command promptv Optional: Encode passwords from the command promptv Optional: Configure client certificate authentication between your application

and the Liberty profile server


Chapter 4. Migrating applications to the Liberty profile

This section provides information about how to migrate applications to the Libertyprofile.

Procedure

Migrate data access applications to the Liberty profile.

Migrating data access applications to the Liberty profileFor data access applications, you need to change configurations when you migratea data source from the WebSphere Application Server full profile to the Libertyprofile.

Procedurev “Configuration differences between the full profile and Liberty profile:

dataSource and jdbcDriver elements.”v “Configuration differences between the full profile and Liberty profile:

connectionManager element” on page 68.v “Migrating a DB2 data source to the Liberty profile” on page 69.v “Migrating a Derby embedded data source to the Liberty profile” on page 71.

Configuration differences between the full profile and Libertyprofile: dataSource and jdbcDriver elements

This page identifies some differences in configuration between dataSource in theLiberty profile and data sources in the full profile.v Data source properties with different names

– ifxIFX_LOCK_MODE_WAIT, which is informixLockModeWait in the full profile.– supplementalJDBCTrace, which is supplementalTrace in the full profile.

v Data source properties with different values– beginTranForResultSetScrollingAPIs, which is true by default in the Liberty

profile– beginTranForVendorAPIs, which is true by default in the Liberty profile– connectionSharing, which is MatchOriginalRequest by default in the Liberty

profile– statementCacheSize, which is 10 by default in the Liberty profile

v connectionSharing property of data sources– The Liberty profile allows connectionSharing to be configured to either

MatchOriginalRequest or MatchCurrentState. By default, it isMatchOriginalRequest.

– The full profile allows connectionSharing to be configured in a finer grainedmanner, where individual connection properties can be matched based on theoriginal connection request or the current state of the connection. In the fullprofile, connectionSharing is a combination of bits representing whichconnection properties to match based on the current state of the connection.In the full profile, a value of 0 means to match all properties based on theoriginal connection request; a value of -1 means to match all properties based


on the current state of the connection. The default value for the full profile is1, which means that the isolation level is matched based on the current stateof the connection and all other properties are matched based on the originalconnection request.

v Time duration properties of data sourceTime duration properties can optionally be specified with units in the Libertyprofile. For example,<dataSource id="informix" jndiName="jdbc/informix" queryTimeout="5m" ...>

<properties.informix ifxIFX_LOCK_MODE_WAIT="120s" .../></dataSource>

See “Liberty profile: Configuration elements in the server.xml file” on page 97for accepted time units and formats of dataSource element. Omitting the units inthe Liberty profile is equivalent to the default units used in the full profile.

v Configuration for JDBC drivers– In the Liberty profile, you can take the same approach of configuring different

jdbcDriver elements for XA capable and non-XA capable data sourceimplementation classes. Alternatively, you can use a single jdbcDriverelement for both. Defining multiple jdbcDriver elements does not causedifferent class loaders to be used. In the Liberty profile, jdbcDriver elementsalways use the class loader of the shared library with which they areconfigured.

– In the full profile, a JDBC provider is defined to point to the JDBC driverJARs, compressed files, and native files. You must define separate JDBCproviders for XA capable and non-XA capable data source implementationclasses.

For some of the commonly used JDBC drivers, the Liberty profile infers the datasource implementation class names based on the names the driver JARs.Therefore, you can omit the implementation class names. For example:<jdbcDriver id="Derby" libraryRef="DerbyLib"/><library id="DerbyLib">

<fileset dir="C:/Drivers/derby" includes="derby.jar" /></library>

Use the optional properties of the default implementation classes to overridethese classes such as javax.sql.DataSource,javax.sql.ConnectionPoolDataSource, and javax.sql.XADataSource.The following example shows how to override the defaultjavax.sql.XADataSource and javax.sql.ConnectionPoolDataSourceimplementations that the Liberty profile selects<jdbcDriver id="Derby" libraryRef="DerbyLib"

javax.sql.XADataSource="org.apache.derby.jdbc.EmbeddedXADataSource"javax.sql.ConnectionPoolDataSource="org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource"/>

<library id="DerbyLib"><fileset dir="C:/Drivers/derby" includes="derby.jar" />

</library>

See “Liberty profile: Configuration elements in the server.xml file” on page 97for more information about the jdbcDriver element.

Configuration differences between the full profile and Libertyprofile: connectionManager element

This page identifies some differences in configuration between connectionManagerin the Liberty profile and connection pools in the full profile.v Properties with different names

– maxConnectionsPerThread, which is maxNumberofMCsAllowableInThread in thefull profile.


– maxIdleTime, which is unusedTimeout in the full profile.– maxPoolSize, which is maxConnections in the full profile.– minPoolSize, which is minConnections in the full profile.

v Time duration propertiesYou can optionally specify the time duration properties with units in the Libertyprofile. For example,<connectionManager id="pool1" connectionTimeout="30s" reapTime="3m" maxIdleTime="30m"/>

See “Liberty profile: Configuration elements in the server.xml file” on page 97for accepted time units and formats for the connectionManager element. If youdo not specify time units in the Liberty profile, the same default units are usedas in the full profile.

v Differences between immediate timeout values and never (disable) timeoutThere are differences in the values that represent immediate timeout and never(disabled) timeout.– The Liberty profile uses a value of 0 to represent immediate, whereas the full

profile often uses -1 for immediate.– The Liberty profile uses a value of -1 to represent never (disabled), whereas

the full profile often uses 0 for never (disabled).

Specifically this applies to the following attributes:– agedTimeout

– connectionTimeout

– maxIdleTime, which is unusedTimeout in the full profile– reapTime

v Purge policy changesIn the Liberty profile , there are three purge policy values: EntirePool,FailingConnectionOnly, and ValidateAllConnections.In the full profile, there are two purge policy values: EntirePool andFailingConnectionOnly, with a second property,defaultPretestOptimizationOverride, determining the behavior ofFailingConnectionOnly.Purge policies in the Liberty profile, and their full profile equivalents, are asfollows:– purgePolicy="EntirePool", which is the same for both.– purgePolicy="FailingConnectionOnly", which is equivalent to

purgePolicy="FailingConnectionOnly" withdefaultPretestOptimizationOverride="false" in the full profile.

– purgePolicy="ValidateAllConnections", which is equivalent topurgePolicy="FailingConnectionOnly" withdefaultPretestOptimizationOverride="true" in the full profile.

Migrating a DB2 data source to the Liberty profileYou can migrate a DB2® data source to the Liberty profile.

About this task

See the following code examples for the configurations for a DB2 data source inthe full profile and Liberty profile.

Chapter 4. Migrating applications to the Liberty profile 69

Example

In the full profile:<resources.jdbc:JDBCProvider xmi:id="JDBCProvider_1321914412932"

providerType="DB2 Using IBM JCC Driver" isolatedClassLoader="false"implementationClassName="com.ibm.db2.jcc.DB2ConnectionPoolDataSource" xa="false">

<classpath>${DB2_JCC_DRIVER_PATH}/db2jcc4.jar</classpath><classpath>${DB2_JCC_DRIVER_PATH}/db2jcc_license_cu.jar</classpath><classpath>${DB2_JCC_DRIVER_PATH}/db2jcc_license_cisuz.jar</classpath><factories xmi:type="resources.jdbc:DataSource" xmi:id="DataSource_1321914498985"

name="DefaultDB2Datasource" jndiName="jdbc/DefaultDB2Datasource"providerType="DB2 Using IBM JCC Driver" authMechanismPreference="BASIC_PASSWORD"authDataAlias="IBM-9NE5C7ONIG4Node01/dbuser2" relationalResourceAdapter="builtin_rra"statementCacheSize="10"datasourceHelperClassname="com.ibm.websphere.rsadapter.DB2UniversalDataStoreHelper">

<propertySet xmi:id="J2EEResourcePropertySet_1321914499000"><resourceProperties xmi:id="J2EEResourceProperty_1321914499000" name="databaseName"

type="java.lang.String" value="TESTDB" required="true" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499001" name="driverType"type="java.lang.Integer" value="4" required="true" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499002" name="serverName"type="java.lang.String" value="localhost" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499003" name="portNumber"type="java.lang.Integer" value="50000" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499010" name="currentLockTimeout"type="java.lang.Integer" value="10" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499013" name="currentSchema"type="java.lang.String" value="DBUSER2" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499015" name="cursorSensitivity"type="java.lang.Integer" value="0" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499016" name="deferPrepares"type="java.lang.Boolean" value="true" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499027" name="loginTimeout"type="java.lang.Integer" value="0" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499032"name="resultSetHoldability" type="java.lang.Integer" value="1" required="false"ignore="false" confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499034"name="retrieveMessagesFromServerOnGetMessage"type="java.lang.Boolean" value="true" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499041" name="traceLevel"type="java.lang.Integer" value="-1" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499052"name="beginTranForResultSetScrollingAPIs" type="java.lang.Boolean" value="false"required="false" ignore="false" confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499053"name="beginTranForVendorAPIs" type="java.lang.Boolean" value="false" required="false"ignore="false" confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499054" name="connectionSharing"type="java.lang.Integer" value="-1" required="false" ignore="false"confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499060"name="nonTransactionalDataSource" type="java.lang.Boolean" value="false"required="false" ignore="false" confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499063"name="syncQueryTimeoutWithTransactionTimeout" type="java.lang.Boolean" value="false"required="false" ignore="false" confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499069"name="webSphereDefaultIsolationLevel" type="java.lang.Integer" value="2"required="false" ignore="false" confidential="false" supportsDynamicUpdates="false"/>

<resourceProperties xmi:id="J2EEResourceProperty_1321914499070"name="webSphereDefaultQueryTimeout" type="java.lang.Integer" value="10"required="false" ignore="false" confidential="false" supportsDynamicUpdates="false"/>

</propertySet><connectionPool xmi:id="ConnectionPool_1321914499012" connectionTimeout="180"

maxConnections="10" minConnections="1" reapTime="180" unusedTimeout="1800"agedTimeout="7200" purgePolicy="EntirePool" />


<mapping xmi:id="MappingModule_1321914681786" mappingConfigAlias=""authDataAlias="IBM-9NE5C7ONIG4Node01/dbuser2"/>

</factories></resources.jdbc:JDBCProvider><systemLoginConfig xmi:id="JAASConfiguration_2">

<authDataEntries xmi:id="auth1" alias="IBM-9NE5C7ONIG4Node01/dbuser2"userId="dbuser2" password="{xor}LDcfLTo7Oz0=" />

</systemLoginConfig>

In the Liberty profile, the equivalent configuration is:<variable name="DB2_JCC_DRIVER_PATH" value="C:/Drivers/DB2" /><library id="db2Lib">

<fileset dir="${DB2_JCC_DRIVER_PATH}" includes="db2jcc4.jardb2jcc_license_cu.jar db2jcc_license_cisuz.jar" />

</library><dataSource id="DefaultDB2Datasource" jndiName="jdbc/DefaultDB2Datasource"

statementCacheSize="10"beginTranForResultSetScrollingAPIs="false"beginTranForVendorAPIs="false"connectionSharing="MatchCurrentState"transactional="false"syncQueryTimeoutWithTransactionTimeout="false"isolationLevel="TRANSACTION_READ_COMMITTED"queryTimeout="10"><jdbcDriver libraryRef="db2Lib"

javax.sql.ConnectionPoolDataSource="com.ibm.db2.jcc.DB2ConnectionPoolDataSource"/><properties.db2.jccdatabaseName="TESTDB"driverType="4"serverName="localhost"portNumber="50000"currentLockTimeout="10"currentSchema="DBUSER2"cursorSensitivity="0"deferPrepares="true"loginTimeout="0"resultSetHoldability="1"retrieveMessagesFromServerOnGetMessage="true"traceLevel="-1"user="dbuser2"password="{xor}LDcfLTo7Oz0="/><connectionManager connectionTimeout="180" maxPoolSize="10" minPoolSize="1" reapTime="180"

maxIdleTime="1800" agedTimeout="7200" purgePolicy="EntirePool"/></dataSource>

Migrating a Derby embedded data source to the Liberty profileYou can migrate a Derby Embedded data source to the Liberty profile.

About this task

See the following code examples for the configurations for a Derby Embedded datasource in the full profile and Liberty profile.

Example

In the full profile:<resources.jdbc:JDBCProvider xmi:id="JDBCProvider_1183122153343"

providerType="Derby JDBC Provider"implementationClassName="org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource"xa="false">

<classpath>${DERBY_JDBC_DRIVER_PATH}/derby.jar</classpath><factories xmi:type="resources.jdbc:DataSource" xmi:id="DataSource_1183122153625"

name="DefaultDerbyDatasource" jndiName="jdbc/DefaultDatasource"providerType="Derby JDBC Provider" authMechanismPreference="BASIC_PASSWORD"relationalResourceAdapter="builtin_rra" statementCacheSize="10"datasourceHelperClassname="com.ibm.websphere.rsadapter.DerbyDataStoreHelper">

<propertySet xmi:id="J2EEResourcePropertySet_1183122153625"><resourceProperties xmi:id="J2EEResourceProperty_1183122153625" name="databaseName"type="java.lang.String" value="C:/myDerby/DefaultDB" required="true"/><resourceProperties xmi:id="J2EEResourceProperty_1183122153626" name="shutdownDatabase"

Chapter 4. Migrating applications to the Liberty profile 71

type="java.lang.String" value="false" required="false"/><resourceProperties xmi:id="J2EEResourceProperty_1183122153629" name="connectionAttributes"type="java.lang.String" value="upgrade=true" required="false"/><resourceProperties xmi:id="J2EEResourceProperty_1183122153630" name="createDatabase"type="java.lang.String" value="create" required="false"/>

</propertySet><connectionPool xmi:id="ConnectionPool_1183122153625" connectionTimeout="180"

maxConnections="10" minConnections="1" reapTime="180" unusedTimeout="1800"agedTimeout="7200" purgePolicy="EntirePool"/>

</factories></resources.jdbc:JDBCProvider>

In the Liberty profile, the equivalent configuration is:<variable name="DERBY_JDBC_DRIVER_PATH" value="C:/Drivers/derby" /><library id="derbyLib">

<fileset dir="${DERBY_JDBC_DRIVER_PATH}" includes="derby.jar" /></library><dataSource id="DefaultDerbyDatasource" jndiName="jdbc/DefaultDerbyDatasource"

statementCacheSize="10"><jdbcDriver libraryRef="derbyLib"

javax.sql.ConnectionPoolDataSource="org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource"/><properties.derby.embedded

databaseName="C:/myDerby/DefaultDB"shutdownDatabase="false"connectionAttributes="upgrade=true"createDatabase="create"

/><connectionManager connectionTimeout="180" maxPoolSize="10" minPoolSize="1" reapTime="180"

maxIdleTime="1800" agedTimeout="7200" purgePolicy="EntirePool" /></dataSource>


Chapter 5. Installing the Liberty profile

You install the Liberty profile by using the WebSphere Application ServerDeveloper Tools for Eclipse, or by extracting an archive file. If you install theprofile by using an archive file, you must apply service by using a fix pack archivefile.


About this task

To try out the Liberty profile, and use the Liberty profile to develop applicationsthat run on the WebSphere Application Server Liberty profile or full profile, youcan download the no-charge developer edition from the WASdev communitydownload page. This edition runs on distributed platforms including IBM i, and onthe Mac.

To use the Liberty profile in a production environment with guaranteed servicelevels and IBM support, you must purchase WebSphere Application Server (base),WebSphere Application Server Network Deployment or WebSphere ApplicationServer Express®. The Liberty profile is included with these editions, and can alsobe downloaded separately, as an edition-specific archive file, from PassportAdvantage® online. The associated service is available from Fix Central.

For Windows, Linux, and Mac OS, you can also install the WebSphere ApplicationServer Developer Tools for Eclipse, then use the tools to install the profile.

Procedure

vDistributed operating systems “Installing the Liberty profile developer tools and

(optionally) the Liberty profile.”

vDistributed operating systems “Installing the Liberty profile by extracting an archive

file” on page 83.

Installing the Liberty profile developer tools and (optionally) theLiberty profile


You can install WebSphere Application Server Developer Tools for Eclipse into anexisting Eclipse workbench. You can install the application-serving environmentseparately, or you can use the tools to install the environment for you. You mightalso want to install Maven Integration for Eclipse.

Before you begin

You can install the Liberty profile application-serving environment as described inthis topic, or as described in “Installing the Liberty profile by extracting an archivefile” on page 83.


https://www.ibm.com/developerworks/mydeveloperworks/blogs/wasdev/entry/download


http://www-01.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm


http://www-933.ibm.com/support/fixcentral/

To install the Liberty profile developer tools, you require thefollowing system components:v Eclipse IDE for Java EE Developers 4.2.2 RC1 (Juno SR2-RC1).v Java runtime environment (JRE).

See “System requirements for WebSphere Application ServerDeveloper Tools for Eclipse” on page 80.

About this task

You can install the developer tools by using any of the following methods:v Find and install the remote installation files from your Eclipse workbench.v Drag an Install icon from the Eclipse Marketplace or WASdev Community web

page to your workbench.v Install from downloaded installation files.

After you have installed the developer tools, you can use them with any edition ofthe Liberty profile for Windows, Linux, and Mac OS. If you have not yet installedthe Liberty profile, the tools can install it for you.

To learn more about WebSphere Application Server Developer Tools for Eclipse,see IBM WebSphere Application Server Developer Tools for Eclipse overview.

Procedure1. Install the developer tools.

Use one of the following methods:v Install the developer tools from a remote repository.v Install the developer tools from downloaded installation files.

2. Optional: Use the developer tools to install the Liberty profile.When you create a new server using the tools, you specify the installation ofthe Liberty profile that you want to use. You are offered three options:v Select an existing installation.v Install from a previously downloaded archive file.v For the no-charge developer edition, Download and install.

See “Creating a Liberty profile server by using developer tools” on page 93.3. Optional: Install Maven Integration for Eclipse.

Installing the developer tools from a remote repositoryDistributed operating systems

You can install WebSphere Application Server Developer Tools for Eclipse into anexisting Eclipse workbench from a repository such as Eclipse Marketplace orWASdev.

Before you begin

To install the Liberty profile developer tools, you require the following systemcomponents:v Eclipse IDE for Java EE Developers 4.2.2 RC1 (Juno SR2-RC1).


v Java runtime environment (JRE).

See “System requirements for WebSphere Application Server Developer Tools forEclipse” on page 80.

About this task

You can install the WebSphere Application Server Developer Tools for Eclipse frominstallation files located in a remote repository by either using your Eclipseworkbench to find the installation files, or by finding a link to the installation fileson a web page.

Procedure1. Start your Eclipse IDE for Java EE Developers workbench.2. Start the installation using either of the following methods.

v Locate the installation files from your Eclipse workbench:a. Click Help > Eclipse Marketplace.b. In the Find field, type WebSphere.c. In the list of results, locate IBM WebSphere Application Server version

Developer Tools V8.5 and then click Install. The Confirm SelectedFeatures page opens.

v Drag an Install icon from a web page to your Eclipse workbench:a. Open your web browser to http://marketplace.eclipse.org/ or

https://www.ibm.com/developerworks/mydeveloperworks/blogs/wasdev/entry/download.

b. Select the release that you want to download.

c. Locate the Install icon ( ) for IBM WebSphere ApplicationServer version Developer Tools.

d. Select and drag the Install icon to your Eclipse workbench, and drop iton the Eclipse toolbar. The Confirm Selected Features page opens.

3. On the Confirm Selected Features page, expand the parent nodes and select thefeatures that you want to install. When you are finished, click Next.

4. On the Review Licenses page, review the license text. If you agree to the terms,click I accept the terms of the license agreement and then click Finish. Theinstallation process starts.

Note: During the installation, a Security Warning dialog box might open anddisplay the following message:Warning: You are installing software that contains unsigned content.The authenticity or validity of this software cannot be established.Do you want to continue with the installation?

You can safely ignore the message and click OK to continue.5. When the installation process completes, restart the workbench.

What to do next

Configure the installation.

Chapter 5. Installing the Liberty profile 75

http://marketplace.eclipse.org/



Installing the developer tools from downloaded installationfiles


You can install WebSphere Application Server Developer Tools for Eclipse into anexisting Eclipse workbench from installation files that you downloaded to yourcomputer. To install the product while you are not connected to the Internet, youmust download additional prerequisite Eclipse files.

Before you begin

To install the Liberty profile developer tools, you require the following systemcomponents:v Eclipse IDE for Java EE Developers 4.2.2 RC1 (Juno SR2-RC1).v Java runtime environment (JRE).

See “System requirements for WebSphere Application Server Developer Tools forEclipse” on page 80.

Important: You must be connected to the Internet during the installation, beforeyou install WebSphere Application Server Developer Tools for Eclipse.

Procedure1. Download the .zip file of IBM WebSphere Application Server Developer Tools

for Eclipse to a directory on your computer.

In a web browser, open WebSphere Application ServerDeveloper Tools for Eclipse V9.0 Beta and click Download.

2. Start your Eclipse IDE for Java EE Developers workbench.3. Click Help > Install new software.4. In the Available Software window, click Add.5. In the Add Repository window, click Archive.6. Browse to the location of the .zip file of IBM WebSphere Application Server

Developer Tools for Eclipse. Select the file and then click Open.7. In the list of results, select IBM WebSphere Application Server Developer

Tools for Eclipse V9.0 Beta. If you do not want to install all features (forexample, you are installing only the WebSphere Application Server V8.5Liberty Profile Tools feature), then expand the IBM WebSphere ApplicationServer Developer Tools for Eclipse V9.0 Beta node and select the featuresthat you want to install.You can install the following features:

Feature Description

Dojo Toolkit (optional) Provides Dojo Toolkit for building Web 2.0applications.

OSGi Application Development Tools Provides tools for developing andmaintaining OSGi-based applications andbundles.

Web Development Tools Develop web applications using the latestweb technologies such as HTML5, CSS3,Dojo Toolkit, Servlet 3.0 and JSP 2.2.


https://www.ibm.com/developerworks/mydeveloperworks/blogs/wasdev/entry/download_wdt_eap

https://www.ibm.com/developerworks/mydeveloperworks/blogs/wasdev/entry/download_wdt_eap

Feature Description

Web Services Development Tools - Liberty Tools for developing and testing JAX-WSWeb services and clients for Liberty.

WebSphere Application Server V8.5 - LibertyProfile

Tools for developing and administeringWebSphere Application Server V8.5 - LibertyProfile.

WebSphere Application Server V8.5 Tools Tools for developing and administeringWebSphere Application Server V8.5.



8. Click Next.9. On the Review Licenses page, review the license text. If you agree to the

terms, click I accept the terms of the license agreement and then click Finish.The installation process starts.

Note: During the installation, a Security Warning dialog box might open anddisplay the following message:Warning: You are installing software that contains unsigned content.The authenticity or validity of this software cannot be established.Do you want to continue with the installation?

You can safely ignore the message and click OK to continue.10. When the installation process completes, restart the workbench.

What to do next

Configure the installation.

Configuring the developer tools installationDistributed operating systems

After you install the WebSphere Application Server Developer Tools for Eclipse,you must complete the required configuration steps. There are also optionalconfiguration steps.

Before you begin

This task assumes that you have already completed one of the following tasks:v “Installing the developer tools from a remote repository” on page 74v “Installing the developer tools from downloaded installation files” on page 76

Attention: These configuration steps require you to modify files. Create a backupcopy of the files before you modify them.

Procedurev Complete the required configuration steps.

1. Stop the workbench.


2. Locate the eclipse.ini file in the <Eclipse installationdirectory>\eclipse directory, where <Eclipse installation directory> is thedirectory where you installed Eclipse.

3. Make a copy of the eclipse.ini file, or back it up.4. Open the eclipse.ini file in a text editor.5. Locate the line -vmargs and add text immediately after it. The text you add

depends on which Java runtime environment (JRE) you are using:– If you are using an IBM 32-bit JRE, then add the following text after the

-vmargs line:-Xms100m-Xmx1024m-Xscmx48m-Xshareclasses:name=IBMSDP_%u-Xquickstart-Xgcpolicy:gencon-Xmnx64m-Dcom.ibm.ws.management.event.max_polling_interval=1000

– If you are using an IBM 64-bit JRE, then add the following text after the-vmargs line:-Xms100m-Xmx1024m-Xscmx48m-Xshareclasses:name=IBMSDP_%u-Xcompressedrefs-Xquickstart-Xgcpolicy:gencon-Xmnx64m-Dcom.ibm.ws.management.event.max_polling_interval=1000

– If you are using an Oracle 32-bit JRE, then add the following text afterthe -vmargs line:-Xms100m-Xmx960m-XX:MaxPermSize=320m-Dcom.ibm.ws.management.event.max_polling_interval=1000

– If you are using an Oracle 64-bit JRE, then add the following text afterthe -vmargs line:-Xms100m-Xmx1024m-XX:MaxPermSize=512m-Xmx1024m-XX:+UseCompressedOops-Dcom.ibm.ws.management.event.max_polling_interval=1000

6. Locate the line --launcher.XXMaxPermSize in the eclipse.ini file and modifythe value:– If you are using an Oracle 32-bit JRE, change the value to 320M:

--launcher.XXMaxPermSize320M

– If you are using an Oracle 64-bit JRE, change the value to 512M:--launcher.XXMaxPermSize512M

7. If you installed any of the WebSphere Application Server Tools features,insert the following text immediately before the line with the text -vmargs:

– Windows For Windows:-vm<WebSphere Application Server V8.5, V8.0 or V7.0 installation directory>\java\jre\bin\javaw.exe

– Linux For Linux:


-vm<WebSphere Application Server V8.5, V8.0 or V7.0 installation directory>/java/jre/bin/java

8. Save and close the eclipse.ini file.9. Restart the workbench.

v Optional: To enhance local server support, complete the following steps:1. Close the workbench.2. Locate and back up the config.ini file in the <Eclipse installation

directory>\eclipse\configuration directory, where <Eclipse installationdirectory> is the directory where you installed Eclipse.

3. Open the config.ini file in a text editor.4. Locate the line eclipse.product=org.eclipse.sdk.ide and replace it with the

following line:eclipse.product=com.ibm.websphere.wdt.product.site.ide

5. Delete the following line:eclipse.application=org.eclipse.ui.ide.workbench

6. Locate the line osgi.splashPath=platform\:/base/plugins/org.eclipse.platform and replace it with the following line:osgi.splashPath=platform\:/base/plugins/com.ibm.websphere.wdt.product.site

7. Save and close the config.ini file.8. Modify the eclipse.ini file:

a. In the <Eclipse installation directory>\eclipse directory, open theeclipse.ini file in a text editor. <Eclipse installation directory> is thedirectory where you installed Eclipse.

b. Delete the following lines:-showsplashorg.eclipse.platform

c. Delete the following lines, if they exist:-productorg.eclipse.epp.package.jee.product

d. Save and close the eclipse.ini file.9. Restart the workbench.

What to do next

If you have not already installed the Liberty profile runtime environment, you canuse the tools to download and install it for you when you create a server for thefirst time. See “Creating a Liberty profile server by using developer tools” on page93.

You might also want to install Maven Integration for Eclipse.

Installing Maven Integration for EclipseYou can install tools for developing Apache Maven projects in the workbench.

Procedure

To install the Maven tools support:1. Start your Eclipse IDE for Java EE Developers workbench.2. Click Help > Install new software.3. In the Available Software window, click Available Software Sites.4. Click Add.


5. In the Add Repository window, click Archive.6. Browse to the location of the .zip file of IBM WebSphere Application Server

Developer Tools for Eclipse. Select the file and then click Open.7. In the Add Repository window, click OK.8. In the Available Software window, clear Group items by category.9. In the filter text field, type maven.

10. Select Maven Tools Support.11. In the Available Software window, click Available Software sites.12. Select http://download.eclipse.org/m2e-wtp/releases/ and then click Enable.13. Click OK.14. Click Next.15. On the Review Licenses page, review the license text. If you agree to the

terms, click I accept the terms of the license agreement and then click Finish.The installation process starts.

16. When the installation process completes, restart the workbench.

System requirements for WebSphere Application ServerDeveloper Tools for Eclipse

Supported platforms

The following tables list the supported platforms for IBM(r) WebSphere(r)Application Server Developer Tools for Eclipse 9.0 Beta:

Table 6. Supported Linux operating systems

Hardware Operating system

Desktop

v x86-32

v x86-64

SUSE (SLED) Desktop 11.x

SUSE (SLED) Desktop 10.x

Ubuntu 12.04 LTS

Red Hat Desktop 5.x

Red Hat Desktop 6.x

Server

v x86-32

v x86-64

Red Hat Enterprise Server 6.x

Red Hat Enterprise Server 5.x

SUSE Enterprise Server 11.x

SUSE Enterprise Server 10.x

Table 7. Supported Microsoft Windows operating systems

Hardware Operating system Editions

v x86-32

v x86-64

Windows 7 v Professional

v Enterprise

v Ultimate


Table 7. Supported Microsoft Windows operating systems (continued)

Hardware Operating system Editions

v x86-32

v x86-64

Windows Vista v Professional

v Enterprise

v Ultimate

v x86-32

v x86-64

Windows Server 2003 v Standard

v Enterprise

v x86-32

v x86-64

Windows Server 2008 v Standard

v Enterprise

Table 8. Supported Mac OS versions

Hardware Operating system

Intel based Mac OS X 10.7 (Lion)

Mountain Lion (10.8)

Table 9. Hosted development environments

Product Version

Citrix Presentation Server 6

Presentation Server 5

Eclipse workbench requirements

You install WebSphere Application Server Developer Tools for Eclipse into anEclipse workbench that is already installed on your computer.

Your Eclipse workbench must be Eclipse IDE for Java EE Developers 4.2.2 RC1(Juno SR2-RC1). for one of the following operating systems:v Windows (32-bit)v Windows (64-bit)v Linux (32-bit)v Linux (64-bit)v OSX (32-bit)v OSX (64-bit)


http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/juno/SR2-RC1/eclipse-jee-juno-SR2-RC1-win32.zip

http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/juno/SR2-RC1/eclipse-jee-juno-SR2-RC1-win64.zip

http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/juno/SR2-RC1/eclipse-jee-juno-SR2-RC1-linux-gtk.tar.gz

http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/juno/SR2-RC1/eclipse-jee-juno-SR2-RC1-linux-gtk-x86_64.tar.gz

http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/juno/SR2-RC1/eclipse-jee-juno-SR2-RC1-macosx-cocoa.tar.gz

http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/juno/SR2-RC1/eclipse-jee-juno-SR2-RC1-macosx-cocoa-x86_64.tar.gz

Runtime environment for Java (JRE) requirements

The required JRE depends on the features that you are installing:

If you are installing any of the WebSphereApplication Server Tools features forversions 8.5, 8.0 or 7.0

If you are NOT installing any of theWebSphere Application Server Toolsfeatures for versions 8.5, 8.0 or 7.0

v IBM Runtime Environment for Windows,Java Technology Edition, Version 6.0 SR9FP1 or later.

v IBM Runtime Environment for Linux, JavaTechnology Edition, Version 6.0 SR9 FP1or later.

v IBM Runtime Environment for Windows,Java Technology Edition, Version 7.0 GAor later.

v IBM Runtime Environment for Linux, JavaTechnology Edition, Version 7.0 GA orlater.

Tip: The IBM Runtime Environment forWindows or Linux, Java Technology EditionVersion 6.0 is included with WebSphereApplication Server version 8.5, 8.0 andversion 7.0. It is located in the followingdirectory <WebSphere Application Serverinstallation directory>/java/jreTip: The IBM Runtime Environment forWindows or Linux, Java Technology EditionVersion 7.0 is optionally installed withWebSphere Application Server version 8.5. Ifinstalled, it is located in the followingdirectory:<WebSphere Application Serverinstallation directory>/java_1.7_32/jre

Any Java 6+ or Java 7+ runtimeenvironment

The following versions work well:

v IBM Runtime Environment for Windowsor Linux, Java Technology Edition, Version7.0 GA OR later.

v IBM Runtime Environment for Windowsor Linux, Java Technology Edition, Version6.0 SR9 FP1 or later.

v Oracle Java Platform Standard EditionRuntime Environment Version 7.0 latestUpdate available.

v Oracle Java Platform Standard EditionRuntime Environment Version 6.0 latestUpdate available.

Tip: IBM Developer Kits and RuntimeEnvironments are available at:http://www.ibm.com/developerworks/java/jdk/

Requirements for installing into Eclipse 3.8.1

Important: If you are installing the product into computer will not be connectedto the Internet during the installation, then you must download and installprerequisite Eclipse files before you install WebSphere Application ServerDeveloper Tools for Eclipse.1. Ensure that you have Eclipse 3.8.1 installed. You can download Eclipse 3.8.1

from the following web address: http://download.eclipse.org/eclipse/downloads/drops/R-3.8.1-201209141540/.

2. Download the following files:v Eclipse Modeling Framework (EMF) 2.8.1v Graphical Editing Framework (GEF) 3.8.1v Eclipse Data Tools Platform (DTP) 1.10.1v EMF Transaction 1.6.0v EMF Validation 1.6.0v Graphitiv Graphical Modeling Framework (GMF) 1.6.1v Web Tools Platform (WTP) 3.4.1


http://www.ibm.com/developerworks/java/jdk/

http://www.ibm.com/developerworks/java/jdk/

http://download.eclipse.org/eclipse/downloads/drops/R-3.8.1-201209141540/

http://download.eclipse.org/eclipse/downloads/drops/R-3.8.1-201209141540/

http://www.eclipse.org/downloads/download.php?file=/modeling/emf/emf/downloads/drops/2.8.1/S201209170436/emf-xsd-SDK-2.8.1RC4.zip

http://www.eclipse.org/downloads/download.php?file=/tools/gef/downloads/drops/3.8.1/S201208200205/GEF-ALL-3.8.1.zip

http://www.eclipse.org/downloads/download.php?file=/datatools/downloads/1.10/dtp-sdk_1.10.1.zip

http://www.eclipse.org/downloads/download.php?file=/modeling/emf/transaction/downloads/drops/1.6.0/R201206271200/emf-transaction-SDK-1.6.0.zip

http://www.eclipse.org/downloads/download.php?file=/modeling/emf/validation/downloads/drops/1.6.0/R201206271200/emf-validation-SDK-1.6.0.zip

http://www.eclipse.org/downloads/download.php?file=/graphiti/archives/0.9.0/org.eclipse.graphiti.site_0.9.0.201206130805.zip

http://www.eclipse.org/downloads/download.php?file=/modeling/gmp/gmf-runtime/downloads/drops/1.6.1/R201209131052/gmf-sdk-runtime-1.6.1.zip

http://www.eclipse.org/downloads/download.php?file=/webtools/downloads/drops/R3.4.1/R-3.4.1-20120917174803/wtp4x-sdk-R-3.4.1-20120917174803.zip

3. For each compressed file that you downloaded in the previous step, extract thecontents of the file into the eclipse directory of your Eclipse 3.8.1 IDE. Ensurethat you preserve the structure of the extracted contents.

Tip: You can overwrite any files that have the same name.For example, if your eclipse directory is located in the file pathC:\eclipse-SDK-3.8.1-win32\ , then you must extract the contents of each fileinto the directory C:\eclipse-SDK-3.8.1-win32\.When you are finished, the extracted files will be in the existing directories ofyour Eclipse IDE:v eclipse (For example, C:\eclipse-SDK-3.8.1-win32\eclipse.)v eclipse\plugins (For example, C:\eclipse-SDK-3.8.1-win32\eclipse\

plugins.)v eclipse\features (For example, C:\eclipse-SDK-3.8.1-win32\eclipse\

features.)4. From a command line, restart your Eclipse IDE using the -clean option. For

example, C:\eclipse-SDK-3.8.1-win32\eclipse\eclipse.exe -clean

Installing the Liberty profile by extracting an archive file


By running a self-extracting archive file that contains the distribution image, youcan install the Liberty profile and you are ready to create a server. For theno-charge developer edition, you can download the archive file from the WASdevcommunity. For all other editions, you can use the archive file that is included witheach edition of WebSphere Application Server, or you can download anedition-specific Liberty profile archive file from Passport Advantage.

Before you begin

You can install the Liberty profile by extracting an archive file as described in thistopic. For distributed platforms, you can also use the WebSphere ApplicationServer Developer Tools for Eclipse to install the profile as described in “Installingthe Liberty profile developer tools and (optionally) the Liberty profile” on page 73.

This topic assumes that your system meets the operating system and Javarequirements for using the Liberty profile. See System Requirements for WebSphereApplication Server v8.5 - Liberty.

Procedure1. Get a copy of the distribution image:

v For the no-charge developer edition (with no IBM support), you candownload the archive file from the WASdev community download page.

v For all other editions, you can use the archive file that is included with eachedition of WebSphere Application Server.

v You can also download an edition-specific Liberty profile archive file,including the developer edition with IBM support, from Passport Advantageonline.

2. Extract the distribution image to your preferred directory.This image is packaged as an archive file called wlp-edition-version.jar. Forexample:


http://www.ibm.com/support/docview.wss?rs=180&uid=swg27028175

http://www.ibm.com/support/docview.wss?rs=180&uid=swg27028175




v To extract the distribution image by using the wizard, run java -jarwlp-edition-version.jar

v To extract the distribution image by accepting the license terms andconditions silently, run java -jar wlp-edition-version.jar --acceptLicense

v To view all available options, run java -jar wlp-edition-version.jar -help

All the application server files are stored in subdirectories of the wlp directory.3. Optional: Set the JAVA_HOME property for your environment.

The Liberty profile requires a JRE in which to run. You can specify the JDK orJRE location using the JAVA_HOME property in the server.env file, as describedin “Customizing the Liberty profile environment” on page 352. On Linux orUNIX systems, you can instead set JAVA_HOME in the user .bashrc file, orappend the JDK or JRE path to the PATH environment variable. On Windowssystems, you can instead set JAVA_HOME as a system environment variable, orappend the JDK or JRE path to the PATH system variable.

Distributed operating systems For example, on Windows systems you can use thefollowing commands to set the JAVA_HOME property, and to add the Java /bindirectory to the path:set JAVA_HOME=C:\Progra~1\Java\JDK16set PATH=%JAVA_HOME%\bin;%PATH%

Notes:

v The Liberty profile runtime environment searches for the java command inthis order: JAVA_HOME property, JRE_HOME property, and system PATH property.

v For more information about supported Java environments, and where to getthem, see “Minimum supported Java levels” on page 566.

Applying a fix pack to a Liberty profile archive installation


The Liberty profile offers a self-extracting archive-based installation as analternative to using IBM Installation Manager. If you installed the Liberty profileby using the self-extracting archive, and want to upgrade to the latest fix packversion, you can apply a new fix pack archive to a new location, and migrate anyrequired user files and server configuration data.

About this task

If you used IBM Installation Manager to install the Liberty profile, you must useInstallation Manager to apply a fix pack.

Important: You must apply a new fix pack archive to a new location. If you installa fix pack to a previous installation location, you cannot back out the fix pack fromthe previous installation location.

Procedure1. Install the new runtime environment.

a. Optional: If you are overwriting your current installation, stop all serversthat are running on the system. This minimizes the risk of incompatiblebehaviors occurring prior to the server being restarted.v <liberty_VX>/bin/server stop <server_name>


If you are installing to a new location, you are not required to stop allservers.

b. Copy or download the new fix pack archive onto the target system.c. Launch the archive by using a Java command. You must use a Java

command because the archive is an executable JAR file. For example, toinstall WebSphere Application Server V8.5.0.1 Liberty Profile for Developers,run the following command:v java -jar <downloaded_archive_location>/wlp-developers-8.5.0.1.jar

For more information about using a Java command to launch an archive,see the instructions in “Installing the Liberty profile by extracting an archivefile” on page 83.

d. Review the license terms, and accept them to continue with the installation.e. Select the installation location. To retain a backup of your original

environment, use a different location to where the previous version isinstalled. If the same location is used, you cannot uninstall the fix pack andreturn to your previous version.

2. Migrate any user data and server configurations. The Liberty profile definestwo locations for storing user-generated content and server configurations:v WLP_USER_DIR; The location of server configuration files, including shared

resources.v WLP_OUTPUT_DIR; The location of resources generated by the server. For

example, log files and temporary disk storage.If the WLP_USER_DIR environment variable has been set on your system, then thenew runtime environment will continue to use the same location. This resultsin no backup of server configuration data. To ensure that your serverconfiguration is backed up, copy the directory referenced by WLP_USER_DIR to anew location on your file system. To protect the original environment, changethe value of WLP_USER_DIR to point to the new location. During uninstallation,reset the value of WLP_USER_DIR to the location of the original serverconfiguration.If WLP_USER_DIR has not been set, the server configuration and shared resourcesare stored in the usr directory at the root of the server's runtime environment(for example, <liberty_8501>/usr). During uninstallation of the runtimeenvironment, you can reset the WLP_USER_DIR environment variable.If the WLP_OUTPUT_DIR environment variable is set on your system, the newserver also uses this location. This can result in old log files being overwritten.To ensure that old log files are protected, either update or unset theWLP_OUTPUT_DIR environment variable. During uninstallation, reset this value toits original value.If the WLP_OUTPUT_DIR value is not set, the default location is in the server rootdirectory (for example <liberty_8501>/usr/servers/<serverName>). If the newruntime environment is installed to a new location, no updates are requiredduring installation or uninstallation because logs continue to appear under theusr/servers/<serverName>/logs directory of each respective installation.

Note: If the server.xml file, or any included XML configuration file, referencesanother resource outside the server configuration directory, these resourcesmust also be copied across, or the references will need to be updated. This alsoapplies to any resources that the application references directly, such asreferences to hardcoded paths on file systems. During uninstallation of the fixpack, these values can be manually reset to their original values.

3. Start the new server.


v If you overwrote a previous installation, start all Liberty profile servers withthe --clean parameter as a launch option. For example, server start--clean. You have to use the --clean option only once; all subsequent serverstarts will not require it.

v If you did not overwrite a previous installation, run <liberty_VX+>/bin/server start <server_name>.

Removing a fix pack from a Liberty profile archive installationDistributed operating systems

If you installed the Liberty profile by using the self-extracting archive, you canuninstall a fix pack from the Liberty profile runtime environment in a givenlocation by migrating any user data and server configurations to the previousLiberty profile runtime environment in a different location, and deleting the fixpack runtime environment.

Procedure1. Stop all servers running on the system.

v <liberty_VX>/bin/server stop <server_name>

2. Migrate any user data and server configurations. For more information see theMigrate any user data and server configurations step in the installation task.

3. Delete the fix pack runtime environment.4. Start the servers.

v <liberty_VX->/bin/server start <server_name>

Applying an interim fix to a Liberty profile archive installation


The Liberty profile offers a self-extracting archive-based installation as analternative to using IBM Installation Manager. If you installed the Liberty profileusing the self-extracting archive, and want to install an interim fix, you can applyan executable JAR file.

About this task

If you used IBM Installation Manager to install the Liberty profile, you must useInstallation Manager to apply an interim fix.

An interim fix is named <Liberty profile level>-WS-WASProd_WLPArchive-<fixtype><fix id>.jar

v <Liberty profile level> refers to a 4-digit fix pack level identifier, which indicatesthe minimum level to which the fix applies. For example, 8.5.0.0.

v <fix type> refers to the type of fix. For example, IF is used for an interim fix, andTF for a diagnostic fix

v <fix id> refers the APAR reference number. If a diagnostic fix is provided beforean APAR is opened, the <fix id> is based on the PMR reference number.

Each interim fix is installed by executing the relevant JAR file, which extracts thecontent into the Liberty profile base folder (/wlp).


Note: When the interim fix is applied, no backup data is created. If you want toback out an interim fix, you must manually remove or restore files from the /wlpfolder.

Each interim fix is provided with a readme.txt file, which contains backup andrestore instructions specific to the fix content, in a section titled Directions toapply fix. If the readme.txt file does not specify any requirement to back up files,you can extract the fix and then restart the server at any time with the --cleanparameter as a launch option.

Procedure1. Optional: If the fix contains files that will overwrite existing files, stop all

servers running on the system.2. Optional: If the readme.txt file indicates that a backup is required, create a

backup of the lib/features/component.mf files. File locations are relative toyour Liberty profile install root.

3. Open a console and direct it to the location of your interim fix JAR file.4. To view available options, run java -jar interim_fix_jar_file -help, where

interim_fix_jar_file is the name of the executable JAR file containing the interimfix. The following launch options are available for the JAR file:

--installLocationThe absolute or relative location of the Liberty profile install directory.

By default the JAR file looks for a wlp directory in its current location.If your Liberty profile install location is not the wlp folder, or is not inthe same directory as the JAR file, then you can use this option tochange where the JAR file will patch. [LibertyRootDir] can either berelative to the location of the JAR file, or an absolute file path.

--suppressInfoThe only messages output from the JAR file will be error messages orconfirmation that patching has completed.

5. Select the install location.6. Start all Liberty profile servers with the --clean parameter as a launch option.

For example, server start --clean. You have to use the --clean option onlyonce; all subsequent server starts will not require it.

Removing an interim fix from a Liberty profile archive installDistributed operating systems

If you installed the Liberty profile by using the self-extracting archive, then toremove an interim fix you must manually remove files, and restore files, from the/wlp folder.

About this task

If you used IBM Installation Manager to apply an interim fix, you can useInstallation Manager to remove the interim fix.

The current set of fixes installed on a Liberty profile can be found in the/lib/fixes directory.

Each interim fix is provided with a readme.txt file, which contains backup andrestore instructions specific to the fix content, in a section titled Directions to


apply fix. If the readme.txt file does not include any requirement to back up files,you can extract the fix and then restart the server at any time with the --cleanparameter as a launch option.

Procedure1. Stop all servers running on the system. For more information, see Starting and

stopping a server.2. Delete or replace the files as detailed in the readme.txt file. File locations are

relative to your Liberty profile install root. For example:v lib/com.ibm.ws.component_1.0.0.20120803-1356.jar

v lib/fixes/8.5.0.0-WS-WASProd_WLPArchive-IFPM11111_8.5.0.20120803-1356.xml

3. Start all Liberty profile servers with the --clean parameter as a launch option.For example, server start --clean. You only need to use the --clean optiononce. All subsequent server starts will not require it.

What to do next

You can reapply the fix by following the instructions in “Applying an interim fix toa Liberty profile archive installation” on page 86.


Chapter 6. Setting up the Liberty profile

Define directory locations and variables, create and configure servers, and add andremove Liberty features that specify the capabilities of your server.

Procedurev Defining directory locations and properties.

v “Verifying the integrity of Liberty profileinstallation” on page 91.

vDistributed operating systems “Creating a Liberty profile server by using developer

tools” on page 93.v “Creating a Liberty profile server manually” on page 95.v “Specifying Liberty profile bootstrap properties” on page 95.

The default HTTP port is 9080 and HTTPS port is 9443 for the Liberty profile.You can manually assign appropriate port numbers in the server.xml files whenmultiple Liberty profile servers are running on the same machine.

Liberty profile: Directory locations and propertiesIn the Liberty profile, many directories have properties associated with them.These properties can be used to specify file locations when you configure theserver.

Table 10. Runtime environment default directory structure. Column 1 contains a file anddirectory tree. If a directory has a property associated with it, this is given in column 2. Adescription of each file or directory is given in Column 3.

Directory or file Property Description

wlp/ wlp.install.dir Root of installation

+- bin/ Scripts for managing the server:server; ws-launch.jar

+- clients/ Client applications. For examplerestConnector.jar.

+- jython/ Jython-based scripts

+- dev/ APIs available at compile timeor run time

+- ibm-api/ Public APIs available for bothcompile and run time by default

+- javadoc/ Java document archives

+- spec/ Public specification APIsavailable for both compile andrun time by default

+- third-party/ Third-party APIs that areavailable at compile time bydefault and must be specified inthe configuration using theapiTypeVisibility attribute ofthe classloader element forapplications at run time.


Table 10. Runtime environment default directory structure (continued). Column 1 contains afile and directory tree. If a directory has a property associated with it, this is given in column2. A description of each file or directory is given in Column 3.


+- tools/ Ant plug-in for the Libertyprofile

+- etc/ User customized server variablesthat apply to all servers(optional)

+- server.env Default server scriptenvironment variables (optional)

+- jvm.options Default jvm options (optional)

+- lafiles/ License information files

+- lib/ Platform runtime environment

+- templates/ Runtime customizationtemplates and examples

+- config/ Configuration examples forsecurity

+- server/ Server template when creating aserver

+- usr/ wlp.user.dir User directory

+- shared/

+- apps/ shared.app.dir Shared applications

+- config/ shared.config.dir Shared configuration files

+- resources/ shared.resource.dir Shared resource definitions:adapters, data sources

+- servers/ Shared servers directory

+- server_name server.config.dir Server configuration directory.Use ${server.config.dir} toreference server-specificconfiguration (applications).

+-bootstrap.properties

Server bootstrap properties(optional)

+- jvm.options Server JVM options, whichreplace the values inwlp/etc/jvm.options (optional)

+- server.env Server script environmentvariables, which are mergedwith wlp/etc/server.env(optional)

+- server.xml Server configuration overlays(required)

+- apps/ Server configuration forapplications

+- dropins/ Server default applicationdropins folder (optional)

+-application_name

Application folder or archive(optional)


Table 10. Runtime environment default directory structure (continued). Column 1 contains afile and directory tree. If a directory has a property associated with it, this is given in column2. A description of each file or directory is given in Column 3.


+- server_name server.output.dir Server output directory. Use${server.output.dir} todescribe artifacts generated bythe server (log files andworkarea).

+- logs/ Server log files, including FFDClogs (directory is present afterserver is first run)

+- console.log Basic server status andoperations messages

+-trace_timestamp.log

Time-stamped trace messages,with the level of detaildetermined by the currenttracing configuration

+- ffdc/ First Failure Data Capture(FFDC) output directory

+-ffdc_timestamp/

First Failure Data Capture(FFDC) output that typicallyincludes selective memorydumps of diagnostic data relatedto the failure of a requestedoperation

+- workarea/ Files created by the server as itoperates (directory is presentafter server is first run)

You can use the properties associated with each directory, if any, to specify filelocations when you configure the server.

Tip: To ensure configuration portability, use the most specific property that isappropriate, and do not rely on the relationship between resources. For example, insome configurations the installation location, ${wlp.install.dir} might not be theparent of the customized instance ${wlp.user.dir}.

Verifying the integrity of Liberty profile installation

You can use the command utilities to verify the installation integrity of the Libertyprofile.

About this task

After you have installed the Liberty profile, you must make sure that theinstallation is completed successfully and that all required features or iFixes areinstalled. The productInfo command provides different options to complete thefollowing tasks:v Compare the differences between APAR fixes and the current installation.v Validate the MD5 checksum file for server installation and each feature.

Chapter 6. Setting up the Liberty profile 91

v Verify the version information of the current installation.v Verify the feature list on the current installation.

Liberty profile: productInfo command

The productInfo command supports validating the product integrity, comparingdifferent versions of the Liberty profile servers, and verifying the current productversions.

Syntax

The command syntax is as follows:productInfo action --[options]

where the possible values of the options vary depending on the value of theactionparameter.

Parameters

The following action parameters and options values are available for theproductInfo command:

compareAllows you to compare APAR fixes that are installed in the currentinstallation with a different version of Liberty profile.

--target="path to directory or archive file"Specifies the target file with which to compare the currentinstallation. The value of --target can be either a directory or anarchive file that must be a valid Liberty profile installation location.This option is required if --apars is not specified.

--apars="a comma separated list of APAR IDs"Checks the current installation against this comma separated list ofAPAR IDs to see if it contains them, and then lists any APARs thatare not included. This option is required if --target is notspecified.

--output="path to an output file"Outputs the result from this command to the supplied file name.By default, the output is directed to standard output.

--verboseDisplay detailed error messages when an error occurs.

Note: At least one of --target or --apars must be supplied

featureInfoLists all the features that are installed on the current Liberty profile server.


validateValidates the Liberty profile server against its checksum file.


--checksumfile="path to the checksum file"Specifies the file that contains the checksum information of *.mfand *.blst being installed. The default value islib/versions/productChecksums.cs. You can also validate theintegrity of an installed feature on the Liberty profile.


versionPrints the product information such as the product name, edition, version,and iFix information.

--output=filenameOutputs the result from this command to the supplied file name.By default, the output is directed to standard output.

--verboseDisplay the whole content of each properties file.

help Prints help information for the specific action.

Usage

The following examples demonstrate correct syntax:productInfo compare --target=C:\wlp\newInstall\wlpproductInfo compare --target=C:\wlp\newInstall.jar --output=C:\wlp\compareOutput.txtproductInfo compare --apars=com.ibm.ws.apar.PM39074,com.ibm.ws.apar.PM39075,com.ibm.ws.apar.PM39080productInfo featureInfo --output=c:\wlp\featureListOutput.txtproductInfo validate --checksumfile=c:\wlp\libs\versions\checksums\appSecurity-2.0-mf.csproductInfo help compare

Creating a Liberty profile server by using developer tools


You can use developer tools to create and start a Liberty profile server. If you havenot yet installed the Liberty profile, the developer tools can install it for you thefirst time you create a server.

Before you begin

Make sure you have installed the developer tools as described in “Installing theLiberty profile developer tools and (optionally) the Liberty profile” on page 73.

You can create a server as described in this topic, or as described in “Creating aLiberty profile server manually” on page 95.

When you create a new server using the tools, you specify the installation of theLiberty profile that you want to use. You are offered three options:v Select an existing installation.v Install from a previously downloaded archive file.v For the no-charge developer edition, Download and install.

If you want to use the tools to install a Liberty edition (other than the no-chargedeveloper edition) from an archive file, make sure you have downloaded thearchive file.


Procedure1. In the workbench, open the Servers view by clicking the Servers tab.2. Right-click the Servers view and select New > Server.3. Under the server type list, expand IBM and select the WebSphere Application

Server V8.5 Liberty Profile server type.4. Click Next. The Liberty Profile Runtime Environment page is displayed.5. Select an installation, install from an archive file, or (for the no-charge

developer edition) download and install, the Liberty profile.If you have previously installed the Liberty profile, complete the followingsteps:a. In the Installation folder section of the Liberty Profile Runtime

Environment page, browse for the directory where you installed the Libertyprofile runtime environment, then click OK.

b. Click Next. The application-serving environment is selected.If you want to install the Liberty profile from an archive file that you havepreviously downloaded, complete the following steps:a. In the Installation folder section of the Liberty Profile Runtime

Environment page, click Download or install.a. In the Install Runtime Environment page, select Install a new runtime

environment from an archive.b. Type or browse for the archive where you downloaded the Liberty profile

runtime environment, then click Next.c. In the License Acceptance page, if you accept the license terms, select I

accept the terms of the license agreement then click Next.d. Under the Target installation folder, type or browse for the directory to

which you want the workbench to extract the archive, then click Finish.e. In the Liberty Profile Runtime Environment page, click Next.If you want to download and install the no-charge developer edition of theLiberty profile, complete the following steps:a. In the Installation folder section of the Liberty Profile Runtime

Environment page, click Download or install.b. In the Install Runtime Environment page, select Download and install a

new runtime environment from:, choose a download site, then click Next.If the developer edition distribution image (a JAR file) is available on yourlocal file system, choose Local download. Otherwise, choose the WASdevcommunity download page.

c. In the License Acceptance page, if you accept the license terms, select Iaccept the terms of the license agreement then click Next.

d. In the Installation Folder page, specify the target installation folder, thenclick Finish. The Liberty profile is downloaded and installed to your chosenfolder.

e. In the Liberty Profile Runtime Environment page, click Next.6. In the Liberty Profile Server page, click New.7. Enter a server name of your choice, then click OK.8. In the Liberty Profile Server page, click Finish.

What to do nextv Edit the server configuration. For more details see topic “Editing the Liberty

profile configuration by using developer tools” in the “Administering” book.




v Start the server in “start” mode or in “debug” mode, stop the server, add orremove applications on the server, and many other tasks. You can perform thesetasks by using the server context menu (right-click on the server to open thepop-up menu) or by selecting the tray buttons in the Servers view.

Tip: In the Servers view, you must select the server entry to perform these tasks.Do not select the server configuration, such as the Server Configuration[server.xml] entry for performing these tasks.

Creating a Liberty profile server manuallyYou can create a server from the command prompt.


Before you begin

Distributed operating systems You can create a server as described in this topic, or asdescribed in “Creating a Liberty profile server by using developer tools” on page93.

Procedure1. Open a command prompt, then change directory to the wlp/bin directory.2. Run the following command to create a server. If you do not specify a server

name, defaultServer is used.

v Windows Linux

server create server_name

Results

A server is created if the specified server does not already exist. If the specifiedserver already exists, an exception message is generated and no server is created.The TCP/IP ports for the new server are not automatically assigned. You canspecify those ports by “Specifying Liberty profile bootstrap properties” other thanusing the default ones.

What to do next

Configure your server to have the features that your application requires. See“Configuring the Liberty profile runtime environment ” in the “Administering”book.

Specifying Liberty profile bootstrap propertiesBootstrap properties initialize the runtime environment for a particular server.Generally, they are attributes that affect the configuration and initialization of theruntime core.

About this task

Bootstrap properties are set in a text file named bootstrap.properties. This fileshould be in the server directory with the configuration root file server.xml. By


default, the server directory is usr/servers/server_name. You can change theserver directory as described in “Customizing the Liberty profile environment” onpage 352.

The bootstrap.properties file contains two types of properties:v A small, predefined set of initialization properties.v Any custom properties that you choose to define. You can then use these custom

properties as variables in other configuration files such as server.xml andincluded files.

Distributed operating systems You can edit the bootstrap.properties file using a texteditor or the editor in the WebSphere Application Server Developer Tools forEclipse. See “Editing the Liberty profile configuration by using developer tools” onpage 344.

If you update the bootstrap.properties file, you must restart the server with the--clean option for the changes to take effect.

Procedurev Use predefined properties to configure trace and logging.

For example, change the name of your trace file by specifying the propertycom.ibm.ws.logging.trace.file.name in the bootstrap.properties file:com.ibm.ws.logging.trace.file.name = trace.log

v Use custom properties to define the default ports for web applications.You can share server.xml and use XML configuration files across variousdevelopment environments that allow machine- or environment-specificcustomization. For example:1. Specify the properties default.http.port and default.https.port in the

bootstrap.properties file:default.http.port = 9081default.https.port = 9444

Note: If you do not specify the properties, the default HTTP port is 9080 andHTTPS ports is 9443. To override the default HTTP endpoint definition, setthe id attribute of the httpEndpoint element to defaultHttpEndpoint in theserver configuration.

2. Use these properties in the server.xml configuration file:<httpEndpoint id="defaultHttpEndpoint"host="*"httpPort="${default.http.port}"httpsPort="${default.https.port}" />

Note: host="*" means “listen on all adapters”. By default, the server islistening only on address 127.0.0.1/localhost. You can also use the hostproperty to specify a single IP address, and then the system listens only onthe specified adapter.

v To apply the changes, restart the server.


Chapter 7. Administering the Liberty profile

A server configuration consists of a server.xml file, a bootstrap.properties file,and any optional files that are included by the two main configuration files. Thereis no administrative console for the Liberty profile. Administrators and developersuse the WebSphere Application Server Developer Tools for Eclipse, or a text editor,to edit the configuration files.

About this task

The Liberty profile is configured by exception. The runtime environment operatesfrom a set of built-in configuration default settings, and you only need to specifyconfiguration that overrides those default settings. You do this by editing either theserver.xml file or another XML file that is included in server.xml at run time.

Features are the units of functionality by which you control the pieces of theruntime environment that are loaded into a particular server. They are the primarymechanism that makes the server composable. The list of features that you specifyin the server configuration provides a functional server.

When you first install and start the server, a feature manager and a default serverconfiguration are available:v By default, a server contains the jsp-2.2 feature, to support servlet and JSP

applications. You can use the feature manager to add the features that you need.v Server configuration is by exception. When you specify the features that you

need, the default configuration of those features provides a rich environmentthat is designed to cover most common requirements, therefore you only need tospecify changes from the default configuration.

Procedurev “Liberty profile: Configuration elements in the server.xml file”v “Administering the Liberty profile by using developer tools” on page 344v “Administering the Liberty profile manually” on page 351

v Chapter 8, “Extending the Liberty profile,” on page 419

Liberty profile: Configuration elements in the server.xml fileThe application server configuration is described in a series of elements in theserver.xml configuration file. Each element has one or more attributes orsub-elements. This topic contains details of the possible elements, attributes, andsub-elements that can be configured.

List of elements in the server.xml configuration file.

v “activationSpec” on page 101v “activedLdapFilterProperties” on page 101v “administrator-role” on page 102v “application” on page 103v “application-bnd” on page 104v “applicationMonitor” on page 106


v “authCache” on page 107v “authData” on page 108

v “authenticated” on page 109v “authentication” on page 110

v “automaticLibraries” on page 110

v “baseEntry” on page 110v “basicRegistry” on page 111

v “binaryLog” on page 112

v “binaryTrace” on page 114v “bundleRepository” on page 116v “channelfw” on page 116v “classloader” on page 117

v “client” on page 119

v “clientManager” on page 120v “config” on page 121v “connectionManager” on page 123

v “contextService” on page 125v “customLdapFilterProperties” on page 126

v “databaseStore” on page 127v “dataSource” on page 128

v “disk” on page 132v “domino50LdapFilterProperties” on page 134v “edirectoryLdapFilterProperties” on page 135

v “ejbContainer” on page 135v “executor” on page 136v “featureManager” on page 138

v “federatedRepository” on page 139v “fileset” on page 141

v “fileTransfer” on page 142

v “group” on page 143

v “groupDisplayNameMapping” on page 143

v “groupSecurityNameMapping” on page 144

v “hostAuthInfo” on page 145v “httpClassification” on page 147v “httpDispatcher” on page 148v “httpEncoding” on page 149v “httpEndpoint” on page 158v “httpOptions” on page 160v “httpSession” on page 162


v “httpSessionDatabase” on page 167v “idsLdapFilterProperties” on page 172v “include” on page 173v “iplanetLdapFilterProperties” on page 174v “jaasLoginContextEntry” on page 175v “jaasLoginModule” on page 176v “jdbcDriver” on page 178

v “jmsCommsEndpoint” on page 178

v “jmsCommsOutbound” on page 180

v “jmsConnectionFactory” on page 181

v “jmsQueue” on page 181

v “jmsQueueConnectionFactory” on page 181

v “jmsTopic” on page 181

v “jmsTopicConnectionFactory” on page 181v “jndiEntry” on page 181v “jpa” on page 182v “jspEngine” on page 183v “keyStore” on page 185v “ldapRegistry” on page 186v “library” on page 192

v “localStore” on page 194v “logging” on page 195v “ltpa” on page 197

v “managedExecutorService” on page 198

v “managedServer” on page 199

v “member” on page 201

v “messagingEngine” on page 202

v “messagingSecurity” on page 207v “mimeTypes” on page 208

v “mongo” on page 208

v “mongoDB” on page 212v “monitor” on page 213v “nativeTransactionManager” on page 213v “netscapeLdapFilterProperties” on page 214

v “oauthProvider” on page 215

v “oauthRoles” on page 220

v “permission” on page 221v “pluginConfiguration” on page 221v “properties” on page 223

Chapter 7. Administering the Liberty profile 99

v “properties.datadirect.sqlserver” on page 223v “properties.db2.i.native” on page 231v “properties.db2.i.toolbox” on page 238v “properties.db2.jcc” on page 250v “properties.derby.client” on page 262v “properties.derby.embedded” on page 265v “properties.informix” on page 267v “properties.informix.jcc” on page 275

v “properties.jms.ActivationSpec” on page 282

v “properties.jms.ConnectionFactory” on page 284

v “properties.jms.Queue” on page 286

v “properties.jms.QueueConnectionFactory” on page 288

v “properties.jms.Topic” on page 290

v “properties.jms.TopicConnectionFactory” on page 292v “properties.microsoft.sqlserver” on page 294v “properties.oracle” on page 298v “properties.sybase” on page 300v “quickStartSecurity” on page 302

v “realm” on page 302

v “remoteAccess” on page 305

v “role” on page 306v “safAuthorization” on page 307v “safCredentials” on page 308v “safRegistry” on page 308v “safRoleMapper” on page 309v “securewayLdapFilterProperties” on page 309

v “serverCommand” on page 310v “ssl” on page 311v “sslDefault” on page 311v “sslOptions” on page 312

v “supportedEntityType” on page 312

v “syncToOSThread” on page 313v “tcpOptions” on page 313

v “textLog” on page 314v “transaction” on page 316v “trustAssociation” on page 319

v “uniqueGroupIdMapping” on page 321

v “uniqueUserIdMapping” on page 322

v “user” on page 323


v “userDisplayNameMapping” on page 323

v “userSecurityNameMapping” on page 323v “variable” on page 324v “virtualHost” on page 324v “webAppSecurity” on page 325v “webContainer” on page 329

v “wimRegistry” on page 336v “wlmClassification” on page 337

v “wsSecurityClient” on page 337

v “wsSecurityProvider” on page 340

activationSpec

Defines a JMS Activation Specification configuration. PID iscom.ibm.ws.jca.activationSpec.

Attributes

id Description: The unique identifier that represents the activation spec.

Required: true

Data type: string

valueDescription: Must be in the format of <ApplicationName/ModuleName/ComponentName> for example id="JMSSample/JMSSample/SampleMDB"

Required: true

Data type: string

activedLdapFilterPropertiesSpecifies the list of default Microsoft Active Directory LDAP filters. PID iscom.ibm.ws.security.registry.ldap.internal.filters.actived.


Attributes

userFilterDescription: An LDAP filter clause for searching the user registry forusers.

Default value: (&(sAMAccountName=%v)(objectcategory=user))

Required: true

Data type: string

groupFilterDescription: An LDAP filter clause for searching the user registry forgroups.

Default value: (&(cn=%v)(objectcategory=group))

Required: true

Data type: string

userIdMapDescription: An LDAP filter that maps the name of a user to an LDAPentry.

Default value: user:sAMAccountName

Required: true

Data type: string

groupIdMapDescription: An LDAP filter that maps the name of a group to an LDAPentry.

Default value: *:cn

Required: true

Data type: string

groupMemberIdMapDescription: An LDAP filter that identifies user to group memberships.

Default value: memberof:member

Required: true

Data type: string

administrator-roleA collection of users and/or groups assigned the server administrator role. PID iscom.ibm.ws.management.security.role.administrator.


Sub-elements

userDescription: User assigned a role.

Required: false

Data type: string

groupDescription: Group assigned a role.

Required: false

Data type: string

applicationDefines the properties of an application. PID is com.ibm.ws.app.manager.

Attributes

locationDescription: Location of an application expressed as an absolute path ora path relative to the server-level apps directory.

Required: true

Data type: string

nameDescription: Name of an application.

Required: false

Data type: string

typeDescription: Type of application archive.

Default value: ${location:type}

Required: false

Data type: string

context-rootDescription: Context root of an application.

Required: false

Data type: string

autoStartDescription: Indicates whether or not the server should start theapplication automatically when the server starts.

Default value: true

Required: false

Data type: boolean


application-bndBinds general deployment information included in the application to specificresources. PID is com.ibm.ws.javaee.dd.appbnd, and it is the child of complex type“application”.

Attributes

versionDescription: Version of the application bindings specification.

Required: false

Data type: string


Sub-elements

security-roleRequired: false

Data type: A role that is mapped to users and groups in a domain userregistry.

nameDescription: Name of a security role.

Required: true

Data type: string

userRequired: false

Data type: A user possessing a security role.

nameDescription: Name of a user possessing a security role.

Required: true

Data type: string

access-idDescription: A user access ID in the general formuser:realmName/userUniqueId. A value will be generated if oneis not specified.

Required: false

Data type: string

groupRequired: false

Data type: A group possessing a security role.

nameDescription: Name of a group possessing a security role.

Required: true

Data type: string

access-idDescription: Group access ID

Required: false

Data type: string

special-subjectRequired: false

Data type: Name of a special-subject possessing a security role.

typeDescription: One of the following special subject types:ALL_AUTHENTICATED_USERS, EVERYONE.

Range:

EVERYONE


ALL_AUTHENTICATED_USERSAll authenticated users

Required: true

Data type: string

run-asRequired: false

Data type: ID and password of a user required to access a bean fromanother bean.

useridDescription: ID of a user required to access a bean from anotherbean.

Required: true

Data type: string

passwordDescription: Password of a user required to access a bean fromanother bean. The value can be stored in clear text or encodedform. To encode the password, use the securityUtility tool withthe encode option.

Required: false

Data type: password (string)

applicationMonitorDefines how the server responds to application additions, updates, and deletions.PID is com.ibm.ws.app.manager.monitor.


Attributes

pollingRateDescription: Rate at which the server checks for application additions,updates, and deletions. Specify a positive integer followed by a unit oftime, which can be hours (h), minutes (m), seconds (s), or milliseconds(ms). For example, specify 500 milliseconds as 500ms. You can includemultiple values in a single entry. For example, 1s500ms is equivalent to1.5 seconds.

Default value: 500ms

Required: false

Data type: string

dropinsDescription: Location of the application drop-in directory expressed as anabsolute path or a path relative to the server directory.

Default value: dropins

Required: false

Data type: string

dropinsEnabledDescription: Monitor the drop-in directory for application additions,updates, and deletions.

Default value: true

Required: false

Data type: boolean

updateTriggerDescription: Application update method or trigger.

Default value: polled

Range:

polled Server will scan for application changes at the polling intervaland update any applications that have detectable changes.

mbeanServer will only update applications when prompted by anMBean called by an external program such as an integrateddevelopment environment or a management application.

disabledDisables all update monitoring. Application changes will not beapplied while the server is running.

Required: false

Data type: string

authCacheControls the operation of the authentication cache service. PID iscom.ibm.ws.security.authentication.cache.


Attributes

initialSizeDescription: Initial number of entries supported by the authenticationcache.

Default value: 50

Required: false

Data type: int

maxSizeDescription: Maximum number of entries supported by theauthentication cache.

Default value: 25000

Required: false

Data type: int

timeoutDescription: Amount of time after which an entry in the cache will beremoved. Specify a positive integer followed by a unit of time, which canbe hours (h), minutes (m), seconds (s), or milliseconds (ms). For example,specify 500 milliseconds as 500ms. You can include multiple values in asingle entry. For example, 1s500ms is equivalent to 1.5 seconds.

Default value: 600s

Required: false

Data type: string

allowBasicAuthLookupDescription: Allow lookup by user ID and hashed password.

Default value: true

Required: false

Data type: boolean

authDataAuthentication data for connecting to an Enterprise Information System (EIS). PIDis com.ibm.ws.security.jca.internal.authdata.config.


Attributes

userDescription: Name of the user to use when connecting to the EIS.

Required: true

Data type: string

passwordDescription: Password of the user to use when connecting to the EIS. Thevalue can be stored in clear text or encoded form. It is recommended thatyou encode the password. To do so, use the securityUtility tool with theencode option.

Required: true


authenticated

Security role for authorization code and token requests. PID iscom.ibm.ws.security.oauth20.authenticated.role.

Sub-elements

userDescription: User who has the security role.

Required: false

Data type: string

groupDescription: Group that has the security role.

Required: false

Data type: string

specialSubjectDescription: specialsubject.desc

Range:

ALL_AUTHENTICATED_USERSAll authenticated users.

EVERYONEAll users for every request, even if the request was notauthenticated.

Required: false

Data type: string


authenticationControls the built-in authentication service configuration. PID iscom.ibm.ws.security.authentication.

Attributes

cacheEnabledDescription: Enables the authentication cache.

Default value: true

Required: true

Data type: boolean

allowHashtableLoginWithIdOnlyDescription: Allow an application to login with just an identity in thehashtable properties. Use this option only when you have applicationsthat require this and have other means to validate the identity.

Default value: false

Required: false

Data type: boolean

automaticLibraries

Configure automatic libraries. PID iscom.ibm.ws.classloading.sharedlibrary.automatic.

Attributes

monitorEnabledDescription: Monitor the automatic library folder for new or deletedlibraries

Default value: true

Required: false

Data type: boolean

baseEntry

baseEntry.desc. PID is com.ibm.ws.wim.core.baseEntry.


Attributes

nameDescription: The name of a base entry.

Required: true

Data type: string

baseDNDescription: Base distinguished name (DN) in the repository.

Required: false

Data type: string

basicRegistryA simple XML-based user registry. PID is com.ibm.ws.security.registry.basic.config.

Attributes

realmDescription: The realm name represents the user registry.

Default value: BasicRegistry

Required: true

Data type: string


Sub-elements

userRequired: false

Data type: A user in a Basic User Registry.

nameDescription: Name of a user in a Basic User Registry.

Required: true

Data type: string

passwordDescription: Password of a user in a Basic User Registry. The valuecan be stored in clear text or encoded form. It is recommended thatyou encode the password. To do so, use the securityUtility tool withthe encode option.

Required: true


groupRequired: false

Data type: A group in a Basic User Registry.

nameDescription: Name of a group in a Basic User Registry.

Required: true

Data type: string

memberRequired: false

Data type: A member of a Basic User Registry group.

nameDescription: Name of a user in a Basic User Registry group.

Required: true

Data type: string

binaryLog

Use this page to configure High Performance Extensible Logging (HPEL) logoptions. The HPEL log can be viewed using the logViewer command (in the profilebin directory). PID is com.ibm.ws.logging.binaryLog, and it is the child of complextype “logging”.


Attributes

dataDirectoryDescription: Specifies the location on the local file system to store the logrecords.

Inherits: com.ibm.hpel.log.dataDirectory

Default value:

Required: false

Data type: string

purgeMaxSizeDescription: Specifies the maximum size for all log files.

Inherits: com.ibm.hpel.log.purgeMaxSize

Default value: 50

Required: false

Data type: int

purgeMinTimeDescription: Specifies the duration after which a server can remove a logrecord.

Inherits: com.ibm.hpel.log.purgeMinTime

Default value: -1

Required: false

Data type: int

fileSwitchTimeDescription: Specifies whether, in addition to regular switching of thecurrent file, to also start the new file at the defined time of day.

Inherits: com.ibm.hpel.log.fileSwitchTime

Required: false

Data type: int

bufferingEnabledDescription: Specifies whether to allow a small delay in saving records tothe disk for improved performance.

Inherits: com.ibm.hpel.log.bufferingEnabled

Default value: true

Required: false

Data type: boolean

outOfSpaceActionDescription: Specifies the action to perform when the file system whererecords are kept runs out of free space.

Inherits: com.ibm.hpel.log.outOfSpaceAction

Default value: StopLogging

Range:


StopServerStop Server

PurgeOldRemove old records

StopLoggingStop Logging

Required: false

Data type: string

binaryTrace

Use this page to configure High Performance Extensible Logging (HPEL) traceoptions. The HPEL trace can be viewed using the logViewer command (in theprofile bin directory). PID is com.ibm.ws.logging.binaryTrace, and it is the child ofcomplex type “logging”.


Attributes

dataDirectoryDescription: Specifies the directory to store binary trace files. Thislocation is also used for dumping records stored in the HPEL memorybuffer.

Inherits: com.ibm.hpel.trace.dataDirectory

Default value:

Required: false

Data type: string

memoryBufferSizeDescription: Specifies the maximum size of in memory buffer inmegabytes (MB).

Inherits: com.ibm.hpel.trace.memoryBufferSize

Required: false

Data type: int

purgeMaxSizeDescription: Specifies the maximum size for all trace files.

Inherits: com.ibm.hpel.trace.purgeMaxSize

Default value: 50

Required: false

Data type: int


Inherits: com.ibm.hpel.trace.purgeMinTime

Default value: -1

Required: false

Data type: int


Inherits: com.ibm.hpel.trace.fileSwitchTime

Required: false

Data type: int


Inherits: com.ibm.hpel.trace.bufferingEnabled

Default value: true

Required: false


Data type: boolean


Inherits: com.ibm.hpel.trace.outOfSpaceAction


Range:




Required: false

Data type: string

bundleRepositoryEBA bundle repository service. PID is com.ibm.ws.eba.bundle.repository.

Attributes

filesetRefDescription: Space separated list of fileset references

Required: false

Data type: List of configuration IDs of type fileset (comma-separatedstring).

Sub-elements

filesetDescription: Space separated list of fileset references

Required: false

Data type: Element of type fileset.

channelfwDefines channel and chain management settings. PID is com.ibm.ws.channelfw.


Attributes

chainStartRetryIntervalDescription: Time interval between start retries. Specify a positive integerfollowed by a unit of time, which can be hours (h), minutes (m), seconds(s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms.You can include multiple values in a single entry. For example, 1s500ms isequivalent to 1.5 seconds.

Default value: 5s

Required: false

Data type: string

chainStartRetryAttemptsDescription: Number of retry attempts to make per chain.

Default value: 60

Required: false

Data type: int

chainQuiesceTimeoutDescription: Default amount of time to wait while quiescing chains.Specify a positive integer followed by a unit of time, which can be hours(h), minutes (m), seconds (s), or milliseconds (ms). For example, specify500 milliseconds as 500ms. You can include multiple values in a singleentry. For example, 1s500ms is equivalent to 1.5 seconds.

Default value: 30s

Required: false

Data type: string

warningWaitTimeDescription: Amount of time to wait before notifying of a missing factoryconfiguration. Specify a positive integer followed by a unit of time, whichcan be hours (h), minutes (m), seconds (s), or milliseconds (ms). Forexample, specify 500 milliseconds as 500ms. You can include multiplevalues in a single entry. For example, 1s500ms is equivalent to 1.5seconds.

Default value: 10s

Required: false

Data type: string

classloaderClassloader Service. PID is com.ibm.ws.classloading.classloader, and it is the childof complex type “application”.


Attributes

delegationDescription: Controls whether parent classloader is used before or afterthis classloader.

Default value: parentFirst

Range:

parentFirstParent first

parentLastParent last

Required: false

Data type: string

privateLibraryRefDescription: List of library references. Library class instances are uniqueto this classloader, independent of class instances from other classloaders.

Required: false

Data type: List of configuration IDs of type library (comma-separatedstring).

commonLibraryRefDescription: List of library references. Library class instances are sharedwith other classloaders.

Required: false

Data type: List of configuration IDs of type library (comma-separatedstring).

apiTypeVisibilityDescription: The types of API package this class loader will be able tosee, as a comma-separated list of any combination of the following: spec,ibm-api, api, third-party.

Default value: spec,ibm-api,api

Required: false

Data type: string


Sub-elements

privateLibraryDescription: List of library references. Library class instances are uniqueto this classloader, independent of class instances from other classloaders.

Required: false

Data type: Element of type library.

commonLibraryDescription: List of library references. Library class instances are sharedwith other classloaders.

Required: false


client

OAuth client definition. Only clients defined here can access the provider. PID iscom.ibm.ws.security.oauth20.client.


Attributes

nameDescription: Name of the client (sometimes referred to as the Id).

Required: false

Data type: string

secretDescription: Secret key of the client.

Required: false


displaynameDescription: Display name of the client.

Required: false

Data type: string

redirectDescription: URL to redirect the client's requests to.

Required: false

Data type: string

enabledDescription: Client is enabled if true, disabled if false.

Default value: true

Required: false

Data type: boolean

clientManager

Security role for client management requests. PID iscom.ibm.ws.security.oauth20.clientmanager.role.


Sub-elements

userDescription: User who has the security role.

Required: false

Data type: string

groupDescription: Group that has the security role.

Required: false

Data type: string

specialSubjectDescription: Special subject that has the security role.

Range:

ALL_AUTHENTICATED_USERSAll authenticated users.

EVERYONEAll users for every request, even if the request was notauthenticated.

Required: false

Data type: string

configDefines how the server processes configuration information. PID iscom.ibm.ws.config.


Attributes

onErrorDescription: Action to take after incurring a configuration error.

Inherits: onError

Default value: WARN

Range:

WARNServer will issue warning and error messages when it incurs aconfiguration error.

FAIL Server will issue a warning or error message on the first erroroccurrence and then stop the server.

IGNOREServer will not issue any warning and error messages when itincurs a configuration error.

Required: true

Data type: string

monitorIntervalDescription: Rate at which the server checks for configuration updates.Specify a positive integer followed by a unit of time, which can be hours(h), minutes (m), seconds (s), or milliseconds (ms). For example, specify500 milliseconds as 500ms. You can include multiple values in a singleentry. For example, 1s500ms is equivalent to 1.5 seconds.

Default value: 500ms

Required: false

Data type: string

updateTriggerDescription: Configuration update method or trigger.

Default value: polled

Range:

polled Server will scan for changes at the polling interval on all theconfiguration files and update the runtime configuration with thechanges detected.

mbeanServer will only update the configuration when prompted by anMBean called by an external program such as an integrateddevelopment environment or a management application.

disabledDisables all update monitoring. Configuration changes will not beapplied while the server is running.

Required: false

Data type: string


connectionManagerConnection Manager configuration. PID is com.ibm.ws.jca.connectionManager.


Attributes

agedTimeoutDescription: Amount of time before a physical connection can bediscarded by pool maintenance. A value of -1 disables this timeout.Specify a positive integer followed by a unit of time, which can be hours(h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s.You can include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Default value: -1

Required: false

Data type: string

connectionTimeoutDescription: Amount of time after which a connection request times out.A value of -1 disables this timeout. Specify a positive integer followed bya unit of time, which can be hours (h), minutes (m), or seconds (s). Forexample, specify 30 seconds as 30s. You can include multiple values in asingle entry. For example, 1m30s is equivalent to 90 seconds.

Default value: 30s

Required: false

Data type: string

maxIdleTimeDescription: Amount of time after which an unused or idle connectioncan be discarded during pool maintenance, if doing so does not reducethe pool below the minimum size. A value of -1 disables this timeout.Specify a positive integer followed by a unit of time, which can be hours(h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s.You can include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Default value: 30m

Required: false

Data type: string

maxPoolSizeDescription: Maximum number of physical connections for a pool. Avalue of 0 means unlimited.

Default value: 50

Required: false

Data type: int

minPoolSizeDescription: Minimum number of physical connections to maintain in thepool. The pool is not pre-populated. Aged timeout can override theminimum.

Required: false

Data type: int

purgePolicy


Description: Specifies which connections to destroy when a staleconnection is detected in a pool.

Default value: EntirePool

Range:

EntirePoolWhen a stale connection is detected, all connections in the poolare marked stale, and when no longer in use, are closed.

FailingConnectionOnlyWhen a stale connection is detected, only the connection whichwas found to be bad is closed.

ValidateAllConnectionsWhen a stale connection is detected, connections are tested andthose found to be bad are closed.

Required: false

Data type: string

reapTimeDescription: Amount of time between runs of the pool maintenancethread. A value of -1 disables pool maintenance. Specify a positive integerfollowed by a unit of time, which can be hours (h), minutes (m), orseconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Default value: 3m

Required: false

Data type: string

maxConnectionsPerThreadDescription: Limits the number of open connections on each thread.

Required: false

Data type: int

numConnectionsPerThreadLocalDescription: Caches the specified number of connections for each thread.

Required: false

Data type: int

contextService

Configures how context is propagated to threads. PID iscom.ibm.ws.context.service.


Attributes

onErrorDescription: Determines the action to take in response to configurationerrors. For example, if securityContext is configured for thiscontextService, but the security feature is not enabled, then onErrordetermines whether to fail, raise a warning, or ignore the parts of theconfiguration which are incorrect.

Inherits: onError

Default value: WARN

Range:

FAIL Fail when incorrect configuration is encountered.

IGNOREIgnore incorrect configuration.

WARNonError.WARN

Required: true

Data type: string

baseContextRefDescription: Specifies a base context service from which to inherit contextthat is not already defined on this context service.

Required: false

Data type: Configuration ID of type contextService (string).

Sub-elements

baseContextDescription: Specifies a base context service from which to inherit contextthat is not already defined on this context service.

Required: false

Data type: Element of type contextService.

customLdapFilterPropertiesSpecifies the list of default Custom LDAP filters. PID iscom.ibm.ws.security.registry.ldap.internal.filters.custom.


Attributes


Default value: (&(uid=%v)(objectclass=ePerson))

Required: true

Data type: string


Default value:

(&(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))

Required: true

Data type: string


Default value: *:uid

Required: true

Data type: string


Default value: *:cn

Required: true

Data type: string


Default value:

ibm-allGroups:member;ibm-allGroups:uniqueMember;groupOfNames:member;groupOfUniqueNames:uniqueMember

Required: true

Data type: string

databaseStore

Clients are defined and tokens are cached in the database. PID iscom.ibm.ws.security.oauth20.database.store.


Attributes

dataSourceRefDescription: Reference to the data source for the store.

Required: false

Data type: Configuration ID of type dataSource (string).

cleanupExpiredTokenIntervalDescription: Expired token cleanup interval (seconds). The equivalentprovider parameter in the full application server profile isoauthjdbc.CleanupInterval. Specify a positive integer followed by a unitof time, which can be hours (h), minutes (m), or seconds (s). For example,specify 30 seconds as 30s. You can include multiple values in a singleentry. For example, 1m30s is equivalent to 90 seconds.

Default value: 3600

Required: false

Data type: string

userDescription: Database store user

Required: false

Data type: string

passwordDescription: Password used to access the database.

Required: false


Sub-elements

dataSourceDescription: Reference to the data source for the store.

Required: false

Data type: Element of type dataSource.

dataSourceDefines a data source configuration. PID is com.ibm.ws.jdbc.dataSource.


Attributes

jndiNameDescription: JNDI name for a data source.

Required: true

Data type: string

jdbcDriverRefDescription: JDBC driver for a data source.

Required: false

Data type: Configuration ID of type jdbcDriver (string).

connectionManagerRefDescription: Connection manager for a data source.

Required: false

Data type: Configuration ID of type connectionManager (string).

typeDescription: Type of data source.

Range:

javax.sql.XADataSource

javax.sql.ConnectionPoolDataSource

javax.sql.DataSource

Required: false

Data type: string

connectionSharingDescription: Specifies how connections are matched for sharing.

Default value: MatchOriginalRequest

Range:

MatchOriginalRequestWhen sharing connections, match based on the originalconnection request.

MatchCurrentStateWhen sharing connections, match based on the current state ofthe connection.

Required: false

Data type: string

isolationLevelDescription: Default transaction isolation level.

Range:

TRANSACTION_READ_UNCOMMITTEDDirty reads, non-repeatable reads and phantom reads can occur.

TRANSACTION_READ_COMMITTEDDirty reads are prevented; non-repeatable reads and phantom


reads can occur.

TRANSACTION_REPEATABLE_READDirty reads and non-repeatable reads are prevented; phantomreads can occur.

TRANSACTION_SERIALIZABLEDirty reads, non-repeatable reads and phantom reads areprevented.

TRANSACTION_SNAPSHOTSnapshot isolation for Microsoft SQL Server JDBC Driver andDataDirect Connect for JDBC driver.

Required: false

Data type: string

statementCacheSizeDescription: Maximum number of cached statements per connection.

Default value: 10

Required: false

Data type: int

transactionalDescription: Enable participation in transactions that are managed by theapplication server.

Default value: true

Required: false

Data type: boolean

beginTranForResultSetScrollingAPIsDescription: Attempt transaction enlistment when result set scrollinginterfaces are used.

Default value: true

Required: false

Data type: boolean

beginTranForVendorAPIsDescription: Attempt transaction enlistment when vendor interfaces areused.

Default value: true

Required: false

Data type: boolean

commitOrRollbackOnCleanupDescription: Determines how to clean up connections that might be in adatabase unit of work (AutoCommit=false) when the connection is closedor returned to the pool.

Range:

commitClean up the connection by committing.

rollback


Clean up the connection by rolling back.

Required: false

Data type: string

queryTimeoutDescription: Default query timeout for SQL statements. In a JTAtransaction, syncQueryTimeoutWithTransactionTimeout can override thisdefault. Specify a positive integer followed by a unit of time, which canbe hours (h), minutes (m), or seconds (s). For example, specify 30 secondsas 30s. You can include multiple values in a single entry. For example,1m30s is equivalent to 90 seconds.

Required: false

Data type: string

recoveryAuthDataRefDescription: Authentication data for transaction recovery.

Required: false

Data type: Configuration ID of type authData (string).

syncQueryTimeoutWithTransactionTimeoutDescription: Use the time remaining (if any) in a JTA transaction as thedefault query timeout for SQL statements.


Required: false

Data type: boolean

supplementalJDBCTraceDescription: Supplements the JDBC driver trace that is logged whenJDBC driver trace is enabled in bootstrap.properties. JDBC driver tracespecifications include: com.ibm.ws.database.logwriter,com.ibm.ws.db2.logwriter, com.ibm.ws.derby.logwriter,com.ibm.ws.informix.logwriter, com.ibm.ws.oracle.logwriter,com.ibm.ws.sqlserver.logwriter, com.ibm.ws.sybase.logwriter.

Required: false

Data type: boolean


Sub-elements

jdbcDriverDescription: JDBC driver for a data source.

Required: false

Data type: Element of type jdbcDriver.

connectionManagerDescription: Connection manager for a data source.

Required: false

Data type: Element of type connectionManager.

recoveryAuthDataDescription: Authentication data for transaction recovery.

Required: false

Data type: Element of type authData.

disk

Enable disk offload to specify that when the cache is full, cache entries areremoved from the cache and saved to disk. The location is a fully-qualifieddirectory location that is used by the disk offload function. The Flush to Disk onStop option specifies that when the server stops, the contents of the memory cacheare moved to disk. PID is com.ibm.ws.cache.disk, and it is the child of complextype “null”.


Attributes

sizeInEntriesDescription: Specifies a value for the maximum disk cache size, innumber of entries.


Required: false

Data type: int

sizeInGBDescription: Specifies a value for the maximum disk cache size, ingigabytes (GB).

Default value: 3

Required: false

Data type: int

evictionPolicyDescription: Specifies the eviction algorithm and thresholds that the diskcache uses to evict entries.

Default value: RANDOM

Range:

RANDOM

SIZE

Required: false

Data type: string

highThresholdDescription: Specifies when the eviction policy starts.

Default value: 80

Required: false

Data type: int

lowThresholdDescription: Specifies when the eviction policy ends.

Default value: 70

Required: false

Data type: int

locationDescription: Specifies a directory to use for disk offload.

Required: false

Data type: string

flushToDiskOnStopEnabledDescription: Set this value to true to have objects that are cached inmemory saved to disk when the server stops. This value is ignored ifEnable disk offload is set to false.



Required: false

Data type: boolean

domino50LdapFilterPropertiesSpecifies the list of default IBM Lotus® Domino® LDAP filters. PID iscom.ibm.ws.security.registry.ldap.internal.filters.domino50.

Attributes


Default value: (&(uid=%v)(objectclass=Person))

Required: true

Data type: string


Default value: (&(cn=%v)(objectclass=dominoGroup))

Required: true

Data type: string


Default value: person:uid

Required: true

Data type: string


Default value: *:cn

Required: true

Data type: string


Default value: dominoGroup:member

Required: true

Data type: string


edirectoryLdapFilterPropertiesSpecifies the list of Novell eDirectory LDAP filters. PID iscom.ibm.ws.security.registry.ldap.internal.filters.eDirectory.

Attributes


Default value: (&(cn=%v)(objectclass=Person))

Required: true

Data type: string


Default value: (&(cn=%v)(objectclass=groupOfNames))

Required: true

Data type: string


Default value: person:cn

Required: true

Data type: string


Default value: *:cn

Required: true

Data type: string


Default value: groupOfNames:member

Required: true

Data type: string

ejbContainer

Defines the behavior of the EJB container. PID is com.ibm.ws.ejbcontainer.runtime.


Attributes

poolCleanupIntervalDescription: The interval between removing unused bean instances. Thissetting only applies to stateless session and message-driven beans. Specifya positive integer followed by a unit of time, which can be hours (h),minutes (m), or seconds (s). For example, specify 30 seconds as 30s. Youcan include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Default value: 30s

Required: true

Data type: string

cacheSizeDescription: The number of stateful session bean instances that should becached in memory.

Default value: 2053

Required: true

Data type: int

cacheCleanupIntervalDescription: The interval between passivating unused stateful sessionbean instances when the size is exceeded. Specify a positive integerfollowed by a unit of time, which can be hours (h), minutes (m), orseconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Default value: 3s

Required: true

Data type: string

executorDefines threading and execution settings for the server. PID iscom.ibm.ws.threading.


Attributes

nameDescription: Name of the executor for which the thread is performingwork.

Default value: Default Executor

Required: false

Data type: string

maxThreadsDescription: Maximum number of threads that can be associated with theexecutor. If greater than 0, this value must be greater than or equal to thevalue of coreThreads. If the value of maxThreads is less than or equal to0, the maximum number of threads is unbounded.

Default value: -1

Required: false

Data type: int

coreThreadsDescription: Steady-state or core number of threads to associate with theexecutor. The number of threads associated with the executor will quicklygrow to this number. If this value is less than 0, a default value is used.This default value is calculated based on the number of hardware threadson the system.

Default value: -1

Required: false

Data type: int

keepAliveDescription: Amount of time to keep an idle thread in the pool beforeallowing it to terminate. Specify a positive integer followed by a unit oftime, which can be hours (h), minutes (m), seconds (s), or milliseconds(ms). For example, specify 500 milliseconds as 500ms. You can includemultiple values in a single entry. For example, 1s500ms is equivalent to1.5 seconds.

Default value: 60s

Required: false

Data type: string

stealPolicyDescription: The work-stealing policy to employ. The options for thispolicy determine how work is queued, and how threads obtain queuedwork.

Default value: LOCAL

Range:

STRICTAll threads that generate work own a local work pile. Threadsthat are associated with the executor take work from otherthreads when the local work pile is exhausted.


LOCALA global work queue is used for work that is generated bythreads that are not associated with the executor. Work generatedby threads associated with the executor is placed on a local workpile. This work pile is owned by the generating thread, unlessanother thread steals it. Threads that are associated with theexecutor take work associated with other threads if the local workpile is empty and there is no work on the global work queue.

NEVERA global work queue is used to feed work to threads that areassociated with the executor. No stealing will occur.

Required: false

Data type: string

rejectedWorkPolicyDescription: Policy to employ when the executor is unable to stage workfor execution.

Default value: ABORT

Range:

ABORTRaise an exception.

CALLER_RUNSExecute the work immediately on the caller's thread.

Required: false

Data type: string

featureManagerDefines how the server loads features. PID is com.ibm.ws.kernel.feature.


Attributes

onErrorDescription: Action to take after a failure to load a feature.

Inherits: onError

Default value: WARN

Range:

WARNServer will issue warning and error messages when it incurs afeature configuration error.

FAIL Server will issue a warning or error message on the first featureconfiguration error occurrence and then stop the server.

IGNOREServer will not issue any warning and error messages when itincurs a feature configuration error.

Required: true

Data type: string

Sub-elements

featureRequired: false

Data type: string

federatedRepository

Configuration for the Federated Manager core services. PID iscom.ibm.ws.wim.core.config.


Attributes

maxSearchResultsDescription: Maximum number of entries that can be returned in asearch.

Default value: 4500

Required: false

Data type: int

searchTimeOutDescription: The maximum amount of time, in milliseconds, to process asearch.


Required: false

Data type: int

supportedEntityTypeRefDescription: The configuration of the supported Entity Type.

Required: false

Data type: List of configuration IDs of type supportedEntityType(comma-separated string).

realmRefDescription: The realm configuration.

Required: false

Data type: List of configuration IDs of type realm (comma-separatedstring).

primaryRealmRefDescription: Primary realm configuration.

Required: false

Data type: Configuration ID of type realm (string).


Sub-elements

supportedEntityTypeDescription: The configuration of the supported Entity Type.

Required: false

Data type: Element of type supportedEntityType.

realmDescription: The realm configuration.

Required: false

Data type: Element of type realm.

primaryRealmDescription: Primary realm configuration.

Required: false

Data type: Element of type realm.

filesetFileset Service. PID is com.ibm.ws.kernel.metatype.helper.fileset.


Attributes

dirDescription: The base directory to search for files.

Default value: ${server.config.dir}

Required: true

Data type: string

caseSensitiveDescription: Boolean to indicate whether or not the search should be casesensitive (default: true).

Default value: true

Required: false

Data type: boolean

includesDescription: The comma or space separated list of file name patterns toinclude in the search results (default: *).

Default value: *

Required: false

Data type: string

excludesDescription: The comma or space separated list of file name patterns toexclude from the search results, by default no files are excluded.

Default value:

Required: false

Data type: string

scanIntervalDescription: Scanning interval to check the fileset for changes as a longwith a time unit suffix h-hour, m-minute, s-second, ms-millisecond (e.g.2ms or 5s). Disabled (scanInterval=0) by default. Specify a positive integerfollowed by a unit of time, which can be hours (h), minutes (m), seconds(s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms.You can include multiple values in a single entry. For example, 1s500ms isequivalent to 1.5 seconds.

Default value: 0

Required: false

Data type: string

fileTransfer

Main file transfer configuration element. PID iscom.ibm.ws.management.filetransfer.


Sub-elements

readLocationDescription: A location where the file transfer service has read-access.Default is ${wlp.install.dir}, ${wlp.user.dir} and ${server.output.dir}

Required: false

Data type: string

writeLocationDescription: A location where the file transfer service has write-access

Required: false

Data type: string

group

The group that is defined as part of the user registry. PID iscom.ibm.ws.messaging.security.group.

Attributes

nameDescription: The name of the group.

Required: true

Data type: string

groupDisplayNameMapping

The property mapping for groupDisplayName (default: cn). PID iscom.ibm.ws.wim.groupDisplayNameMapping.


Attributes

propertyForInputDescription: The property that maps to the user registry attribute forinput. The valid values are: uniqueId, uniqueName, externalId,externalName and the attributes of PersonAccount and Group entitytypes.

Default value: cn

Required: true

Data type: string

propertyForOutputDescription: The property that maps to the user registry attribute foroutput. The valid values are: uniqueId, uniqueName, externalId,externalName and the attributes of PersonAccount and Group entitytypes.

Default value: cn

Required: true

Data type: string

groupSecurityNameMapping

The property mapping for groupSecurityName (default: cn). PID iscom.ibm.ws.wim.groupSecurityNameMapping.

Attributes


Default value: cn

Required: true

Data type: string

propertyForOutputDescription: The property that maps to the user registry attribute foroutput. The valid values are: uniqueId, uniqueName, externalId,externalName and the attributes of PersonAccount and Group entitytypes.

Default value: cn

Required: true

Data type: string


hostAuthInfo

Connection details to allow for Atlas to authenticate to the server's host. PID iscom.ibm.ws.management.repository.member.hostAuthInfo.


Attributes

hostNameDescription: The fully qualified host name or IP address. A '*' wildcardwill result in host name detection; this is not recommended formulti-homed systems and may result in unexpected behaviour. The hostname must be unique within the network and must be the host name onwhich the remote connection protocol is listening (SSH, or OS specificRPC). This value will inherit from the defaultHostName variable if notset. The host name set here will directly control where the server'sinformation is stored within the Atlas repository.

Inherits: defaultHostName

Default value: localhost

Required: true

Data type: string

portDescription: The port on which the remote connection protocol islistening (SSH, or OS specific RPC). See product documentation forsupported RPC mechanisms.

Default value: 22

Required: true

Data type: int

userIdDescription: The operating system user ID to use to connect to the host.

Required: false

Data type: string

userPasswordDescription: The password for the operating system user. If this propertyis not set, key-based authentication will be used. Use of key-basedauthentication is recommended for hosts which support SSH. If thisproperty is set and sshPrivateKeyPath is also set, the key will takeprecedence.

Required: false


userHomeDescription: The home directory of the user login ID. Only required to beset if sudo is to be used and SSH generation is to be done automatically.

Required: false

Data type: string

sshPublicKeyPathDescription: The path to the SSH public key file. If the key pair does notexist, a key pair will be generated automatically. The public key will beplaced into the configured userId's authorized_keys file if it is notpresent. Setting the path to the public key is not required.

Required: false


Data type: string

sshPrivateKeyPathDescription: The path to the SSH private key file. If the key pair does notexist, a key pair will be generated automatically. The private key isrequired for key-based authentication.

Required: false

Data type: string

sshPrivateKeyPasswordDescription: The password for the SSH private key.

Required: false


useSudoDescription: If this property is set to true, then sudo will be used toinvoke commands. The user to sudo as can be controlled by settingsudoUser attribute. If sudoUser is not set, then the user to sudo as will bethe configured default sudo user for the host. If this property is not set,and either sudoUser or sudoUserPassword are set, then useSudo isassumed to be true. If this property is set to false, and either sudoUser orsudoUserPassword are set, then a warning will be printed and the sudooptions will be ignored.

Required: false

Data type: boolean

sudoUserDescription: The sudo user ID. This property should not be set whenuseSudo=false.

Required: false

Data type: string

sudoUserPasswordDescription: The password for the sudo user. This property should not beset when useSudo=false.

Required: false


httpClassificationAn element representing a rule used by WLM for classifying incoming HTTPrequests. PID is com.ibm.ws.zos.wlm.httpclassification, and it is the child ofcomplex type “wlmClassification”.


Attributes

transactionClassDescription: Defines the priority

Default value:

Required: false

Data type: string

hostDescription: Defines which host to map the transaction class to

Default value: *

Required: false

Data type: string

portDescription: Defines which port to map the transaction class to

Default value: *

Required: false

Data type: string

resourceDescription: Defines the URI to use when mapping transaction class

Default value: *

Required: false

Data type: string

methodDescription: Defines the HTTP method to map to

Default value: *

Required: false

Data type: string

httpDispatcherHTTP Dispatcher configuration. PID is com.ibm.ws.http.dispatcher.

Attributes

appOrContextRootMissingMessageDescription: Message to return to the client when the application in therequested URI can not be found.

Required: false

Data type: string


httpEncodingConfiguration properties for the HTTP Transport Encoding service. PID iscom.ibm.ws.transport.http.encoding.


Attributes

converter.Shift_JISDescription: Converter for Shift_JIS

Default value: Cp943C

Required: false

Data type: string

converter.EUC-JPDescription: Converter for EUC-JP

Default value: Cp33722C

Required: false

Data type: string

converter.EUC-KRDescription: Converter for EUC-KR

Default value: Cp970

Required: false

Data type: string

converter.EUC_KRDescription: Converter for EUC_KR


Required: false

Data type: string

converter.EUC-TWDescription: Converter for EUC-TW


Required: false

Data type: string

converter.Big5Description: Converter for Big5


Required: false

Data type: string

converter.GB2312Description: Converter for GB2312

Default value: EUC_CN

Required: false

Data type: string

converter.ISO-2022-KRDescription: Converter for ISO-2022-KR

Default value: ISO2022KR


Required: false

Data type: string

encoding.enDescription: Encoding for 'en' locale

Default value: ISO-8859-1

Required: false

Data type: string

encoding.frDescription: Encoding for 'fr' locale


Required: false

Data type: string

encoding.deDescription: Encoding for 'de' locale


Required: false

Data type: string

encoding.esDescription: Encoding for 'es' locale


Required: false

Data type: string

encoding.ptDescription: Encoding for 'pt' locale


Required: false

Data type: string

encoding.daDescription: Encoding for 'da' locale


Required: false

Data type: string

encoding.caDescription: Encoding for 'ca' locale


Required: false

Data type: string

encoding.fiDescription: Encoding for 'fi' locale



Required: false

Data type: string

encoding.itDescription: Encoding for 'it' locale


Required: false

Data type: string

encoding.nlDescription: Encoding for 'nl' locale


Required: false

Data type: string

encoding.noDescription: Encoding for 'no' locale


Required: false

Data type: string

encoding.svDescription: Encoding for 'sv' locale


Required: false

Data type: string

encoding.isDescription: Encoding for 'is' locale


Required: false

Data type: string

encoding.euDescription: Encoding for 'eu' locale


Required: false

Data type: string

encoding.csDescription: Encoding for 'cs' locale


Required: false

Data type: string

encoding.hrDescription: Encoding for 'hr' locale



Required: false

Data type: string

encoding.huDescription: Encoding for 'hu' locale


Required: false

Data type: string

encoding.ltDescription: Encoding for 'lt' locale


Required: false

Data type: string

encoding.plDescription: Encoding for 'pl' locale


Required: false

Data type: string

encoding.shDescription: Encoding for 'sh' locale


Required: false

Data type: string

encoding.skDescription: Encoding for 'sk' locale


Required: false

Data type: string

encoding.slDescription: Encoding for 'sl' locale


Required: false

Data type: string

encoding.sqDescription: Encoding for 'sq' locale


Required: false

Data type: string

encoding.foDescription: Encoding for 'fo' locale



Required: false

Data type: string

encoding.roDescription: Encoding for 'ro' locale


Required: false

Data type: string

encoding.mtDescription: Encoding for 'mt' locale


Required: false

Data type: string

encoding.etDescription: Encoding for 'et' locale


Required: false

Data type: string

encoding.lvDescription: Encoding for 'lv' locale


Required: false

Data type: string

encoding.beDescription: Encoding for 'be' locale


Required: false

Data type: string

encoding.bgDescription: Encoding for 'bg' locale


Required: false

Data type: string

encoding.mkDescription: Encoding for 'mk' locale


Required: false

Data type: string

encoding.ruDescription: Encoding for 'ru' locale



Required: false

Data type: string

encoding.srDescription: Encoding for 'sr' locale


Required: false

Data type: string

encoding.ukDescription: Encoding for 'uk' locale


Required: false

Data type: string

encoding.arDescription: Encoding for 'ar' locale


Required: false

Data type: string

encoding.faDescription: Encoding for 'fa' locale


Required: false

Data type: string

encoding.msDescription: Encoding for 'ms' locale


Required: false

Data type: string

encoding.elDescription: Encoding for 'el' locale


Required: false

Data type: string

encoding.iwDescription: Encoding for 'iw' locale


Required: false

Data type: string

encoding.heDescription: Encoding for 'he' locale



Required: false

Data type: string

encoding.jiDescription: Encoding for 'ji' locale


Required: false

Data type: string

encoding.yiDescription: Encoding for 'yi' locale


Required: false

Data type: string

encoding.trDescription: Encoding for 'tr' locale


Required: false

Data type: string

encoding.thDescription: Encoding for 'th' locale

Default value: windows-874

Required: false

Data type: string

encoding.viDescription: Encoding for 'vi' locale

Default value: windows-1258

Required: false

Data type: string

encoding.jaDescription: Encoding for 'ja' locale

Default value: Shift_JIS

Required: false

Data type: string

encoding.koDescription: Encoding for 'ko' locale

Default value: EUC-KR

Required: false

Data type: string

encoding.zhDescription: Encoding for 'zh' locale

Default value: GB2312


Required: false

Data type: string

encoding.zh_TWDescription: Encoding for 'zh_TW' locale

Default value: Big5

Required: false

Data type: string

encoding.hyDescription: Encoding for 'hy' locale

Default value: UTF-8

Required: false

Data type: string

encoding.kaDescription: Encoding for 'ka' locale


Required: false

Data type: string

encoding.hiDescription: Encoding for 'hi' locale


Required: false

Data type: string

encoding.mrDescription: Encoding for 'mr' locale


Required: false

Data type: string

encoding.saDescription: Encoding for 'sa' locale


Required: false

Data type: string

encoding.taDescription: Encoding for 'ta' locale


Required: false

Data type: string

encoding.bnDescription: Encoding for 'bn' locale



Required: false

Data type: string

httpEndpointConfiguration properties for an HTTP endpoint. PID is com.ibm.ws.http.


Attributes

httpOptionsRefDescription: HTTP protocol options for the endpoint.

Inherits: defaultHTTPVar

Required: false

Data type: Configuration ID of type httpOptions (string).

tcpOptionsRefDescription: TCP protocol options for the endpoint.

Default value: defaultTCPOptions

Required: false

Data type: Configuration ID of type tcpOptions (string).

enabledDescription: Toggle the availability of an endpoint. When true, thisendpoint will be activated by the dispatcher to handle HTTP requests.

Default value: true

Required: false

Data type: boolean

hostDescription: IP address, domain name server (DNS) host name withdomain name suffix, or just the DNS host name, used by a client torequest a resource. Use '*' for all available network interfaces.

Inherits: defaultHostName


Required: false

Data type: string

httpPortDescription: The port used for client HTTP requests. Use -1 to disablethis port.

Required: false

Data type: int

httpsPortDescription: The port used for client HTTP requests secured with SSL(https). Use -1 to disable this port.

Required: false

Data type: int

virtualHostDescription: ID of a configured virtual host. All endpoints are associatedwith the 'default_host' virtual host by default.

Default value: default_host

Required: false


Data type: string

sslOptionsRefDescription: SSL protocol options for the endpoint.

Inherits: defaultSSLVar

Required: false

Data type: Configuration ID of type sslOptions (string).

Sub-elements

httpOptionsDescription: HTTP protocol options for the endpoint.

Inherits: defaultHTTPVar

Required: false

Data type: Element of type httpOptions.

tcpOptionsDescription: TCP protocol options for the endpoint.


Required: false

Data type: Element of type tcpOptions.

sslOptionsDescription: SSL protocol options for the endpoint.


Required: false

Data type: Element of type sslOptions.

httpOptionsHTTP protocol configuration. PID is com.ibm.ws.http.options.


Attributes

keepAliveEnabledDescription: Enables persistent connections (HTTP keepalive). If true,connections are kept alive for reuse by multiple sequential requests andresponses. If false, connections are closed after the response is sent.

Default value: true

Required: false

Data type: boolean

maxKeepAliveRequestsDescription: Maximum number of persistent requests that are allowed ona single HTTP connection if persistent connections are enabled. A value of-1 means unlimited.

Default value: 100

Required: false

Data type: int

persistTimeoutDescription: Amount of time that a socket will be allowed to remain idlebetween requests. This setting only applies if persistent connections areenabled. Specify a positive integer followed by a unit of time, which canbe hours (h), minutes (m), or seconds (s). For example, specify 30 secondsas 30s. You can include multiple values in a single entry. For example,1m30s is equivalent to 90 seconds.

Default value: 30s

Required: false

Data type: string

readTimeoutDescription: Amount of time to wait for a read request to complete on asocket after the first read occurs. Specify a positive integer followed by aunit of time, which can be hours (h), minutes (m), or seconds (s). Forexample, specify 30 seconds as 30s. You can include multiple values in asingle entry. For example, 1m30s is equivalent to 90 seconds.

Default value: 60s

Required: false

Data type: string

writeTimeoutDescription: Amount of time to wait on a socket for each portion of theresponse data to be transmitted. Specify a positive integer followed by aunit of time, which can be hours (h), minutes (m), or seconds (s). Forexample, specify 30 seconds as 30s. You can include multiple values in asingle entry. For example, 1m30s is equivalent to 90 seconds.

Default value: 60s

Required: false

Data type: string


httpSessionConfiguration for HTTP session management. PID is com.ibm.ws.session.


Attributes

storageRefDescription: The ID of the persistent storage location for session data. Ifno storage location is defined, session data will be stored in the localapplication server's memory.

Required: false

Data type: string

sslTrackingEnabledDescription: Specifies that session tracking uses Secure Sockets Layer(SSL) information as a session ID.


Required: false

Data type: boolean

urlRewritingEnabledDescription: Specifies that the session management facility uses rewrittenURLs to carry the session IDs.


Required: false

Data type: boolean

protocolSwitchRewritingEnabledDescription: Adds the session ID to a URL when the URL requires aswitch from HTTP to HTTPS or from HTTPS to HTTP.


Required: false

Data type: boolean

cookiesEnabledDescription: Specifies that session tracking uses cookies to carry sessionIDs.

Default value: true

Required: false

Data type: boolean

cookieNameDescription: A unique name for a session management cookie.

Default value: JSESSIONID

Required: false

Data type: string

cookieDomainDescription: Domain field of a session tracking cookie.

Default value:

Required: false


Data type: string

cookieMaxAgeDescription: Maximum amount of time that a cookie can reside on theclient browser.

Default value: -1

Required: false

Data type: int

cookiePathDescription: A cookie is sent to the URL designated in the path.

Default value: /

Required: false

Data type: string

cookieSecureDescription: Specifies that the session cookies include the secure field.


Required: false

Data type: boolean

cookieHttpOnlyDescription: Specifies that session cookies include the HttpOnly field.Browsers that support the HttpOnly field do not enable cookies to beaccessed by client-side scripts. Using the HttpOnly field will help preventcross-site scripting attacks.

Default value: true

Required: false

Data type: boolean

maxInMemorySessionCountDescription: Maximum number of sessions to maintain in memory foreach web module.

Default value: 1000

Required: false

Data type: int

allowOverflowDescription: Allows the number of sessions in memory to exceed thevalue of the Max in-memory session count property.

Default value: true

Required: false

Data type: boolean

invalidationTimeoutDescription: Amount of time a session can go unused before it is nolonger valid.

Default value: 1800

Required: false


Data type: long

securityIntegrationEnabledDescription: Enables security integration, which causes the sessionmanagement facility to associate the identity of users with their HTTPsessions.

Default value: true

Required: false

Data type: boolean

idLengthDescription: Length of the session identifier.

Default value: 23

Required: false

Data type: int

useContextRootAsCookiePathDescription: Specifies that the cookie path equals the context root of theweb module instead of /


Required: false

Data type: boolean

alwaysEncodeUrlDescription: The Servlet 2.5 specification specifies to not encode the URLon a response.encodeURL call if it is not necessary. To support backwardcompatibility when URL encoding is enabled, set this property to true tocall the encodeURL method. The URL is always encoded, even if thebrowser supports cookies.


Required: false

Data type: boolean

cloneIdDescription: The clone ID of the cluster member. Within a cluster, this IDmust be unique to maintain session affinity. When set, this nameoverwrites the default name generated by the server.

Required: false

Data type: string

cloneSeparatorDescription: The single character used to separate the session ID from theclone ID in session cookies. The default value should usually be used. Onsome Wireless Application Protocol (WAP) devices, a colon (:) is notallowed, so a plus sign (+) should be used instead. Different valuesshould rarely be used. You should understand the clone characterrequirements of other products running on your system before using thisproperty to change the clone separator character. The fact that anycharacter can be specified as the value for this property does not implythat the character you specify will function correctly. This fact also doesnot imply that IBM is responsible for fixing any problem that might arisefrom using an alternative character.


Default value: :

Required: false

Data type: string

debugCrossoverDescription: Enable this option to perform additional checks to verifythat only the session associated with the request is accessed or referenced,and log messages if any discrepancies are detected. Disable this option toskip the additional checks.


Required: false

Data type: boolean

forceInvalidationMultipleDescription: If your requests normally are not bound by a response timelimit, specify 0 to indicate that the session manager should waitindefinitely until a request is complete before attempting to invalidate thesession. Otherwise, set this property to a positive integer to delay theinvalidation of active sessions. Active timed out sessions will not beinvalidated by the first invalidation interval pass, but will be invalidatedby the interval pass based on this value. For example, a value of 2 wouldinvalidate an active session on the second invalidation interval pass afterthe session timeout has expired.

Default value: 3

Required: false

Data type: int

idReuseDescription: In a multi-JVM environment that is not configured forsession persistence, setting this property to "true" enables the sessionmanager to use the same session information for all of a user's requestseven if the web applications that are handling these requests aregoverned by different JVMs. The default value for this property is false.Set this property to true if you want to enable the session manager to usethe session ID sent from a browser to preserve session data across webapplications that are running in an environment that is not configured forsession persistence.


Required: false

Data type: boolean

noAdditionalInfoDescription: Forces removal of information that is not needed in sessionidentifiers.


Required: false

Data type: boolean

reaperPollIntervalDescription: The wake-up interval, in seconds, for the process thatremoves invalid sessions. The minimum value is 30 seconds. If a value


less than the minimum is entered, an appropriate value is automaticallydetermined and used. This value overrides the default installation value,which is between 30 and 360 seconds, based off the session timeout value.Because the default session timeout is 30 minutes, the reaper interval isusually between 2 and 3 minutes.

Default value: -1

Required: false

Data type: long

rewriteIdDescription: Use this property to change the key used with URLrewriting.

Default value: jsessionid

Required: false

Data type: string

securityUserIgnoreCaseDescription: Indicates that the session security identity and the clientsecurity identity should be considered a match even if their cases aredifferent. For example, when this property is set to true, the sessionsecurity identity USER1 matches the client security identities User1 anduser1.


Required: false

Data type: boolean

invalidateOnUnauthorizedSessionRequestExceptionDescription: Set this property to true if, in response to an unauthorizedrequest, you want the session manager to invalidate a session instead ofissuing an UnauthorizedSessionRequestException. When a session isinvalidated, the requester can create a new session, but does not haveaccess to any of the previously saved session data. This allows a singleuser to continue processing requests to other applications after a logoutwhile still protecting session data.


Required: false

Data type: boolean

httpSessionDatabaseControls how HTTP sessions are persisted to a database. PID iscom.ibm.ws.session.db.


Attributes

dataSourceRefDescription: The ID of the data source the session manager should use topersist HTTP session data.

Required: true

Data type: string

useMultiRowSchemaDescription: When enabled, each session data attribute is placed in aseparate row in the database, allowing larger amounts of data to bestored for each session. This configuration can yield better performancewhen session attributes are very large and few changes are required tothe session attributes. When disabled, all session data attributes areplaced in the same row for each session.


Required: false

Data type: boolean

db2RowSizeDescription: Table space page size configured for the sessions table, ifusing a DB2 database. Increasing this value can improve databaseperformance in some environments.

Default value: 4KB

Range:

4KB Use the default table space page size of 4 KB. You do not need tocreate a DB2 buffer pool or table space, and you do not need tospecify a table space name.

8KB Use a table space page size of 8 KB. You must additionally createa DB2 buffer pool and table space, and specify 8KB as the pagesize for both. You must also specify the name of the table spaceyou created.

16KB Use a table space page size of 16 KB. You must additionallycreate a DB2 buffer pool and table space, and specify 16KB as thepage size for both. You must also specify the name of the tablespace you created.

32KB Use a table space page size of 32 KB. You must additionallycreate a DB2 buffer pool and table space, and specify 32KB as thepage size for both. You must also specify the name of the tablespace you created.

Required: false

Data type: string

tableSpaceNameDescription: Table space to be used for the sessions table. This value isonly required when the DB2 Row Size is greater than 4KB.

Default value:

Required: false


Data type: string

scheduleInvalidationDescription: Enable this option to reduce the number of database updatesrequired to keep the HTTP sessions alive. Specify the two hours of a daywhen there is the least activity in the application server. When this optionis disabled, the invalidator process runs every few minutes to removeinvalidated HTTP sessions.


Required: false

Data type: boolean

scheduleInvalidationFirstHourDescription: Indicates the first hour during which the invalidatedsessions are cleared from the persistent store. Specify this value as aninteger between 0 and 23. This value is valid only when scheduleinvalidation is enabled.

Default value: 0

Required: false

Data type: int

scheduleInvalidationSecondHourDescription: Indicates the second hour during which the invalidatedsessions are cleared from the persistent store. Specify this value as aninteger between 0 and 23. This value is valid only when scheduleinvalidation is enabled.

Default value: 0

Required: false

Data type: int

writeFrequencyDescription: Specifies when session data is written to the persistent store.By default, session data is written to the persistent store after the servletcompletes execution. Changing this value can improve performance insome environments.

Default value: END_OF_SERVLET_SERVICE

Range:

END_OF_SERVLET_SERVICESession data is written to the persistent store after the servletcompletes execution.

MANUAL_UPDATEA programmatic sync on the IBMSession object is required towrite the session data to the persistent store.

TIME_BASED_WRITESession data is written to the persistent store based on thespecified write interval value.

Required: false

Data type: string

writeInterval


Description: Number of seconds that should pass before writing sessiondata to the persistent store. The default is 120 seconds. This value is onlyused when a time based write frequency is enabled.

Default value: 120

Required: false

Data type: int

writeContentsDescription: Specifies how much session data should be written to thepersistent store. By default, only updated attributes are written, but allattributes can be written instead (regardless of whether or not theychanged).

Default value: ONLY_UPDATED_ATTRIBUTES

Range:

ONLY_UPDATED_ATTRIBUTESOnly updated attributes are written to the persistent store.

ALL_SESSION_ATTRIBUTESAll attributes are written to the persistent store.

Required: false

Data type: string

noAffinitySwitchBackDescription: Set this property to "true" to maintain affinity to the newmember even after original one comes back up. When a cluster memberfails, its requests routed to a different cluster member, and sessions areactivated in that other member. Thus, session affinity is maintained to thenew member, and when failed cluster member comes back up, therequests for sessions that were created in the original cluster member arerouted back to it. Allowed values are true or false, with the default beingfalse. Set this property to true when you have distributed sessionsconfigured with time-based write. Note that this property has no affect onthe behavior when distributed sessions are not enabled.


Required: false

Data type: boolean

onlyCheckInCacheDuringPreInvokeDescription: A value of true indicates that the last access time of asession should only be updated if a request gets the session. A value offalse indicates that the last access time of a session should be updatedupon every request. Changing this value can improve performance insome environments.


Required: false

Data type: boolean

optimizeCacheIdIncrementsDescription: If the user's browser session is moving back and forth acrossmultiple web applications, you might see extra persistent store activity asthe in-memory sessions for a web module are refreshed from the


persistent store. As a result, the cache IDs are continually increasing andthe in-memory session attributes are overwritten by those of thepersistent copy. Set this property to true if you want to prevent the cacheIDs from continually increasing. A value of true indicates that the sessionmanager should assess whether the in-memory session for a web moduleis older than the copy in persistent store. If the configuration is a cluster,ensure that the system times of each cluster member are as identical aspossible.

Default value: true

Required: false

Data type: boolean

tableNameDescription: The database table name.

Default value: sessions

Required: false

Data type: string

useInvalidatedIdDescription: Set this property to "true" to reuse the incoming ID if thesession with that ID was recently invalidated. This is a performanceoptimization because it prevents checking the persistent store.

Default value: true

Required: false

Data type: boolean

useOracleBlobDescription: Set this property to "true" to create the database table usingthe Binary Large Object (BLOB) data type for the medium column. Thisvalue increases performance of persistent sessions when Oracle databasesare used. Due to an Oracle restriction, BLOB support requires use of theOracle Call Interface (OCI) database driver for more than 4000 bytes ofdata. You must also ensure that a new sessions table is created before theserver is restarted by dropping your old sessions table or by changing thedatasource definition to reference a database that does not contain asessions table.


Required: false

Data type: boolean

skipIndexCreationDescription: Set this property to "true" to disable index creation on serverstartup. This custom property should only be used if you want tomanually create your own database indices for session persistence.However, it is recommended that you let session manager create databaseindices. Before enabling this property, make sure that the correct indexdoes exist on your session database.


Required: false

Data type: boolean


usingCustomSchemaNameDescription: Set this property to "true" if you are using DB2 for sessionpersistence and the currentSchema property is set in the data source.


Required: false

Data type: boolean

idsLdapFilterPropertiesSpecifies the list of default IBM Tivoli® Directory Server LDAP filters. PID iscom.ibm.ws.security.registry.ldap.internal.filters.ids.


Attributes



Required: true

Data type: string


Default value:

(&(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))

Required: true

Data type: string



Required: true

Data type: string


Default value: *:cn

Required: true

Data type: string


Default value:

ibm-allGroups:member;ibm-allGroups:uniqueMember;groupOfNames:member;groupOfUniqueNames:uniqueMember

Required: true

Data type: string

includeSpecify a configuration resource to include in the servers configuration.


Attributes

optionalDescription: Allow the included resource to be skipped if it cannot befound.

Required: false

Data type: boolean

locationDescription: The resource location, this could be a file path or a URI for aremote resource.

Required: true

Data type: string

iplanetLdapFilterPropertiesSpecifies the list of default Sun Java System Directory Server LDAP filters. PID iscom.ibm.ws.security.registry.ldap.internal.filters.iPlanet.


Attributes


Default value: (&(uid=%v)(objectclass=inetOrgPerson))

Required: true

Data type: string


Default value: (&(cn=%v)(objectclass=ldapsubentry))

Required: true

Data type: string


Default value: inetOrgPerson:uid

Required: true

Data type: string


Default value: *:cn

Required: true

Data type: string


Default value: nsRole:nsRole

Required: true

Data type: string

jaasLoginContextEntryThe JAAS login context entry configuration. PID iscom.ibm.ws.security.authentication.internal.jaas.jaasLoginContextEntry.


Attributes

nameDescription: Name of a JAAS configuration entry.

Required: true

Data type: string

loginModuleRefDescription: A reference to the ID of a JAAS login module.

Default value: hashtable, userNameAndPassword, certificate, token

Required: false

Data type: List of configuration IDs of type jaasLoginModule(comma-separated string).

jaasLoginModuleA login module in the JAAS configuration. PID iscom.ibm.ws.security.authentication.internal.jaas.jaasLoginModuleConfig.


Attributes

classNameDescription: Fully-qualified package name of the JAAS login moduleclass.

Required: true

Data type: string

controlFlagDescription: The login module's control flag. Valid values areREQUIRED, REQUISITE, SUFFICIENT, and OPTIONAL.

Default value: REQUIRED

Range:

REQUIREDThis LoginModule is REQUIRED as per the JAAS specification.The LoginModule is required to succeed.

REQUISITEcontrolFlag.REQUISITE

SUFFICIENTThis LoginModule is SUFFICIENT as per the JAAS specification.The LoginModule is not required to succeed. If authentication issuccessful, no other LoginModules will be called and control isreturned to the caller.

OPTIONALThis LoginModule is OPTIONAL as per the JAAS specification.The LoginModule is not required to succeed.

Required: true

Data type: string

libraryRefDescription: A reference to the ID of the shared library configuration.

Required: false

Data type: Configuration ID of type library (string).

Sub-elements

libraryDescription: A reference to the ID of the shared library configuration.

Required: false


optionsDescription: A collection of JAAS Login module options

Required: false


jdbcDriverIdentifies a JDBC driver. PID is com.ibm.ws.jdbc.jdbcDriver.

Attributes

libraryRefDescription: Identifies JDBC driver JARs and native files.

Required: false


javax.sql.XADataSourceDescription: JDBC driver implementation of javax.sql.XADataSource.

Required: false

Data type: string

javax.sql.ConnectionPoolDataSourceDescription: JDBC driver implementation ofjavax.sql.ConnectionPoolDataSource.

Required: false

Data type: string

javax.sql.DataSourceDescription: JDBC driver implementation of javax.sql.DataSource.

Required: false

Data type: string

Sub-elements

libraryDescription: Identifies JDBC driver JARs and native files.

Required: false


jmsCommsEndpoint

Configuration properties for JMS incoming connection requests. PID iscom.ibm.ws.messaging.comms.server.


Attributes

tcpOptionsRefDescription: TCP protocol options for the endpoint.


Required: false


enabledDescription: Toggle the availability of an JMS Comms endpoint. Whentrue, this endpoint will be activated by the JMS Comms component.

Default value: true

Required: false

Data type: boolean

hostDescription: IP address, domain name server (DNS) host name withdomain name suffix, or just the DNS host name, used by a client torequest a resource. Use '*' for all available network interfaces.


Required: false

Data type: string

jmsPortDescription: The port used for client messaging application connectionrequest. Use -1 to disable this port.

Default value: 7276

Required: false

Data type: int

jmsSSLPortDescription: The port used for client messaging application connectionrequests secured with SSL. Use -1 to disable this port.

Default value: 7286

Required: false

Data type: int

sslOptionsRefDescription: SSL protocol options for the endpoint.


Required: false



Sub-elements

tcpOptionsDescription: TCP protocol options for the endpoint.


Required: false


sslOptionsDescription: SSL protocol options for the endpoint.


Required: false


jmsCommsOutbound

%jmsCommsOutbound.desc. PID is com.ibm.ws.messaging.comms.client.

Attributes

tcpOptionsRefDescription: TCP protocol options for JMS Comms outbound


Required: false


sslOptionsRefDescription: SSL protocol options for JMS Comms outbound


Required: false



Sub-elements

tcpOptionsDescription: TCP protocol options for JMS Comms outbound


Required: false


sslOptionsDescription: SSL protocol options for JMS Comms outbound


Required: false


jmsConnectionFactory

Defines a JMS connection factory configuration. PID iscom.ibm.ws.jca.jmsConnectionFactory.

jmsQueue

Defines a JMS queue configuration. PID is com.ibm.ws.jca.jmsQueue.

jmsQueueConnectionFactory

Defines a JMS queue connection factory configuration. PID iscom.ibm.ws.jca.jmsQueueConnectionFactory.

jmsTopic

Defines a JMS topic configuration. PID is com.ibm.ws.jca.jmsTopic.

jmsTopicConnectionFactory

Defines a JMS topic connection factory configuration. PID iscom.ibm.ws.jca.jmsTopicConnectionFactory.

jndiEntryA single entry in the JNDI default namespace. PID iscom.ibm.ws.jndi.internal.JNDIEntry.


Attributes

jndiNameDescription: The JNDI name to use for this entry.

Required: true

Data type: string

valueDescription: The JNDI value to associate with the name.

Required: true

Data type: string

jpaConfiguration properties for the Java Persistence API container. PID iscom.ibm.ws.jpacomponent.

Attributes

defaultJtaDataSourceJndiNameDescription: Default Java™ Transaction API (JTA) data source JNDI nameto be used by applications running in this server. By default, data sourcesare JTA. Only data sources that are transactional are allowed in this field.

Default value:

Required: false

Data type: string

defaultNonJtaDataSourceJndiNameDescription: Default non-transactional data source JNDI name to be usedby applications running in this server. Only data sources that have beenmarked as non-transactional are allowed in this field.

Default value:

Required: false

Data type: string

defaultPersistenceProviderDescription: Default persistence provider.

Default value: com.ibm.websphere.persistence.PersistenceProviderImpl

Required: false

Data type: string

entityManagerPoolCapacityDescription: EntityManager pool capacity per PersistenceContextreference. The minimum is 0 and the maximum is 500.

Default value: -1

Required: false

Data type: int


Sub-elements

excludedApplicationDescription: An application to be excluded from JPA processing.

Default value:

Required: false

Data type: string

jspEngineJSP 2.2 configuration. PID is com.ibm.ws.jsp.2.2.


Attributes

disableJspRuntimeCompilationDescription: Disable compilation of JSPs at runtime.


Required: false

Data type: boolean

extendedDocumentRootDescription: Directory that the JSP engine will search for additional JSPfiles to serve.

Default value:

Required: false

Data type: string

jdkSourceLevelDescription: Default Java source level for JSPs compiled by the JSPengine.

Default value: 15

Range:

13

14

15

16

Required: false

Data type: string

keepGeneratedDescription: Keep Java source files generated for JSPs.


Required: false

Data type: boolean

useInMemoryDescription: Generate Java source and classes in memory (withoutwriting to disk).


Required: false

Data type: boolean

recompileJspOnRestartDescription: Recompile JSPs after an application is restarted. JSPs arerecompiled on first access.


Required: false


Data type: boolean

useImplicitTagLibsDescription: Allow JSPs to use jsx and tsx tag libs.

Default value: true

Required: false

Data type: boolean

disableResourceInjectionDescription: Disable injection of resources into JSPs.


Required: false

Data type: boolean

prepareJSPsDescription: When this attribute is present, all JSPs larger than the value(in kilobytes) are compiled at application server startup. Set this to 0 tocompile all JSPs.

Required: false

Data type: int

keyStoreA repository of security certificates used for SSL encryption. PID iscom.ibm.ws.ssl.keystore.


Attributes

passwordDescription: The password used to load the keystore file. The value canbe stored in clear text or encoded form. Use the securityUtility tool toencode the password.

Required: true


locationDescription: An absolute or relative path to the keystore file. If a relativepath is provided, the server will attempt to locate the file in the${server.config.dir}/resources/security directory. Use the keystore file fora file-based keystore, the keyring name for SAF keyrings, or the deviceconfiguration file for hardware cryptography devices. In the SSL minimalconfiguration, the location of the file is assumed to be${server.config.dir}/resources/security/key.jks.

Default value: ${server.output.dir}/resources/security/key.jks

Required: false

Data type: string

typeDescription: A keystore type supported by the target SDK.

Default value: jks

Required: false

Data type: string

ldapRegistryConfiguration properties for an LDAP user registry. PID iscom.ibm.ws.security.registry.ldap.config.


Attributes

hostDescription: Address of the LDAP server in the form of a IP address or adomain name service (DNS) name.

Required: true

Data type: string

portDescription: Port number of the LDAP server.

Required: true

Data type: int

baseDNDescription: Base distinguished name (DN) of the directory service,which indicates the starting point for LDAP searches in the directoryservice.

Required: true

Data type: string

ldapTypeDescription: Type of LDAP server to which a connection will beestablished.

Range:

Microsoft Active Directoryactived

Custom

IBM Lotus Dominodomino50

Novell eDirectoryedirectory

IBM Tivoli Directory Serveribm_dir_server

Sun Java System Directory Serveriplanet

Netscape Directory Servernetscape

IBM SecureWay Directory Serversecureway

Required: true

Data type: string


Default value: LdapRegistry

Required: false


Data type: string

bindDNDescription: Distinguished name (DN) for the application server, which isused to bind to the directory service.

Required: false

Data type: string

bindPasswordDescription: Password for the bind DN. The value can be stored in cleartext or encoded form. It is recommended that you encode the password.To do so, use the securityUtility tool with the encode option.

Required: false


ignoreCaseDescription: Perform a case-insensitive authentication check.

Default value: true

Required: false

Data type: boolean

recursiveSearchDescription: Performs a nested group search. Select this option only if theLDAP server does not support recursive server-side searches.


Required: false

Data type: boolean

reuseConnectionDescription: Requests the application server to reuse the LDAP serverconnection.

Default value: true

Required: false

Data type: boolean

sslEnabledDescription: Indicates whether an SSL connection should be made to theLDAP server.


Required: false

Data type: boolean

sslRefDescription: ID of the SSL configuration to be used to connect to theSSL-enabled LDAP server.

Required: false

Data type: string

searchTimeoutDescription: Maximum time for an LDAP server to respond before arequest is canceled. This is equivalent to a read timeout once the


connection is established. Specify a positive integer followed by a unit oftime, which can be hours (h), minutes (m), seconds (s), or milliseconds(ms). For example, specify 500 milliseconds as 500ms. You can includemultiple values in a single entry. For example, 1s500ms is equivalent to1.5 seconds.

Default value: 1m

Required: false

Data type: string

connectTimeoutDescription: Maximum time for establishing a connection to the LDAPserver. Specify a positive integer followed by a unit of time, which can behours (h), minutes (m), seconds (s), or milliseconds (ms). For example,specify 500 milliseconds as 500ms. You can include multiple values in asingle entry. For example, 1s500ms is equivalent to 1.5 seconds.

Default value: 1m

Required: false

Data type: string

certificateMapModeDescription: Specifies whether to map x.509 certificates into an LDAPdirectory by EXACT_DN or CERTIFICATE_FILTER. SpecifyCERTIFICATE_FILTER to use the specified certificate filter for themapping.

Range:

EXACT_DNexactDN

CERTIFICATE_FILTERcertFilter

Required: false

Data type: string

certificateFilterDescription: Specifies the filter certificate mapping property for theLDAP filter. The filter is used to map attributes in the client certificate toentries in the LDAP registry. For example, the filter can be specified as:uid=${SubjectCN}.

Required: false

Data type: string

activedFiltersRefDescription: Specifies the list of default Microsoft Active Directory LDAPfilters.

Required: false

Data type: Configuration ID of type activedLdapFilterProperties (string).

customFiltersRefDescription: Specifies the list of default Custom LDAP filters.

Required: false

Data type: Configuration ID of type customLdapFilterProperties (string).


domino50FiltersRefDescription: Specifies the list of default IBM Lotus Domino LDAP filters.

Required: false

Data type: Configuration ID of type domino50LdapFilterProperties(string).

edirectoryFiltersRefDescription: Specifies the list of Novell eDirectory LDAP filters.

Required: false

Data type: Configuration ID of type edirectoryLdapFilterProperties(string).

idsFiltersRefDescription: Specifies the list of default IBM Tivoli Directory ServerLDAP filters.

Required: false

Data type: Configuration ID of type idsLdapFilterProperties (string).

iplanetFiltersRefDescription: Specifies the list of default Sun Java System Directory ServerLDAP filters.

Required: false

Data type: Configuration ID of type iplanetLdapFilterProperties (string).

netscapeFiltersRefDescription: Specifies the list of default Netscape Directory Server LDAPfilters.

Required: false

Data type: Configuration ID of type netscapeLdapFilterProperties (string).

securewayFiltersRefDescription: Specifies the list of default IBM SecureWay Directory ServerLDAP filters.

Required: false

Data type: Configuration ID of type securewayLdapFilterProperties(string).


Sub-elements

failoverServersDescription: List of LDAP failover servers.

Required: false

Data type: List of LDAP failover servers.

nameDescription: Configuration properties for LDAP failover servers.

Required: false

Data type: string

serverDescription: Configuration properties for LDAP failover server.

Required: false

Data type: Configuration properties for LDAP failover server.

hostDescription: LDAP server host name, which can be either an IPaddress or a domain name service (DNS) name.

Required: true

Data type: string

portDescription: LDAP failover server port.

Required: true

Data type: int

activedFiltersDescription: Specifies the list of default Microsoft Active Directory LDAPfilters.

Required: false

Data type: Element of type activedLdapFilterProperties.

customFiltersDescription: Specifies the list of default Custom LDAP filters.

Required: false

Data type: Element of type customLdapFilterProperties.

domino50FiltersDescription: Specifies the list of default IBM Lotus Domino LDAP filters.

Required: false

Data type: Element of type domino50LdapFilterProperties.

edirectoryFiltersDescription: Specifies the list of Novell eDirectory LDAP filters.

Required: false

Data type: Element of type edirectoryLdapFilterProperties.

idsFilters


Description: Specifies the list of default IBM Tivoli Directory ServerLDAP filters.

Required: false

Data type: Element of type idsLdapFilterProperties.

iplanetFiltersDescription: Specifies the list of default Sun Java System Directory ServerLDAP filters.

Required: false

Data type: Element of type iplanetLdapFilterProperties.

netscapeFiltersDescription: Specifies the list of default Netscape Directory Server LDAPfilters.

Required: false

Data type: Element of type netscapeLdapFilterProperties.

securewayFiltersDescription: Specifies the list of default IBM SecureWay Directory ServerLDAP filters.

Required: false

Data type: Element of type securewayLdapFilterProperties.

libraryShared Library. PID is com.ibm.ws.classloading.sharedlibrary.


Attributes

nameDescription: Name of shared library for administrators

Required: false

Data type: string

descriptionDescription: Description of shared library for administrators

Required: false

Data type: string

filesetRefDescription: Id of referenced Fileset

Required: false

Data type: List of configuration IDs of type fileset (comma-separatedstring).

apiTypeVisibilityDescription: The types of API package this library's class loader will beable to see, as a comma-separated list of any combination of thefollowing: spec, ibm-api, api, third-party.

Default value: spec,ibm-api,api

Required: false

Data type: string


Sub-elements

filesetDescription: Id of referenced Fileset

Required: false

Data type: Element of type fileset.

folderDescription: Id of referenced folder

Required: false

Data type: Folder containing resources such as .properties and .class files.

dirDescription: Directory or folder to be included in the libraryclasspath for locating resource files

Required: true

Data type: string

fileDescription: Id of referenced File

Required: false

Data type: Add a file to be included in this library.

nameDescription: Fully qualified filename

Required: true

Data type: string

localStore

Clients are defined in server.xml and tokens are cached in the server. PID iscom.ibm.ws.security.oauth20.local.store.

Attributes

clientRefRequired: false

Data type: List of configuration IDs of type client (comma-separatedstring).


Sub-elements

clientRequired: false

Data type: Element of type client.

loggingControls the output of log and trace messages. PID is com.ibm.ws.logging.


Attributes

maxFileSizeDescription: Maximum size of a log file, in megabytes, before beingrolled over; a value of 0 means no limit.

Inherits: com.ibm.ws.logging.max.file.size

Default value: 20

Required: false

Data type: int

maxFilesDescription: Maximum number of log files that will be kept, before theoldest file is removed; a value of 0 means no limit.

Inherits: com.ibm.ws.logging.max.files

Default value: 2

Required: false

Data type: int

logDirectoryDescription: Location to which all log files will be written. The defaultvalue is ${server.output.dir}/logs.

Inherits: com.ibm.ws.logging.log.directory

Default value: ${server.output.dir}/logs

Required: false

Data type: string

messageFileNameDescription: Name of the file to which message output will be writtenrelative to the configured log directory. The default value is messages.log.

Inherits: com.ibm.ws.logging.message.file.name

Default value: messages.log

Required: false

Data type: string

traceFileNameDescription: Name of the file to which trace output will be writtenrelative to the configured log directory. The default value is trace.log.

Inherits: com.ibm.ws.logging.trace.file.name

Default value: trace.log

Required: false

Data type: string

traceSpecificationDescription: A trace specification that conforms to the trace specificationgrammar and specifies the initial state for various trace components. Anempty value is allowed and treated as 'disable all trace'. Any componentthat is not specified is initialized to a default state of disabled.


Inherits: com.ibm.ws.logging.trace.specification

Default value: *=info=enabled

Required: false

Data type: string

traceFormatDescription: This format is used for the trace log.

Inherits: com.ibm.ws.logging.trace.format

Default value: ENHANCED

Range:

BASICUse the basic trace format.

ENHANCEDUse the enhanced basic trace format.

ADVANCEDUse the advanced trace format.

Required: false

Data type: string

consoleLogLevelDescription: The logging level used to filter messages written to systemstreams. The default value is audit.

Inherits: com.ibm.ws.logging.console.log.level

Default value: AUDIT

Range:

INFO Info, audit, and warning messages will be written to the systemoutput stream. Error messages will be written to the system errorstream.

AUDITAudit and warning messages will be written to the system outputstream. Error messages will be written to the system error stream.

WARNINGWarning messages will be written to the system output stream.Error messages will be written to the system error stream.

ERRORError messages will be written to the system error stream.

OFF No server output will be written to system streams. Only JVMoutput will be written to system streams.

Required: false

Data type: string

ltpaLightweight Third Party Authentication (LTPA) token configuration. PID iscom.ibm.ws.security.token.ltpa.LTPAConfiguration.


Attributes

keysFileNameDescription: Path of the file containing the token keys.

Default value: ${server.config.dir}/resources/security/ltpa.keys

Required: false

Data type: string

keysPasswordDescription: Password for the token keys. The value can be stored inclear text or encoded form. It is recommended to encode the password,use the securityUtility tool with the encode option.

Default value: {xor}CDo9Hgw=

Required: false


expirationDescription: Amount of time after which a token expires in minutes.Specify a positive integer followed by a unit of time, which can be hours(h) or minutes (m). For example, specify 30 minutes as 30m. You caninclude multiple values in a single entry. For example, 1h30m isequivalent to 90 minutes.

Default value: 120m

Required: false

Data type: string

monitorIntervalDescription: Rate at which the server checks for updates to the LTPAtoken keys file. Specify a positive integer followed by a unit of time,which can be hours (h), minutes (m), seconds (s), or milliseconds (ms).For example, specify 500 milliseconds as 500ms. You can include multiplevalues in a single entry. For example, 1s500ms is equivalent to 1.5seconds.

Default value: 0ms

Required: false

Data type: string

managedExecutorService

PID is com.ibm.ws.concurrent.managedExecutorService.


Attributes

contextServiceRefDescription: contextServiceRef.desc

Default value: DefaultContextService

Required: false

Data type: Configuration ID of type contextService (string).

jndiNameDescription: JNDI name for a managed executor service

Required: false

Data type: string

Sub-elements

contextServiceDescription: contextServiceRef.desc

Default value: DefaultContextService

Required: false

Data type: Element of type contextService.

managedServer

Managed server configuration. PID is com.ibm.ws.management.repository.member.

Attributes

electionPortDescription: Host leader election port


Required: true

Data type: int

managementRepository

Management repository configuration. PID is com.ibm.ws.management.repository.


Sub-elements

cohortDescription: The endpoint of a management repository cohort

Required: false

Data type: string

managementRepositoryConnection

The management repository connection configuration, which consists of at leastone bootstrap address (host and port). The management repository connection canhave multiple bootstrap addresses. PID iscom.ibm.ws.management.repository.connection.

Attributes

bootstrapHostDescription: A host name for a management repository bootstrapinstance.

Required: true

Data type: string

bootstrapPortDescription: The port for the JMX/REST connector, typically the HTTPSport.

Required: true

Data type: int

bootstrapUsernameDescription: The user with which to authenticate to the ManagementRepository

Required: true

Data type: string

bootstrapPasswordDescription: The password for the user with which to authenticate to theManagement Repository

Required: true


sslRefDescription: ID of the SSL configuration to be used to connect to theSSL-enabled LDAP server.

Default value: defaultSSLConfig

Required: true

Data type: string


Sub-elements

additionalBootstrapAddressDescription: An additional management repository bootstrap addresswhich will be used in the event of the primary address being unavailable.

Required: false

Data type: An additional management repository bootstrap addresswhich will be used in the event of the primary address being unavailable.

hostDescription: A host name for a management repository bootstrapinstance.

Required: true

Data type: string

portDescription: The port for the JMX/REST connector, typically theHTTPS port.

Required: true

Data type: int

member

Members of an external cache group that are controlled by WebSphere ApplicationServer. PID is com.ibm.ws.cache.cacheGroup.member, and it is the child of complextype “cacheGroup”.

Attributes

hostDescription: Fully qualified host name

Required: false

Data type: string

portDescription: IP port.

Required: false

Data type: int


Sub-elements

adapterBeanNameDescription: Specifies the name of a class, which is located on theWebSphere Application Server class path, of the adapter betweenWebSphere Application Server and this external cache.

Required: true

Data type: string

messagingEngine

A messaging engine is a component, running inside a server, that managesmessaging resources. Applications are connected to a messaging engine when theysend and receive messages. PID is com.ibm.ws.messaging.runtime.

Attributes


Sub-elements

fileStoreDescription: Messaging File store.

Required: false

Data type: Messaging File store.

pathDescription: Path to the file store.

Default value: ${server.output.dir}/messaging/messageStore

Required: false

Data type: string

logFileSizeDescription: Size in megabytes of the log file.

Default value: 10

Required: false

Data type: long

fileStoreSizeDescription: fileStoreSize.desc

Default value: 400

Required: false

Data type: long

queueDescription: A JMS queue is used as a destination for point-to-pointmessaging.

Required: false

Data type: A JMS queue is used as a destination for point-to-pointmessaging.

forceReliabilityDescription: The reliability assigned to a message produced to thisdestination when an explicit reliability has not been set by theproducer.

Default value: AssuredPersistent

Range:

BestEffortNonPersistent

ExpressNonPersistent

ReliableNonPersistent

ReliablePersistent

AssuredPersistent

Required: false

Data type: string


exceptionDestinationDescription: The destination to which a message is forwarded by thesystem when it cannot be delivered to this destination.

Default value: _SYSTEM.Exception.Destination

Required: false

Data type: string

failedDeliveryPolicyDefault value: SEND_TO_EXCEPTION_DESTINATION

Range:

SEND_TO_EXCEPTION_DESTINATION

DISCARD

KEEP_TRYING

Required: false

Data type: string

redeliveryIntervalDescription: Indicates the application server the waiting time before amessage is redelivered to an MDB. The waiting time is indicated onlyif the exception destination property is set to None, and theconfigured number of maximum failed deliveries has been reached.

Default value: -1

Required: false

Data type: long

maxRedeliveryCountDescription: The maximum number of failed attempts to process amessage before the message is forwarded to the exception destinationfor the destination. Specify a value in the range 0 - 2147483647. Avalue of 0 (zero) means that if a message cannot be delivered on thefirst attempt, it is either forwarded to the exception destination ordiscarded, as defined by the exceptionDestination property.

Default value: 5

Required: false

Data type: int

sendAllowedDescription: Producers can send messages to this destination.

Default value: true

Required: false

Data type: boolean

receiveAllowedDescription: Clear this option (setting it to false) to preventconsumers from being able to receive messages from this destination.

Default value: true

Required: false

Data type: boolean


maintainStrictOrderDescription: Maintains the order in which a producer sends messagesto the destination.


Required: false

Data type: boolean

maxQueueDepthDescription: The maximum number of messages that the messagingengine can place on its message points.


Required: false

Data type: long

topicSpaceDescription: topicSpaceRef.desc

Required: false

Data type: topicSpace.desc.

forceReliabilityDescription: topicSpace.forceReliability.desc


Range:




ReliablePersistent

AssuredPersistent

Required: false

Data type: string

exceptionDestinationDescription: topicSpace.exceptionDestination.desc

Default value: _SYSTEM.Exception.Destination

Required: false

Data type: string

failedDeliveryPolicyDefault value: SEND_TO_EXCEPTION_DESTINATION

Range:

SEND_TO_EXCEPTION_DESTINATION

DISCARD

KEEP_TRYING

Required: false

Data type: string


redeliveryIntervalDescription: topicSpace.redeliveryInterval.desc

Default value: -1

Required: false

Data type: long

maxRedeliveryCountDescription: topicSpace.maxRedeliveryCount.desc

Default value: 5

Required: false

Data type: int

sendAllowedDescription: topicSpace.sendAllowed.desc

Default value: true

Required: false

Data type: boolean

receiveAllowedDescription: topicSpace.receiveAllowed.desc

Default value: true

Required: false

Data type: boolean

maintainStrictOrderDescription: topicSpace.maintainStrictOrder.desc


Required: false

Data type: boolean

maxQueueDepthDescription: topicSpace.maxQueueDepth.desc


Required: false

Data type: long

aliasDescription: An alias destination provides a level of abstraction betweenapplications and the underlying target destinations that hold messages.Applications interact with the alias destination, so the target destinationcan be changed without changing the application.

Required: false

Data type: An alias destination provides a level of abstraction betweenapplications and the underlying target destinations that hold messages.Applications interact with the alias destination, so the target destinationcan be changed without changing the application.

targetDestinationDescription: The targetDestination parameter identifies a destination


that might be within the same Bus as the alias destination.

Default value:

Required: false

Data type: string

forceReliabilityDescription: The reliability assigned to a message produced to thisdestination when an explicit reliability has not been set by theproducer.


Range:




ReliablePersistent

AssuredPersistent

Required: false

Data type: string

sendAllowedDescription: Producers can send messages to this alias destination.

Default value: true

Range:

true

false

Required: false

Data type: string

messagingSecurity

Security for the JMSServer-1.0 feature. PID is com.ibm.ws.messaging.security.

Attributes

roleRefDescription: A set of permissions mapped to the users and groups.

Required: false

Data type: List of configuration IDs of type role (comma-separatedstring).


Sub-elements

roleDescription: A set of permissions mapped to the users and groups.

Required: false

Data type: Element of type role.

mimeTypesDefinition of mime types shared by all http virtual hosts. PID iscom.ibm.ws.http.mimetype.

Sub-elements

typeDescription: Definition of mime type as id=value. Use the extension asthe id, and the associated type as the value.

Required: false

Data type: string

mongo

Configuration for a Mongo instance. PID is com.ibm.ws.mongo.mongo.


Attributes

libraryRefDescription: Specifies a library that contains the Mongo Java Driver

Required: false


onErrorDescription: Determines the action to take in response to configurationerrors.

Inherits: onError

Default value: WARN

Range:

FAIL Fail when incorrect configuration is encountered.

IGNOREIgnore incorrect configuration.

WARNonError.WARN

Required: false

Data type: string

passwordDescription: Password for database user.

Required: false


userDescription: Database user name.

Required: false

Data type: string

alwaysUseMBeansDescription: Configures whether the driver uses MBeans or MXBeans.

Required: false

Data type: boolean

autoConnectRetryDescription: Retry connections to a server, for an interval up to themaxAutoConnectRetryTime, if the socket cannot be opened.

Required: false

Data type: boolean

connectionsPerHostDescription: Limits the number of open connections to each host.Connections are pooled when not in use.

Required: false

Data type: int


connectTimeoutDescription: Connection timeout for new connections. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as500ms. You can include multiple values in a single entry. For example,1s500ms is equivalent to 1.5 seconds.

Required: false

Data type: string

cursorFinalizerEnabledDescription: Attempts to clean up DBCursors that are not closed.

Required: false

Data type: boolean

descriptionDescription: Description of a Mongo instance.

Required: false

Data type: string

fsyncDescription: Global WriteConcern fsync parameter.

Required: false

Data type: boolean

j Description: Global WriteConcern j parameter.

Required: false

Data type: boolean

maxAutoConnectRetryTimeDescription: Interval during which to retry attempts to open a connectionto a server. Specify a positive integer followed by a unit of time, whichcan be hours (h), minutes (m), seconds (s), or milliseconds (ms). Forexample, specify 500 milliseconds as 500ms. You can include multiplevalues in a single entry. For example, 1s500ms is equivalent to 1.5seconds.

Required: false

Data type: string

maxWaitTimeDescription: Maximum amount of time to wait for an availableconnection. If negative, the connection request never times out. Specify apositive integer followed by a unit of time, which can be hours (h),minutes (m), seconds (s), or milliseconds (ms). For example, specify 500milliseconds as 500ms. You can include multiple values in a single entry.For example, 1s500ms is equivalent to 1.5 seconds.

Required: false

Data type: string

readPreferenceDescription: Configures the read preference.

Range:


nearest

primary

primaryPreferred

secondary

secondaryPreferred

Required: false

Data type: string

safeDescription: Use WriteConcern.SAFE unless fsync, j, w, or wtimeout areconfigured.

Required: false

Data type: boolean

socketKeepAliveDescription: Configures whether or not to keep sockets alive.

Required: false

Data type: boolean

socketTimeoutDescription: The socket timeout. Specify a positive integer followed by aunit of time, which can be hours (h), minutes (m), seconds (s), ormilliseconds (ms). For example, specify 500 milliseconds as 500ms. Youcan include multiple values in a single entry. For example, 1s500ms isequivalent to 1.5 seconds.

Required: false

Data type: string

threadsAllowedToBlockForConnectionMultiplierDescription: This value, multiplied by connectionsPerHost, establishes anupper limit on threads that are allowed to wait for an availableconnection.

Required: false

Data type: int

w Description: Global write concern w parameter.

Required: false

Data type: int

wtimeoutDescription: Global write concern wtimeout parameter. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as500ms. You can include multiple values in a single entry. For example,1s500ms is equivalent to 1.5 seconds.

Required: false

Data type: string


Sub-elements

hostNamesDescription: List of host names. The ordering of this list must beconsistent with the list of ports, such that the first element in the list ofhost names corresponds to the first element in the list of ports, and soforth.


Required: true

Data type: string

libraryDescription: Specifies a library that contains the Mongo Java Driver

Required: false


portsDescription: List of port numbers. The ordering of this list must beconsistent with the list of host names, such that the first element in thelist of host names corresponds to the first element in the list of ports, andso forth.


Required: false

Data type: int

mongoDB

Configuration for a Mongo DB instance. PID is com.ibm.ws.mongo.mongoDB.

Attributes

databaseNameDescription: Name of the database.

Required: true

Data type: string

jndiNameDescription: JNDI name for a Mongo DB instance

Required: true

Data type: string

mongoRefDescription: Specifies the Mongo instance.

Required: false

Data type: Configuration ID of type mongo (string).


Sub-elements

mongoDescription: Specifies the Mongo instance.

Required: false

Data type: Element of type mongo.

monitorConfiguration for Monitoring. PID iscom.ibm.ws.monitor.internal.MonitoringFrameworkExtender.

Attributes

enableTraditionalPMIDescription: Internal Property to enable or disable Traditional PMI


Required: false

Data type: boolean

nativeTransactionManagerConfigures the RRS Native Transaction Manager. PID is com.ibm.ws.zos.tx.


Attributes

shutdownTimeoutDescription: The amount of time to wait before allowing the nativecontext manager to stop if one or more native contexts are in-use. Anative context is considered in-use if it contains an RRS unit of recoverywith one or more interests. The timeout is specified by a positive integerfollowed by a unit of time, which can be milliseconds (ms), seconds (s),minutes (m) or hours (h). For example, fifteen seconds is specified as 15s.Specify a positive integer followed by a unit of time, which can be hours(h), minutes (m), seconds (s), or milliseconds (ms). For example, specify500 milliseconds as 500ms. You can include multiple values in a singleentry. For example, 1s500ms is equivalent to 1.5 seconds.

Default value: 15s

Required: false

Data type: string

resourceManagerNamePrefixDescription: The resource manager prefix to be used as part of the servergenerated resource manager name that is registered with ResourceRecovery Services (RRS). The prefix must contain 1 to 8 alphanumeric(A-Z,a-z,0-9) and national (@,#,$) character only. The prefix name ofDEFAULT is a reserved prefix name that identifies a default serverconfiguration and should not be used for securing server access.

Default value: DEFAULT

Required: false

Data type: string

netscapeLdapFilterPropertiesSpecifies the list of default Netscape Directory Server LDAP filters. PID iscom.ibm.ws.security.registry.ldap.internal.filters.netscape.


Attributes


Default value: (&(uid=%v)(objectclass=inetOrgPerson))

Required: true

Data type: string


Default value:

(&(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))

Required: true

Data type: string


Default value: inetOrgPerson:uid

Required: true

Data type: string


Default value: *:cn

Required: true

Data type: string


Default value:groupOfNames:member;groupOfUniqueNames:uniqueMember

Required: true

Data type: string

oauthProvider

OAuth provider definition. PID is com.ibm.ws.security.oauth20.provider.


Attributes

localStoreRefRequired: false

Data type: Configuration ID of type localStore (string).

databaseStoreRefRequired: false

Data type: Configuration ID of type databaseStore (string).

authorizationGrantLifetimeDescription: Authorization grant lifetime (seconds). The equivalentprovider parameter in the full application server profile isoauth20.max.authorization.grant.lifetime.seconds. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.


Required: false

Data type: string

authorizationCodeLifetimeDescription: Authorization code lifetime (seconds). The equivalentprovider parameter in the full application server profile isoauth20.code.lifetime.seconds. Specify a positive integer followed by aunit of time, which can be hours (h), minutes (m), or seconds (s). Forexample, specify 30 seconds as 30s. You can include multiple values in asingle entry. For example, 1m30s is equivalent to 90 seconds.

Default value: 60

Required: false

Data type: string

authorizationCodeLengthDescription: Length of the generated authorization code. The equivalentprovider parameter in the full application server profile isoauth20.code.length.

Default value: 30

Required: false

Data type: long

accessTokenLifetimeDescription: Time that access token is valid (seconds). The equivalentprovider parameter in the full application server profile isoauth20.token.lifetime.seconds. Specify a positive integer followed by aunit of time, which can be hours (h), minutes (m), or seconds (s). Forexample, specify 30 seconds as 30s. You can include multiple values in asingle entry. For example, 1m30s is equivalent to 90 seconds.

Default value: 3600

Required: false


Data type: string

accessTokenLengthDescription: Length of the generated OAuth access token. The equivalentprovider parameter in the full application server profile isoauth20.access.token.length.

Default value: 40

Required: false

Data type: long

issueRefreshTokenDescription: A value of false disables generation and the use of refreshtokens. The equivalent provider parameter in the full application serverprofile is oauth20.issue.refresh.token.

Default value: true

Required: false

Data type: boolean

refreshTokenLengthDescription: Length of generated refresh token. The equivalent providerparameter in the full application server profile isoauth20.refresh.token.length.

Default value: 50

Required: false

Data type: long

libraryRefDescription: Reference to shared library containing mediator plugin class.

Required: false


allowPublicClientsDescription: A value of false disables the access of public clients asdetailed in the OAuth specification. The equivalent provider parameter inthe full application server profile is oauth20.allow.public.clients.


Required: false

Data type: boolean

authorizationFormTemplateDescription: URL of a custom authorization page template. Theequivalent provider parameter in the full application server profile isoauth20.authorization.form.template.

Default value: template.html

Required: false

Data type: string

authorizationErrorTemplateDescription: URL of a custom authorization error page template. Theequivalent provider parameter in the full application server profile isoauth20.authorization.error.template.


Default value:

Required: false

Data type: string

customLoginURLDescription: URL of a custom login page. The equivalent providerparameter in the full application server profile isoauth20.authorization.loginURL.

Default value: login.jsp

Required: false

Data type: string

autoAuthorizeParamDescription: To use auto authorization, append the autoAuthorizeparameter to requests with a value of true. The equivalent providerparameter in the full application server profile isoauth20.autoauthorize.param.

Default value: autoauthz

Required: false

Data type: string

clientURISubstitutionsDescription: Optional value to replace client URI strings for dynamichostnames. The equivalent provider parameter in the full applicationserver profile is oauth20.client.uri.substitutions.

Required: false

Data type: string

clientTokenCacheSizeDescription: Maximum number of entries in the client token cache. Theequivalent provider parameter in the full application server profile isoauth20.token.userClientTokenLimit.

Default value: 100

Required: false

Data type: long

filterDescription: URI filter selects requests to be authorized by this provider.The equivalent provider parameter in the full application server profile isFilter.

Required: false

Data type: string

characterEncodingDescription: characterEncoding.desc

Required: false

Data type: string

oauthOnlyDescription: If the value is false, fall back to available authentication forrequests with no OAuth access token. The equivalent provider parameter


in the full application server profile is oauthOnly.

Default value: true

Required: false

Data type: boolean

includeTokenInSubjectDescription: If the value is true, add thecom.ibm.wsspi.security.oauth20.token.WSOAuth20Token as a privatecredential. The equivalent provider parameter in the full applicationserver profile is includeToken.

Default value: true

Required: false

Data type: boolean


Sub-elements

localStoreRequired: false

Data type: Element of type localStore.

databaseStoreRequired: false

Data type: Element of type databaseStore.

libraryDescription: Reference to shared library containing mediator plugin class.

Required: false


mediatorClassnameDescription: Mediator plugin class name. The equivalent providerparameter in the full application server profile isoauth20.mediator.classnames.

Required: false

Data type: string

grantTypeDescription: An access token grant type (as detailed in the OAuthspecification) that is allowed for the provider. The equivalent providerparameter in the full application server profile isoauth20.grant.types.allowed.

Required: false

Data type: string

autoAuthorizeClientDescription: Name of a client that is allowed to use auto authorization.The equivalent provider parameter in the full application server profile isoauth20.autoauthorize.clients.

Required: false

Data type: string

oauthRoles

OAuth web application security role map. PID iscom.ibm.ws.security.oauth20.roles.


Attributes

authenticatedRefRequired: false

Data type: List of configuration IDs of type authenticated(comma-separated string).

clientManagerRefRequired: false

Data type: List of configuration IDs of type clientManager(comma-separated string).

Sub-elements

authenticatedRequired: false

Data type: Element of type authenticated.

clientManagerRequired: false

Data type: Element of type clientManager.

permission

The permission for the destination. PID iscom.ibm.ws.messaging.security.permission.

Attributes

nameDescription: The name of the destination for which the permission isdefined.

Required: true

Data type: string

actionsDescription: The actions that are allowed for this permission (the allowedactions are SEND, RECEIVE, CREATE, and BROWSE).

Required: true

Data type: string

pluginConfigurationGenerate plugin configuration. PID is com.ibm.ws.generatePluginConfig.


Attributes

pluginInstallRootDescription: Web container plugin installation position in file system

Default value: .

Required: false

Data type: string

webserverPortDescription: Web server HTTP port

Default value: 80

Required: false

Data type: string

webserverSecurePortDescription: Web server HTTPS port

Default value: 443

Required: false

Data type: string

sslKeyringLocationDescription: Location of SSL keyring

Default value: PATH/FILE

Required: false

Data type: string

sslStashfileLocationDescription: Location of SSL stashfile

Default value: PATH/FILE

Required: false

Data type: string

sslCertlabelDescription: SSL cert label

Default value: REPLACE

Required: false

Data type: string

ipv6PreferredDescription: IPv6 is preferred


Required: false

Data type: boolean


propertiesList of JDBC vendor properties for the data source. For example,databaseName="dbname" serverName="localhost" portNumber="50000". PID iscom.ibm.ws.jdbc.dataSource.properties, and it is the child of complex type“dataSource”.

Attributes

databaseNameDescription: JDBC driver property: databaseName.

Required: false

Data type: string

serverNameDescription: Server where the database is running.

Required: false

Data type: string

portNumberDescription: Port on which to obtain database connections.

Required: false

Data type: int

URLDescription: URL for connecting to the database.

Required: false

Data type: string


Required: false

Data type: string


Required: false


properties.datadirect.sqlserverData source properties for the DataDirect Connect for JDBC driver for MicrosoftSQL Server. PID is com.ibm.ws.jdbc.dataSource.properties.datadirect.sqlserver, andit is the child of complex type “dataSource”.


Attributes


Required: false

Data type: string



Required: false

Data type: string


Default value: 1433

Required: false

Data type: int


Required: false

Data type: string


Required: false


accountingInfoDescription: JDBC driver property: accountingInfo.

Required: false

Data type: string

alternateServersDescription: JDBC driver property: alternateServers.

Required: false

Data type: string

alwaysReportTriggerResultsDescription: JDBC driver property: alwaysReportTriggerResults.

Required: false

Data type: boolean

applicationNameDescription: JDBC driver property: applicationName.

Required: false

Data type: string


authenticationMethodDescription: JDBC driver property: authenticationMethod.

Range:

auto

kerberos

ntlm

userIdPassword

Required: false

Data type: string

bulkLoadBatchSizeDescription: JDBC driver property: bulkLoadBatchSize.

Required: false

Data type: long

bulkLoadOptionsDescription: JDBC driver property: bulkLoadOptions.

Required: false

Data type: long

clientHostNameDescription: JDBC driver property: clientHostName.

Required: false

Data type: string

clientUserDescription: JDBC driver property: clientUser.

Required: false

Data type: string

codePageOverrideDescription: JDBC driver property: codePageOverride.

Required: false

Data type: string

connectionRetryCountDescription: JDBC driver property: connectionRetryCount.

Required: false

Data type: int

connectionRetryDelayDescription: JDBC driver property: connectionRetryDelay. Specify apositive integer followed by a unit of time, which can be hours (h),minutes (m), or seconds (s). For example, specify 30 seconds as 30s. Youcan include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Required: false

Data type: string


convertNullDescription: JDBC driver property: convertNull.

Required: false

Data type: int

dateTimeInputParameterTypeDescription: JDBC driver property: dateTimeInputParameterType.

Range:

auto

dateTime

dateTimeOffset

Required: false

Data type: string

dateTimeOutputParameterTypeDescription: JDBC driver property: dateTimeOutputParameterType.

Range:

auto

dateTime

dateTimeOffset

Required: false

Data type: string

describeInputParametersDescription: JDBC driver property: describeInputParameters.

Range:

describeAll

describeIfDateTime

describeIfString

noDescribe

Required: false

Data type: string

describeOutputParametersDescription: JDBC driver property: describeOutputParameters.

Range:

describeAll

describeIfDateTime

describeIfString

noDescribe

Required: false

Data type: string

enableBulkLoad


Description: JDBC driver property: enableBulkLoad.

Required: false

Data type: boolean

enableCancelTimeoutDescription: JDBC driver property: enableCancelTimeout.

Required: false

Data type: boolean

encryptionMethodDescription: JDBC driver property: encryptionMethod.

Range:

noEncryption

loginSSL

requestSSL

SSL

Required: false

Data type: string

failoverGranularityDescription: JDBC driver property: failoverGranularity.

Range:

atomic

atomicWithRepositioning

disableIntegrityCheck

nonAtomic

Required: false

Data type: string

failoverModeDescription: JDBC driver property: failoverMode.

Range:

connect

extended

select

Required: false

Data type: string

failoverPreconnectDescription: JDBC driver property: failoverPreconnect.

Required: false

Data type: boolean

hostNameInCertificateDescription: JDBC driver property: hostNameInCertificate.


Required: false

Data type: string

initializationStringDescription: JDBC driver property: initializationString.

Required: false

Data type: string

insensitiveResultSetBufferSizeDescription: JDBC driver property: insensitiveResultSetBufferSize.

Required: false

Data type: int

javaDoubleToStringDescription: JDBC driver property: javaDoubleToString.

Required: false

Data type: boolean

JDBCBehaviorDescription: JDBC driver property: JDBCBehavior. Values are: 0 (JDBC4.0) or 1 (JDBC 3.0).

Default value: 0

Range:

0 JDBC 4.0

1 JDBC 3.0

Required: false

Data type: int

loadBalancingDescription: JDBC driver property: loadBalancing.

Required: false

Data type: boolean

loginTimeoutDescription: JDBC driver property: loginTimeout. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Required: false

Data type: string

longDataCacheSizeDescription: JDBC driver property: longDataCacheSize.

Required: false

Data type: int

netAddressDescription: JDBC driver property: netAddress.

Required: false


Data type: string

packetSizeDescription: JDBC driver property: packetSize.

Required: false

Data type: int

queryTimeoutDescription: JDBC driver property: queryTimeout. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Required: false

Data type: string

resultsetMetaDataOptionsDescription: JDBC driver property: resultsetMetaDataOptions.

Required: false

Data type: int

selectMethodDescription: JDBC driver property: selectMethod.

Range:

cursor

direct

Required: false

Data type: string

snapshotSerializableDescription: JDBC driver property: snapshotSerializable.

Required: false

Data type: boolean

spyAttributesDescription: JDBC driver property: spyAttributes.

Required: false

Data type: string

stringInputParameterTypeDescription: JDBC driver property: stringInputParameterType.

Default value: varchar

Range:

nvarchar

varchar

Required: false

Data type: string

stringOutputParameterType


Description: JDBC driver property: stringOutputParameterType.

Default value: varchar

Range:

nvarchar

varchar

Required: false

Data type: string

suppressConnectionWarningsDescription: JDBC driver property: suppressConnectionWarnings.

Required: false

Data type: boolean

transactionModeDescription: JDBC driver property: transactionMode.

Range:

explicit

implicit

Required: false

Data type: string

truncateFractionalSecondsDescription: JDBC driver property: truncateFractionalSeconds.

Required: false

Data type: boolean

trustStoreDescription: JDBC driver property: trustStore.

Required: false

Data type: string

trustStorePasswordDescription: JDBC driver property: trustStorePassword.

Required: false


useServerSideUpdatableCursorsDescription: JDBC driver property: useServerSideUpdatableCursors.

Required: false

Data type: boolean

validateServerCertificateDescription: JDBC driver property: validateServerCertificate.

Required: false

Data type: boolean

XATransactionGroupDescription: JDBC driver property: XATransactionGroup.


Required: false

Data type: string

XMLDescribeTypeDescription: JDBC driver property: XMLDescribeType.

Range:

longvarbinary

longvarchar

Required: false

Data type: string

properties.db2.i.nativeData source properties for the IBM DB2 for i Native JDBC driver. PID iscom.ibm.ws.jdbc.dataSource.properties.db2.i.native, and it is the child of complextype “dataSource”.


Attributes


Default value: *LOCAL

Required: false

Data type: string


Required: false

Data type: string


Required: false


accessDescription: JDBC driver property: access.

Default value: all

Range:

all

read call

read only

Required: false

Data type: string

autoCommitDescription: JDBC driver property: autoCommit.

Default value: true

Required: false

Data type: boolean

batchStyleDescription: JDBC driver property: batchStyle.

Default value: 2.0

Range:

2.0

2.1

Required: false

Data type: string

behaviorOverrideDescription: JDBC driver property: behaviorOverride.


Required: false

Data type: int

blockSizeDescription: JDBC driver property: blockSize.

Default value: 32

Range:

0

8

16

32

64

128

256

512

Required: false

Data type: int

cursorHoldDescription: JDBC driver property: cursorHold.


Required: false

Data type: boolean

cursorSensitivityDescription: JDBC driver property: cursorSensitivity. Values are: 0(TYPE_SCROLL_SENSITIVE_STATIC), 1(TYPE_SCROLL_SENSITIVE_DYNAMIC), 2(TYPE_SCROLL_ASENSITIVE).

Default value: asensitive

Range:

asensitive

sensitive

Required: false

Data type: string

dataTruncationDescription: JDBC driver property: dataTruncation.

Default value: true

Required: false

Data type: string

dateFormatDescription: JDBC driver property: dateFormat.

Range:


dmy

eur

mdy

iso

jis

julian

usa

ymd

Required: false

Data type: string

dateSeparatorDescription: JDBC driver property: dateSeparator.

Range:

/ The forward slash character (/).

- The dash character (-).

. The period character (.).

, The comma character (,).

b The character b

Required: false

Data type: string

decimalSeparatorDescription: JDBC driver property: decimalSeparator.

Range:



Required: false

Data type: string

directMapDescription: JDBC driver property: directMap.

Default value: true

Required: false

Data type: boolean

doEscapeProcessingDescription: JDBC driver property: doEscapeProcessing.

Default value: true

Required: false

Data type: boolean

fullErrorsDescription: JDBC driver property: fullErrors.


Required: false

Data type: boolean

librariesDescription: JDBC driver property: libraries.

Required: false

Data type: string

lobThresholdDescription: JDBC driver property: lobThreshold.

Default value: 0

Required: false

Data type: int

lockTimeoutDescription: JDBC driver property: lockTimeout. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Default value: 0

Required: false

Data type: string


Required: false

Data type: string

maximumPrecisionDescription: JDBC driver property: maximumPrecision.

Default value: 31

Range:

31

63

Required: false

Data type: int

maximumScaleDescription: JDBC driver property: maximumScale.

Default value: 31

Required: false

Data type: int

minimumDivideScale


Description: JDBC driver property: minimumDivideScale.

Default value: 0

Required: false

Data type: int

networkProtocolDescription: JDBC driver property: networkProtocol.

Required: false

Data type: int


Required: false

Data type: int

prefetchDescription: JDBC driver property: prefetch.

Default value: true

Required: false

Data type: boolean

queryOptimizeGoalDescription: JDBC driver property: queryOptimizeGoal. Values are: 1(*FIRSTIO) or 2 (*ALLIO).

Default value: 2

Range:

1 *FIRSTIO

2 *ALLIO

Required: false

Data type: string

reuseObjectsDescription: JDBC driver property: reuseObjects.

Default value: true

Required: false

Data type: boolean


Required: false

Data type: string

serverTraceCategoriesDescription: JDBC driver property: serverTraceCategories.

Default value: 0

Required: false

Data type: int


systemNamingDescription: JDBC driver property: systemNaming.


Required: false

Data type: boolean

timeFormatDescription: JDBC driver property: timeFormat.

Range:

eur

hms

iso

jis

usa

Required: false

Data type: string

timeSeparatorDescription: JDBC driver property: timeSeparator.

Range:

: The colon character (:).



b The character b

Required: false

Data type: string

traceDescription: JDBC driver property: trace.

Required: false

Data type: boolean

transactionTimeoutDescription: JDBC driver property: transactionTimeout. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Default value: 0

Required: false

Data type: string

translateBinaryDescription: JDBC driver property: translateBinary.


Required: false


Data type: boolean

translateHexDescription: JDBC driver property: translateHex.

Default value: character

Range:

binary

character

Required: false

Data type: string

useBlockInsertDescription: JDBC driver property: useBlockInsert.


Required: false

Data type: boolean

properties.db2.i.toolboxData source properties for the IBM DB2 for i Toolbox JDBC driver. PID iscom.ibm.ws.jdbc.dataSource.properties.db2.i.toolbox, and it is the child of complextype “dataSource”.


Attributes


Required: true

Data type: string


Required: false

Data type: string


Required: false

Data type: string


Required: false


accessDescription: JDBC driver property: access.

Default value: all

Range:

all

read call

read only

Required: false

Data type: string

behaviorOverrideDescription: JDBC driver property: behaviorOverride.

Required: false

Data type: int

bidiImplicitReorderingDescription: JDBC driver property: bidiImplicitReordering.

Default value: true

Required: false

Data type: boolean

bidiNumericOrderingDescription: JDBC driver property: bidiNumericOrdering.


Required: false


Data type: boolean

bidiStringTypeDescription: JDBC driver property: bidiStringType.

Required: false

Data type: int

bigDecimalDescription: JDBC driver property: bigDecimal.

Default value: true

Required: false

Data type: boolean

blockCriteriaDescription: JDBC driver property: blockCriteria. Values are: 0 (no recordblocking), 1 (block if FOR FETCH ONLY is specified), 2 (block if FORUPDATE is specified).

Default value: 2

Range:

0

1

2

Required: false

Data type: int

blockSizeDescription: JDBC driver property: blockSize.

Default value: 32

Range:

0

8

16

32

64

128

256

512

Required: false

Data type: int

cursorHoldDescription: JDBC driver property: cursorHold.


Required: false

Data type: boolean


cursorSensitivityDescription: JDBC driver property: cursorSensitivity. Values are: 0(TYPE_SCROLL_SENSITIVE_STATIC), 1(TYPE_SCROLL_SENSITIVE_DYNAMIC), 2(TYPE_SCROLL_ASENSITIVE).

Default value: asensitive

Range:

asensitive

insensitive

sensitive

Required: false

Data type: string

dataCompressionDescription: JDBC driver property: dataCompression.

Default value: true

Required: false

Data type: boolean

dataTruncationDescription: JDBC driver property: dataTruncation.

Default value: true

Required: false

Data type: boolean

dateFormatDescription: JDBC driver property: dateFormat.

Range:

dmy

eur

mdy

iso

jis

julian

usa

ymd

Required: false

Data type: string

dateSeparatorDescription: JDBC driver property: dateSeparator.

Range:

/ The forward slash character (/).

- The dash character (-).




The space character ( ).

Required: false

Data type: string

decimalSeparatorDescription: JDBC driver property: decimalSeparator.

Range:



Required: false

Data type: string

driverDescription: JDBC driver property: driver.

Default value: toolbox

Range:

native

toolbox

Required: false

Data type: string

errorsDescription: JDBC driver property: errors.

Default value: basic

Range:

basic

full

Required: false

Data type: string

extendedDynamicDescription: JDBC driver property: extendedDynamic.


Required: false

Data type: boolean

extendedMetaDataDescription: JDBC driver property: extendedMetaData.


Required: false

Data type: boolean

fullOpen


Description: JDBC driver property: fullOpen.


Required: false

Data type: boolean

holdInputLocatorsDescription: JDBC driver property: holdInputLocators.

Default value: true

Required: false

Data type: boolean

holdStatementsDescription: JDBC driver property: holdStatements.


Required: false

Data type: boolean

isolationLevelSwitchingSupportDescription: JDBC driver property: isolationLevelSwitchingSupport.


Required: false

Data type: boolean

keepAliveDescription: JDBC driver property: keepAlive.

Required: false

Data type: boolean

lazyCloseDescription: JDBC driver property: lazyClose.


Required: false

Data type: boolean

librariesDescription: JDBC driver property: libraries.

Required: false

Data type: string

lobThresholdDescription: JDBC driver property: lobThreshold.

Default value: 0

Required: false

Data type: int

loginTimeoutDescription: JDBC driver property: loginTimeout. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can include


multiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Required: false

Data type: string

maximumPrecisionDescription: JDBC driver property: maximumPrecision.

Default value: 31

Range:

31

63 64

Required: false

Data type: int

maximumScaleDescription: JDBC driver property: maximumScale.

Default value: 31

Required: false

Data type: int

metaDataSourceDescription: JDBC driver property: metaDataSource.

Default value: 1

Required: false

Data type: int

minimumDivideScaleDescription: JDBC driver property: minimumDivideScale.

Default value: 0

Required: false

Data type: int

namingDescription: JDBC driver property: naming.

Default value: sql

Range:

sql

system

Required: false

Data type: string

packageDescription: JDBC driver property: package.

Required: false

Data type: string

packageAdd


Description: JDBC driver property: packageAdd.

Default value: true

Required: false

Data type: boolean

packageCCSIDDescription: JDBC driver property: packageCCSID. Values are: 1200(UCS-2) or 13488 (UTF-16).


Range:

1200 1200 (UCS-2)

13488 13488 (UTF-16)

Required: false

Data type: int

packageCacheDescription: JDBC driver property: packageCache.


Required: false

Data type: boolean

packageCriteriaDescription: JDBC driver property: packageCriteria.

Default value: default

Range:

default

select

Required: false

Data type: string

packageErrorDescription: JDBC driver property: packageError.

Default value: warning

Range:

exception

warning

none

Required: false

Data type: string

packageLibraryDescription: JDBC driver property: packageLibrary.

Default value: QGPL

Required: false


Data type: string

prefetchDescription: JDBC driver property: prefetch.

Default value: true

Required: false

Data type: boolean

promptDescription: JDBC driver property: prompt.


Required: false

Data type: boolean

proxyServerDescription: JDBC driver property: proxyServer.

Required: false

Data type: string

qaqqiniLibraryDescription: JDBC driver property: qaqqiniLibrary.

Required: false

Data type: string

queryOptimizeGoalDescription: JDBC driver property: queryOptimizeGoal. Values are: 1(*FIRSTIO) or 2 (*ALLIO).

Default value: 0

Required: false

Data type: int

receiveBufferSizeDescription: JDBC driver property: receiveBufferSize.

Required: false

Data type: int

remarksDescription: JDBC driver property: remarks.

Default value: system

Range:

sql

system

Required: false

Data type: string

rollbackCursorHoldDescription: JDBC driver property: rollbackCursorHold.



Required: false

Data type: boolean

savePasswordWhenSerializedDescription: JDBC driver property: savePasswordWhenSerialized.


Required: false

Data type: boolean

secondaryUrlDescription: JDBC driver property: secondaryUrl.

Required: false

Data type: string

secureDescription: JDBC driver property: secure.


Required: false

Data type: boolean

sendBufferSizeDescription: JDBC driver property: sendBufferSize.

Required: false

Data type: int

serverTraceCategoriesDescription: JDBC driver property: serverTraceCategories.

Default value: 0

Required: false

Data type: int

soLingerDescription: JDBC driver property: soLinger. Specify a positive integerfollowed by a unit of time, which can be hours (h), minutes (m), orseconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Required: false

Data type: string

soTimeoutDescription: JDBC driver property: soTimeout. Specify a positive integerfollowed by a unit of time, which can be hours (h), minutes (m), seconds(s), or milliseconds (ms). For example, specify 500 milliseconds as 500ms.You can include multiple values in a single entry. For example, 1s500ms isequivalent to 1.5 seconds.

Required: false

Data type: string

sortDescription: JDBC driver property: sort.


Default value: hex

Range:

hex

language

table

Required: false

Data type: string

sortLanguageDescription: JDBC driver property: sortLanguage.

Required: false

Data type: string

sortTableDescription: JDBC driver property: sortTable.

Required: false

Data type: string

sortWeightDescription: JDBC driver property: sortWeight.

Range:

shared

unqiueunique

Required: false

Data type: string

tcpNoDelayDescription: JDBC driver property: tcpNoDelay.

Required: false

Data type: boolean

threadUsedDescription: JDBC driver property: threadUsed.

Default value: true

Required: false

Data type: boolean

timeFormatDescription: JDBC driver property: timeFormat.

Range:

eur

hms

iso

jis

usa


Required: false

Data type: string

timeSeparatorDescription: JDBC driver property: timeSeparator.

Range:

: The colon character (:).



The space character ( ).

Required: false

Data type: string

toolboxTraceDescription: JDBC driver property: toolboxTrace.

Range:

none

datastream

diagnostic

error

information

warning

conversion

proxy

pcml

jdbc

all

thread

Required: false

Data type: string

traceDescription: JDBC driver property: trace.

Required: false

Data type: boolean

translateBinaryDescription: JDBC driver property: translateBinary.


Required: false

Data type: boolean

translateBooleanDescription: JDBC driver property: translateBoolean.


Default value: true

Required: false

Data type: boolean

translateHexDescription: JDBC driver property: translateHex.

Default value: character

Range:

binary

character

Required: false

Data type: string

trueAutoCommitDescription: JDBC driver property: trueAutoCommit.


Required: false

Data type: boolean

xaLooselyCoupledSupportDescription: JDBC driver property: xaLooselyCoupledSupport.

Default value: 0

Required: false

Data type: int

properties.db2.jccData source properties for the IBM Data Server Driver for JDBC and SQLJ for DB2.PID is com.ibm.ws.jdbc.dataSource.properties.db2.jcc, and it is the child of complextype “dataSource”.


Attributes

driverTypeDescription: JDBC driver property: driverType.

Default value: 4

Range:

2 Type 2 JDBC driver.

4 Type 4 JDBC driver.

Required: false

Data type: int


Required: false

Data type: string



Required: false

Data type: string



Required: false

Data type: int


Required: false

Data type: string


Required: false


activateDatabaseDescription: JDBC driver property: activateDatabase.

Required: false

Data type: int

alternateGroupDatabaseNameDescription: JDBC driver property: alternateGroupDatabaseName.

Required: false


Data type: string

alternateGroupPortNumberDescription: JDBC driver property: alternateGroupPortNumber.

Required: false

Data type: string

alternateGroupServerNameDescription: JDBC driver property: alternateGroupServerName.

Required: false

Data type: string

blockingReadConnectionTimeoutDescription: JDBC driver property: blockingReadConnectionTimeout.Specify a positive integer followed by a unit of time, which can be hours(h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s.You can include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Required: false

Data type: string

clientAccountingInformationDescription: JDBC driver property: clientAccountingInformation.

Required: false

Data type: string

clientApplicationInformationDescription: JDBC driver property: clientApplicationInformation.

Required: false

Data type: string

clientRerouteServerListJNDINameDescription: JDBC driver property: clientRerouteServerListJNDIName.

Required: false

Data type: string

clientUserDescription: JDBC driver property: clientUser.

Required: false

Data type: string

clientWorkstationDescription: JDBC driver property: clientWorkstation.

Required: false

Data type: string

connectionCloseWithInFlightTransactionDescription: JDBC driver property:connectionCloseWithInFlightTransaction.

Range:


1 CONNECTION_CLOSE_WITH_EXCEPTION

2 CONNECTION_CLOSE_WITH_ROLLBACK

Required: false

Data type: int

currentAlternateGroupEntryDescription: JDBC driver property: currentAlternateGroupEntry.

Required: false

Data type: int

currentFunctionPathDescription: JDBC driver property: currentFunctionPath.

Required: false

Data type: string

currentLocaleLcCtypeDescription: JDBC driver property: currentLocaleLcCtype.

Required: false

Data type: string

currentLockTimeoutDescription: JDBC driver property: currentLockTimeout. Specify apositive integer followed by a unit of time, which can be hours (h),minutes (m), or seconds (s). For example, specify 30 seconds as 30s. Youcan include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Required: false

Data type: string

currentPackagePathDescription: JDBC driver property: currentPackagePath.

Required: false

Data type: string

currentPackageSetDescription: JDBC driver property: currentPackageSet.

Required: false

Data type: string

currentSQLIDDescription: JDBC driver property: currentSQLID.

Required: false

Data type: string

currentSchemaDescription: JDBC driver property: currentSchema.

Required: false

Data type: string

cursorSensitivity


Description: JDBC driver property: cursorSensitivity. Values are: 0(TYPE_SCROLL_SENSITIVE_STATIC), 1(TYPE_SCROLL_SENSITIVE_DYNAMIC), 2(TYPE_SCROLL_ASENSITIVE).

Range:

0 TYPE_SCROLL_SENSITIVE_STATIC

1 TYPE_SCROLL_SENSITIVE_DYNAMIC

2 TYPE_SCROLL_ASENSITIVE

Required: false

Data type: int

deferPreparesDescription: JDBC driver property: deferPrepares.

Default value: true

Required: false

Data type: boolean

enableAlternateGroupSeamlessACRDescription: JDBC driver property: enableAlternateGroupSeamlessACR.

Required: false

Data type: boolean

enableClientAffinitiesListDescription: JDBC driver property: enableClientAffinitiesList. Values are:1 (YES) or 2 (NO).

Range:

1 YES

2 NO

Required: false

Data type: int

enableExtendedDescribeDescription: JDBC driver property: enableExtendedDescribe.

Range:

1 YES

2 NO

Required: false

Data type: int

enableExtendedIndicatorsDescription: JDBC driver property: enableExtendedIndicators.

Range:

1 YES

2 NO

Required: false


Data type: int

enableNamedParameterMarkersDescription: JDBC driver property: enableNamedParameterMarkers.Values are: 1 (YES) or 2 (NO).

Range:

1 YES

2 NO

Required: false

Data type: int

enableSeamlessFailoverDescription: JDBC driver property: enableSeamlessFailover. Values are: 1(YES) or 2 (NO).

Range:

1 YES

2 NO

Required: false

Data type: int

enableSysplexWLBDescription: JDBC driver property: enableSysplexWLB.

Required: false

Data type: boolean

fetchSizeDescription: JDBC driver property: fetchSize.

Required: false

Data type: int

fullyMaterializeInputStreamsDescription: JDBC driver property: fullyMaterializeInputStreams.

Required: false

Data type: boolean

fullyMaterializeInputStreamsOnBatchExecutionDescription: JDBC driver property:fullyMaterializeInputStreamsOnBatchExecution.

Range:

1 YES

2 NO

Required: false

Data type: int

fullyMaterializeLobDataDescription: JDBC driver property: fullyMaterializeLobData.

Required: false


Data type: boolean

implicitRollbackOptionDescription: JDBC driver property: implicitRollbackOption.

Range:

0 IMPLICIT_ROLLBACK_OPTION_NOT_SET

1 IMPLICIT_ROLLBACK_OPTION_NOT_CLOSE_CONNECTION

2 IMPLICIT_ROLLBACK_OPTION_CLOSE_CONNECTION

Required: false

Data type: int

interruptProcessingModeDescription: JDBC driver property: interruptProcessingMode.

Range:

0 INTERRUPT_PROCESSING_MODE_DISABLED

1 INTERRUPT_PROCESSING_MODE_STATEMENT_CANCEL

2 INTERRUPT_PROCESSING_MODE_CLOSE_SOCKET

Required: false

Data type: int

keepAliveTimeOutDescription: JDBC driver property: keepAliveTimeOut. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Required: false

Data type: string

keepDynamicDescription: JDBC driver property: keepDynamic.

Required: false

Data type: int

kerberosServerPrincipalDescription: JDBC driver property: kerberosServerPrincipal.

Required: false

Data type: string


Required: false

Data type: string


maxConnCachedParamBufferSizeDescription: JDBC driver property: maxConnCachedParamBufferSize.

Required: false

Data type: int

maxRetriesForClientRerouteDescription: JDBC driver property: maxRetriesForClientReroute.

Required: false

Data type: int

profileNameDescription: JDBC driver property: profileName.

Required: false

Data type: string

queryCloseImplicitDescription: JDBC driver property: queryCloseImplicit. Values are: 1(QUERY_CLOSE_IMPLICIT_YES) or 2 (QUERY_CLOSE_IMPLICIT_NO).

Range:

1 QUERY_CLOSE_IMPLICIT_YES

2 QUERY_CLOSE_IMPLICIT_NO

Required: false

Data type: int

queryDataSizeDescription: JDBC driver property: queryDataSize.

Required: false

Data type: int

queryTimeoutInterruptProcessingModeDescription: JDBC driver property:queryTimeoutInterruptProcessingMode.

Range:

1 INTERRUPT_PROCESSING_MODE_STATEMENT_CANCEL

2 INTERRUPT_PROCESSING_MODE_CLOSE_SOCKET

Required: false

Data type: int

readOnlyDescription: JDBC driver property: readOnly.

Required: false

Data type: boolean

recordTemporalHistoryDescription: recordTemporalHistory.desc

Range:

1 YES


2 NO

Required: false

Data type: int

resultSetHoldabilityDescription: JDBC driver property: resultSetHoldability. Values are: 1(HOLD_CURSORS_OVER_COMMIT) or 2(CLOSE_CURSORS_AT_COMMIT).

Range:

1 HOLD_CURSORS_OVER_COMMIT

2 CLOSE_CURSORS_AT_COMMIT

Required: false

Data type: int

resultSetHoldabilityForCatalogQueriesDescription: JDBC driver property:resultSetHoldabilityForCatalogQueries. Values are: 1(HOLD_CURSORS_OVER_COMMIT) or 2(CLOSE_CURSORS_AT_COMMIT).

Range:



Required: false

Data type: int

retrieveMessagesFromServerOnGetMessageDescription: JDBC driver property:retrieveMessagesFromServerOnGetMessage.

Default value: true

Required: false

Data type: boolean

retryIntervalForClientRerouteDescription: JDBC driver property: retryIntervalForClientReroute. Specifya positive integer followed by a unit of time, which can be hours (h),minutes (m), or seconds (s). For example, specify 30 seconds as 30s. Youcan include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Required: false

Data type: string

securityMechanismDescription: JDBC driver property: securityMechanism. Values are: 3(CLEAR_TEXT_PASSWORD_SECURITY), 4 (USER_ONLY_SECURITY), 7(ENCRYPTED_PASSWORD_SECURITY), 9(ENCRYPTED_USER_AND_PASSWORD_SECURITY), 11(KERBEROS_SECURITY), 12(ENCRYPTED_USER_AND_DATA_SECURITY"),(ENCRYPTED_USER_PASSWORD_AND_DATA_SECURITY"), 15(PLUGIN_SECURITY), 16 (ENCRYPTED_USER_ONLY_SECURITY).


Range:

3 CLEAR_TEXT_PASSWORD_SECURITY

4 USER_ONLY_SECURITY

7 ENCRYPTED_PASSWORD_SECURITY

9 ENCRYPTED_USER_AND_PASSWORD_SECURITY

11 KERBEROS_SECURITY

12 ENCRYPTED_USER_AND_DATA_SECURITY

13 ENCRYPTED_USER_PASSWORD_AND_DATA_SECURITY

15 PLUGIN_SECURITY

16 ENCRYPTED_USER_ONLY_SECURITY

Required: false

Data type: int

sendDataAsIsDescription: JDBC driver property: sendDataAsIs.

Required: false

Data type: boolean

sessionTimeZoneDescription: JDBC driver property: sessionTimeZone.

Required: false

Data type: string

sqljCloseStmtsWithOpenResultSetDescription: JDBC driver property: sqljCloseStmtsWithOpenResultSet.

Required: false

Data type: boolean

sqljEnableClassLoaderSpecificProfilesDescription: JDBC driver property: sqljEnableClassLoaderSpecificProfiles.

Required: false

Data type: boolean

sslConnectionDescription: JDBC driver property: sslConnection.

Required: false

Data type: boolean

streamBufferSizeDescription: JDBC driver property: streamBufferSize.

Required: false

Data type: int

stripTrailingZerosForDecimalNumbersDescription: JDBC driver property:stripTrailingZerosForDecimalNumbers.

Range:


1 YES

2 NO

Required: false

Data type: int

sysSchemaDescription: JDBC driver property: sysSchema.

Required: false

Data type: string

timerLevelForQueryTimeOutDescription: JDBC driver property: timerLevelForQueryTimeOut.

Range:

-1 QUERYTIMEOUT_DISABLED

1 QUERYTIMEOUT_STATEMENT_LEVEL

2 QUERYTIMEOUT_CONNECTION_LEVEL

Required: false

Data type: int

traceDirectoryDescription: JDBC driver property: traceDirectory.

Required: false

Data type: string

traceFileDescription: JDBC driver property: traceFile.

Required: false

Data type: string

traceFileAppendDescription: JDBC driver property: traceFileAppend.

Required: false

Data type: boolean

traceFileCountDescription: JDBC driver property: traceFileCount.

Required: false

Data type: int

traceFileSizeDescription: JDBC driver property: traceFileSize.

Required: false

Data type: int

traceLevelDescription: Bitwise combination of the following constant values:TRACE_NONE=0, TRACE_CONNECTION_CALLS=1,


TRACE_STATEMENT_CALLS=2, TRACE_RESULT_SET_CALLS=4,TRACE_DRIVER_CONFIGURATION=16, TRACE_CONNECTS=32,TRACE_DRDA_FLOWS=64, TRACE_RESULT_SET_META_DATA=128,TRACE_PARAMETER_META_DATA=256, TRACE_DIAGNOSTICS=512,TRACE_SQLJ=1024, TRACE_META_CALLS=8192,TRACE_DATASOURCE_CALLS=16384,TRACE_LARGE_OBJECT_CALLS=32768,TRACE_SYSTEM_MONITOR=131072, TRACE_TRACEPOINTS=262144,TRACE_ALL=-1.

Default value: 0

Required: false

Data type: int

traceOptionDescription: JDBC driver property: traceOption

Range:

0

1

Required: false

Data type: int

translateForBitDataDescription: JDBC driver property: translateForBitData.

Range:

1 HEX_REPRESENTATION

2 SERVER_ENCODING_REPRESENTATION

Required: false

Data type: int

updateCountForBatchDescription: JDBC driver property: updateCountForBatch.

Range:

1 NO_UPDATE_COUNT

2 TOTAL_UPDATE_COUNT

Required: false

Data type: int

useCachedCursorDescription: JDBC driver property: useCachedCursor.

Required: false

Data type: boolean

useIdentityValLocalForAutoGeneratedKeysDescription: JDBC driver property:useIdentityValLocalForAutoGeneratedKeys.

Required: false


Data type: boolean

useJDBC4ColumnNameAndLabelSemanticsDescription: JDBC driver property:useJDBC4ColumnNameAndLabelSemantics. Values are: 1 (YES) or 2(NO).

Range:

1 YES

2 NO

Required: false

Data type: int

useJDBC41DefinitionForGetColumnsDescription: JDBC driver property: useJDBC41DefinitionForGetColumns.

Range:

1 YES

2 NO

Required: false

Data type: int

useTransactionRedirectDescription: JDBC driver property: useTransactionRedirect.

Required: false

Data type: boolean

xaNetworkOptimizationDescription: JDBC driver property: xaNetworkOptimization.

Required: false

Data type: boolean

properties.derby.clientData source properties for Derby Network Client JDBC driver. PID iscom.ibm.ws.jdbc.dataSource.properties.derby.client, and it is the child of complextype “dataSource”.


Attributes

createDatabaseDescription: JDBC driver property: createDatabase.

Range:

create When the first connection is established, automatically create thedatabase if it doesn't exist.

false Do not automatically create the database.

Required: false

Data type: string


Required: false

Data type: string



Required: false

Data type: string


Default value: 1527

Required: false

Data type: int


Required: false

Data type: string


Required: false


connectionAttributesDescription: JDBC driver property: connectionAttributes.

Required: false

Data type: string

loginTimeoutDescription: JDBC driver property: loginTimeout. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90


seconds.

Required: false

Data type: string

retrieveMessageTextDescription: JDBC driver property: retrieveMessageText.

Default value: true

Required: false

Data type: boolean

securityMechanismDescription: JDBC driver property: securityMechanism. Values are: 3(CLEAR_TEXT_PASSWORD_SECURITY), 4 (USER_ONLY_SECURITY), 7(ENCRYPTED_PASSWORD_SECURITY), 8(STRONG_PASSWORD_SUBSTITUTE_SECURITY), 9(ENCRYPTED_USER_AND_PASSWORD_SECURITY).

Default value: 3

Range:




8 STRONG_PASSWORD_SUBSTITUTE_SECURITY


Required: false

Data type: short

shutdownDatabaseDescription: JDBC driver property: shutdownDatabase.

Range:

shutdownShut down the database when a connection is attempted.

false Do not shut down the database.

Required: false

Data type: string

sslDescription: JDBC driver property: ssl.

Range:

basic

peerAuthentication

off

Required: false

Data type: string



Required: false

Data type: string


Required: false

Data type: string


Required: false

Data type: boolean

traceLevelDescription: Bitwise combination of the following constant values:TRACE_NONE=0, TRACE_CONNECTION_CALLS=1,TRACE_STATEMENT_CALLS=2, TRACE_RESULT_SET_CALLS=4,TRACE_DRIVER_CONFIGURATION=16, TRACE_CONNECTS=32,TRACE_DRDA_FLOWS=64, TRACE_RESULT_SET_META_DATA=128,TRACE_PARAMETER_META_DATA=256, TRACE_DIAGNOSTICS=512,TRACE_XA_CALLS=2048, TRACE_ALL=-1.

Required: false

Data type: int

properties.derby.embeddedData source properties for Derby Embedded JDBC driver. PID iscom.ibm.ws.jdbc.dataSource.properties.derby.embedded, and it is the child ofcomplex type “dataSource”.


Attributes

createDatabaseDescription: JDBC driver property: createDatabase.

Range:

create When the first connection is established, automatically create thedatabase if it doesn't exist.

false Do not automatically create the database.

Required: false

Data type: string


Required: false

Data type: string


Required: false

Data type: string


Required: false


connectionAttributesDescription: JDBC driver property: connectionAttributes.

Required: false

Data type: string


Required: false

Data type: string

shutdownDatabaseDescription: JDBC driver property: shutdownDatabase.

Range:

shutdownShut down the database when a connection is attempted.

false Do not shut down the database.

Required: false


Data type: string

properties.informixData source properties for the Informix® JDBC driver. PID iscom.ibm.ws.jdbc.dataSource.properties.informix, and it is the child of complex type“dataSource”.


Attributes


Required: false

Data type: string

ifxIFXHOSTDescription: JDBC driver property: ifxIFXHOST.


Required: false

Data type: string


Required: false

Data type: string


Default value: 1526

Required: false

Data type: int


Required: false

Data type: string


Required: false


ifxCLIENT_LOCALEDescription: JDBC driver property: ifxCLIENT_LOCALE.

Required: false

Data type: string

ifxCPMAgeLimitDescription: JDBC driver property: ifxCPMAgeLimit. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Required: false

Data type: string

ifxCPMInitPoolSize


Description: JDBC driver property: ifxCPMInitPoolSize.

Required: false

Data type: int

ifxCPMMaxConnectionsDescription: JDBC driver property: ifxCPMMaxConnections.

Required: false

Data type: int

ifxCPMMaxPoolSizeDescription: JDBC driver property: ifxCPMMaxPoolSize.

Required: false

Data type: int

ifxCPMMinAgeLimitDescription: JDBC driver property: ifxCPMMinAgeLimit. Specify apositive integer followed by a unit of time, which can be hours (h),minutes (m), or seconds (s). For example, specify 30 seconds as 30s. Youcan include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Required: false

Data type: string

ifxCPMMinPoolSizeDescription: JDBC driver property: ifxCPMMinPoolSize.

Required: false

Data type: int

ifxCPMServiceIntervalDescription: JDBC driver property: ifxCPMServiceInterval. Specify apositive integer followed by a unit of time, which can be hours (h),minutes (m), seconds (s), or milliseconds (ms). For example, specify 500milliseconds as 500ms. You can include multiple values in a single entry.For example, 1s500ms is equivalent to 1.5 seconds.

Required: false

Data type: string

ifxDBANSIWARNDescription: JDBC driver property: ifxDBANSIWARN.

Required: false

Data type: boolean

ifxDBCENTURYDescription: JDBC driver property: ifxDBCENTURY.

Required: false

Data type: string

ifxDBDATEDescription: JDBC driver property: ifxDBDATE.

Required: false

Data type: string


ifxDBSPACETEMPDescription: JDBC driver property: ifxDBSPACETEMP.

Required: false

Data type: string

ifxDBTEMPDescription: JDBC driver property: ifxDBTEMP.

Required: false

Data type: string

ifxDBTIMEDescription: JDBC driver property: ifxDBTIME.

Required: false

Data type: string

ifxDBUPSPACEDescription: JDBC driver property: ifxDBUPSPACE.

Required: false

Data type: string

ifxDB_LOCALEDescription: JDBC driver property: ifxDB_LOCALE.

Required: false

Data type: string

ifxDELIMIDENTDescription: JDBC driver property: ifxDELIMIDENT.

Required: false

Data type: boolean

ifxENABLE_TYPE_CACHEDescription: JDBC driver property: ifxENABLE_TYPE_CACHE.

Required: false

Data type: boolean

ifxFET_BUF_SIZEDescription: JDBC driver property: ifxFET_BUF_SIZE.

Required: false

Data type: int

ifxGL_DATEDescription: JDBC driver property: ifxGL_DATE.

Required: false

Data type: string

ifxGL_DATETIMEDescription: JDBC driver property: ifxGL_DATETIME.

Required: false

Data type: string

ifxIFX_AUTOFREE


Description: JDBC driver property: ifxIFX_AUTOFREE.

Required: false

Data type: boolean

ifxIFX_DIRECTIVESDescription: JDBC driver property: ifxIFX_DIRECTIVES.

Required: false

Data type: string

ifxIFX_LOCK_MODE_WAITDescription: JDBC driver property: ifxIFX_LOCK_MODE_WAIT. Specifya positive integer followed by a unit of time, which can be hours (h),minutes (m), or seconds (s). For example, specify 30 seconds as 30s. Youcan include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Default value: 2s

Required: false

Data type: string

ifxIFX_SOC_TIMEOUTDescription: JDBC driver property: ifxIFX_SOC_TIMEOUT. Specify apositive integer followed by a unit of time, which can be hours (h),minutes (m), seconds (s), or milliseconds (ms). For example, specify 500milliseconds as 500ms. You can include multiple values in a single entry.For example, 1s500ms is equivalent to 1.5 seconds.

Required: false

Data type: string

ifxIFX_USEPUTDescription: JDBC driver property: ifxIFX_USEPUT.

Required: false

Data type: boolean

ifxIFX_USE_STRENCDescription: JDBC driver property: ifxIFX_USE_STRENC.

Required: false

Data type: boolean

ifxIFX_XASPECDescription: JDBC driver property: ifxIFX_XASPEC.

Default value: y

Required: false

Data type: string

ifxINFORMIXCONRETRYDescription: JDBC driver property: ifxINFORMIXCONRETRY.

Required: false

Data type: int

ifxINFORMIXCONTIMEDescription: JDBC driver property: ifxINFORMIXCONTIME. Specify a


positive integer followed by a unit of time, which can be hours (h),minutes (m), or seconds (s). For example, specify 30 seconds as 30s. Youcan include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Required: false

Data type: string

ifxINFORMIXOPCACHEDescription: JDBC driver property: ifxINFORMIXOPCACHE.

Required: false

Data type: string

ifxINFORMIXSTACKSIZEDescription: JDBC driver property: ifxINFORMIXSTACKSIZE.

Required: false

Data type: int

ifxJDBCTEMPDescription: JDBC driver property: ifxJDBCTEMP.

Required: false

Data type: string

ifxLDAP_IFXBASEDescription: JDBC driver property: ifxLDAP_IFXBASE.

Required: false

Data type: string

ifxLDAP_PASSWDDescription: JDBC driver property: ifxLDAP_PASSWD.

Required: false

Data type: string

ifxLDAP_URLDescription: JDBC driver property: ifxLDAP_URL.

Required: false

Data type: string

ifxLDAP_USERDescription: JDBC driver property: ifxLDAP_USER.

Required: false

Data type: string

ifxLOBCACHEDescription: JDBC driver property: ifxLOBCACHE.

Required: false

Data type: int

ifxNEWCODESETDescription: JDBC driver property: ifxNEWCODESET.

Required: false


Data type: string

ifxNEWLOCALEDescription: JDBC driver property: ifxNEWLOCALE.

Required: false

Data type: string

ifxNODEFDACDescription: JDBC driver property: ifxNODEFDAC.

Required: false

Data type: string

ifxOPTCOMPINDDescription: JDBC driver property: ifxOPTCOMPIND.

Required: false

Data type: string

ifxOPTOFCDescription: JDBC driver property: ifxOPTOFC.

Required: false

Data type: string

ifxOPT_GOALDescription: JDBC driver property: ifxOPT_GOAL.

Required: false

Data type: string

ifxPATHDescription: JDBC driver property: ifxPATH.

Required: false

Data type: string

ifxPDQPRIORITYDescription: JDBC driver property: ifxPDQPRIORITY.

Required: false

Data type: string

ifxPLCONFIGDescription: JDBC driver property: ifxPLCONFIG.

Required: false

Data type: string

ifxPLOAD_LO_PATHDescription: JDBC driver property: ifxPLOAD_LO_PATH.

Required: false

Data type: string

ifxPROTOCOLTRACEDescription: JDBC driver property: ifxPROTOCOLTRACE.

Required: false

Data type: int


ifxPROTOCOLTRACEFILEDescription: JDBC driver property: ifxPROTOCOLTRACEFILE.

Required: false

Data type: string

ifxPROXYDescription: JDBC driver property: ifxPROXY.

Required: false

Data type: string

ifxPSORT_DBTEMPDescription: JDBC driver property: ifxPSORT_DBTEMP.

Required: false

Data type: string

ifxPSORT_NPROCSDescription: JDBC driver property: ifxPSORT_NPROCS.

Required: false

Data type: boolean

ifxSECURITYDescription: JDBC driver property: ifxSECURITY.

Required: false

Data type: string

ifxSQLH_FILEDescription: JDBC driver property: ifxSQLH_FILE.

Required: false

Data type: string

ifxSQLH_LOCDescription: JDBC driver property: ifxSQLH_LOC.

Required: false

Data type: string

ifxSQLH_TYPEDescription: JDBC driver property: ifxSQLH_TYPE.

Required: false

Data type: string

ifxSSLCONNECTIONDescription: JDBC driver property: ifxSSLCONNECTION.

Required: false

Data type: string

ifxSTMT_CACHEDescription: JDBC driver property: ifxSTMT_CACHE.

Required: false

Data type: string

ifxTRACE


Description: JDBC driver property: ifxTRACE.

Required: false

Data type: int

ifxTRACEFILEDescription: JDBC driver property: ifxTRACEFILE.

Required: false

Data type: string

ifxTRUSTED_CONTEXTDescription: JDBC driver property: ifxTRUSTED_CONTEXT.

Required: false

Data type: string

ifxUSEV5SERVERDescription: JDBC driver property: ifxUSEV5SERVER.

Required: false

Data type: boolean

ifxUSE_DTENVDescription: JDBC driver property: ifxUSE_DTENV.

Required: false

Data type: boolean


Required: false

Data type: string

roleNameDescription: JDBC driver property: roleName.

Required: false

Data type: string

properties.informix.jccData source properties for the IBM Data Server Driver for JDBC and SQLJ forInformix. PID is com.ibm.ws.jdbc.dataSource.properties.informix.jcc, and it is thechild of complex type “dataSource”.


Attributes


Required: false

Data type: string



Required: false

Data type: string


Default value: 1526

Required: false

Data type: int


Required: false

Data type: string


Required: false


currentLockTimeoutDescription: JDBC driver property: currentLockTimeout. Specify apositive integer followed by a unit of time, which can be hours (h),minutes (m), or seconds (s). For example, specify 30 seconds as 30s. Youcan include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Default value: 2s

Required: false

Data type: string

DBANSIWARNDescription: JDBC driver property: DBANSIWARN.

Required: false

Data type: boolean

DBDATEDescription: JDBC driver property: DBDATE.

Required: false

Data type: string


DBPATHDescription: JDBC driver property: DBPATH.

Required: false

Data type: string

DBSPACETEMPDescription: JDBC driver property: DBSPACETEMP.

Required: false

Data type: string

DBTEMPDescription: JDBC driver property: DBTEMP.

Required: false

Data type: string

DBUPSPACEDescription: JDBC driver property: DBUPSPACE.

Required: false

Data type: string

DELIMIDENTDescription: JDBC driver property: DELIMIDENT.

Required: false

Data type: boolean

deferPreparesDescription: JDBC driver property: deferPrepares.

Required: false

Data type: boolean


Default value: 4

Required: false

Data type: int

enableNamedParameterMarkersDescription: JDBC driver property: enableNamedParameterMarkers.Values are: 1 (YES) or 2 (NO).

Required: false

Data type: int

enableSeamlessFailoverDescription: JDBC driver property: enableSeamlessFailover. Values are: 1(YES) or 2 (NO).

Required: false

Data type: int

enableSysplexWLBDescription: JDBC driver property: enableSysplexWLB.


Required: false

Data type: boolean

fetchSizeDescription: JDBC driver property: fetchSize.

Required: false

Data type: int

fullyMaterializeLobDataDescription: JDBC driver property: fullyMaterializeLobData.

Required: false

Data type: boolean

IFX_DIRECTIVESDescription: JDBC driver property: IFX_DIRECTIVES.

Range:

ON

OFF

Required: false

Data type: string

IFX_EXTDIRECTIVESDescription: JDBC driver property: IFX_EXTDIRECTIVES.

Range:

ON

OFF

Required: false

Data type: string

IFX_UPDDESCDescription: JDBC driver property: IFX_UPDDESC.

Required: false

Data type: string

IFX_XASTDCOMPLIANCE_XAENDDescription: JDBC driver property: IFX_XASTDCOMPLIANCE_XAEND.

Range:

0

1

Required: false

Data type: string

INFORMIXOPCACHEDescription: JDBC driver property: INFORMIXOPCACHE.

Required: false

Data type: string

INFORMIXSTACKSIZE


Description: JDBC driver property: INFORMIXSTACKSIZE.

Required: false

Data type: string

keepDynamicDescription: JDBC driver property: keepDynamic.

Required: false

Data type: int


Required: false

Data type: string

NODEFDACDescription: JDBC driver property: NODEFDAC.

Range:

yes

no

Required: false

Data type: string

OPTCOMPINDDescription: JDBC driver property: OPTCOMPIND.

Range:

0

1

2

Required: false

Data type: string

OPTOFCDescription: JDBC driver property: OPTOFC.

Range:

0

1

Required: false

Data type: string

PDQPRIORITYDescription: JDBC driver property: PDQPRIORITY.

Range:

HIGH


LOW

OFF

Required: false

Data type: string

progressiveStreamingDescription: JDBC driver property: progressiveStreaming. Values are: 1(YES) or 2 (NO).

Range:

1 YES

2 NO

Required: false

Data type: int

PSORT_DBTEMPDescription: JDBC driver property: PSORT_DBTEMP.

Required: false

Data type: string

PSORT_NPROCSDescription: JDBC driver property: PSORT_NPROCS.

Required: false

Data type: string

queryDataSizeDescription: JDBC driver property: queryDataSize.

Required: false

Data type: int

resultSetHoldabilityDescription: JDBC driver property: resultSetHoldability. Values are: 1(HOLD_CURSORS_OVER_COMMIT) or 2(CLOSE_CURSORS_AT_COMMIT).

Range:



Required: false

Data type: int

resultSetHoldabilityForCatalogQueriesDescription: JDBC driver property:resultSetHoldabilityForCatalogQueries. Values are: 1(HOLD_CURSORS_OVER_COMMIT) or 2(CLOSE_CURSORS_AT_COMMIT).

Range:




Required: false

Data type: int

retrieveMessagesFromServerOnGetMessageDescription: JDBC driver property:retrieveMessagesFromServerOnGetMessage.

Default value: true

Required: false

Data type: boolean

securityMechanismDescription: JDBC driver property: securityMechanism. Values are: 3(CLEAR_TEXT_PASSWORD_SECURITY), 4 (USER_ONLY_SECURITY), 7(ENCRYPTED_PASSWORD_SECURITY), 9(ENCRYPTED_USER_AND_PASSWORD_SECURITY).

Range:





Required: false

Data type: short

STMT_CACHEDescription: JDBC driver property: STMT_CACHE.

Range:

0

1

Required: false

Data type: string


Required: false

Data type: string


Required: false

Data type: string


Required: false

Data type: boolean

traceLevelDescription: Bitwise combination of the following constant values:


TRACE_NONE=0, TRACE_CONNECTION_CALLS=1,TRACE_STATEMENT_CALLS=2, TRACE_RESULT_SET_CALLS=4,TRACE_DRIVER_CONFIGURATION=16, TRACE_CONNECTS=32,TRACE_DRDA_FLOWS=64, TRACE_RESULT_SET_META_DATA=128,TRACE_PARAMETER_META_DATA=256, TRACE_DIAGNOSTICS=512,TRACE_SQLJ=1024, TRACE_META_CALLS=8192,TRACE_DATASOURCE_CALLS=16384,TRACE_LARGE_OBJECT_CALLS=32768,TRACE_SYSTEM_MONITOR=131072, TRACE_TRACEPOINTS=262144,TRACE_ALL=-1.

Required: false

Data type: int

useJDBC4ColumnNameAndLabelSemanticsDescription: JDBC driver property:useJDBC4ColumnNameAndLabelSemantics. Values are: 1 (YES) or 2(NO).

Required: false

Data type: int

properties.jms.ActivationSpec

Activation Specification properties. PID is properties.jms.ActivationSpec, and it isthe child of complex type “activationSpec”.


Attributes

destinationTypeDescription: The type of the destination, which can be eitherjavax.jms.Queue or javax.jms.Topic

Default value: javax.jms.Queue

Required: true

Data type: string

destinationRefDescription: Reference to a JMS destination

Required: false

Data type: Configuration ID of type jmsQueue (string).

userNameDescription: User Name

Default value: CF1USER

Required: false

Data type: string

passwordDescription: Password


Required: false

Data type: string

readAheadDescription: Read ahead is an optimization that preemptively assignsmessages to consumers. This processes the consumer requests faster

Default value: Default

Range:

Default

AlwaysOn

AlwaysOff

Required: false

Data type: string

connectionNameDescription: A comma-separated list of endpoint triplets, with the syntaxhostName:portNumber:chainName, used to connect to a bootstrap server.For example:Merlin:7276:BootstrapBasicMessaging,Gandalf:5557:BootstrapSecureMessaging

If hostName is not specified, the default is localhost. If portNumber is notspecified, the default is 7276. If chainName is not specified, the default isBootstrapBasicMessaging. Refer to the information center for moreinformation



Required: false

Data type: string

targetTransportDescription: Specify whether the client connects to the messaging enginethrough in-process or TCP/IP

Default value: BINDING_THEN_CLIENT

Range:

BINDING

CLIENT

BINDING_THEN_CLIENT

Required: false

Data type: string

Sub-elements

destinationDescription: Reference to a JMS destination

Required: false

Data type: Element of type jmsQueue.

properties.jms.ConnectionFactory

A JMS connection factory is used to create connections to the associated JMSprovider of JMS destinations, for both point-to-point and publish/subscribemessaging. PID is properties.jms.ConnectionFactory, and it is the child of complextype “jmsConnectionFactory”.


Attributes



Required: false

Data type: string

clientIDDescription: The JMS client identifier needed for durable topicsubscriptions on all connections created using this connection factory.This identifier is required if the application is doing durablepublish/subscribe messaging.

Default value: clientId

Required: false

Data type: string



Required: false

Data type: string

nonPersistentMappingDescription: The reliability applied to Non-persistent JMS messages sentusing this connection factory.

Default value: ExpressNonPersistent

Range:




Required: false

Data type: string

persistentMappingDescription: The reliability applied to persistent JMS messages sent usingthis connection factory.

Default value: ReliablePersistent

Range:

ReliablePersistent

AssuredPersistent

Required: false

Data type: string

readAheadDescription: Read ahead is an optimization that preemptively assigns


messages to consumers. This processes the consumer requests faster.


Range:

Default

AlwaysOn

AlwaysOff

Required: false

Data type: string

connectionNameDescription: The Connection Name that has triplets separated by acomma, with the syntax hostName:portNumber:chainName, used toconnect to a bootstrap server. For example,Merlin:7276:BootstrapBasicMessaging. If hostName is not specified, thedefault is localhost. If portNumber is not specified, the default is 7276. IfchainName is not specified, the default is BootstrapBasicMessaging. Referto the information center for more information


Required: false

Data type: string

targetTransportDescription: Specify whether the client connects to the messaging enginethrough in-process or TCP/IP.


Range:

BINDING

CLIENT

BINDING_THEN_CLIENT

Required: false

Data type: string

temporaryQueueNamePrefixDescription: The prefix of up to twelve characters used for the temporaryqueues created by applications that use this connection factory.

Default value: tempor

Required: false

Data type: string

properties.jms.Queue

Queue. PID is properties.jms.Queue, and it is the child of complex type“jmsQueue”.


Attributes

queueNameDescription: The name of the associated Queue

Default value: Default.Queue

Required: false

Data type: string

deliveryModeDescription: The delivery mode for messages sent to this destination.This controls the persistence of messages on this destination.

Default value: Application

Range:

Application

Persistent

NonPersistent

Required: false

Data type: string

timeToLiveDescription: The default time in milliseconds from its dispatch time thatthe system must keep the messages live in the destination.

Default value: 0

Required: false

Data type: long

readAheadDescription: Read ahead is an optimization that preemptively assignsmessages to consumers. This processes the consumer requests faster.

Default value: AsConnection

Range:

AsConnection

AlwaysOn

AlwaysOff

Required: false

Data type: string

priorityDescription: The relative priority for messages sent to this destination, inthe range 0 to 9, with 0 as the lowest priority and 9 as the highestpriority.

Default value: 1

Required: false

Data type: int


properties.jms.QueueConnectionFactory

A JMS queue connection factory is used to create connections to the associated JMSprovider of JMS queues, for point-to-point messaging. PID isproperties.jms.QueueConnectionFactory, and it is the child of complex type“jmsQueueConnectionFactory”.


Attributes



Required: false

Data type: string

clientIDDescription: The JMS client identifier needed for durable topicsubscriptions on all connections created using this connection factory.This identifier is required if the application is doing durablepubish/subscribe


Required: false

Data type: string



Required: false

Data type: string



Range:




Required: false

Data type: string



Range:

ReliablePersistent

AssuredPersistent

Required: false

Data type: string

readAheadDescription: Read ahead is an optimization that preemptively assigns


messages to consumers. This processes the consumer requests faster.


Range:

Default

AlwaysOn

AlwaysOff

Required: false

Data type: string

connectionNameDescription: The Connection Name that has triplets, with the syntaxhostName:portNumber:chainName, used to connect to a bootstrap server.For example Merlin:7276:BootstrapBasicMessaging. If hostName is notspecified, the default is localhost. If portNumber is not specified, thedefault is 7276. If chainName is not specified, the default isBootstrapBasicMessaging. Refer to the information center for moreinformation.


Required: false

Data type: string



Range:

BINDING

CLIENT

BINDING_THEN_CLIENT

Required: false

Data type: string

temporaryQueueNamePrefixDescription: The prefix used at the start of temporary topics created byapplications using this connection factory.


Required: false

Data type: string

properties.jms.Topic

The name of the topic that this JMS topic is assigned to, in the topic space definedby the Topic space property. PID is properties.jms.Topic, and it is the child ofcomplex type “jmsTopic”.


Attributes

topicSpaceDescription: A topic space is a location for publish/subscribe messaging.

Default value: Default.Topic.Space

Required: false

Data type: string

topicNameDescription: The name of the topic that this JMS topic is assigned to, inthe topic space defined by the Topic space property.

Default value: Default.Topic

Required: false

Data type: string

deliveryModeDescription: The delivery mode for messages sent to this destination.This controls the persistence of messages on this destination.

Default value: Application

Range:

Application

Persistent

NonPersistent

Required: false

Data type: string

timeToLiveDescription: The default time in milliseconds from its dispatch time thatthe system must keep the messages live in the destination.

Default value: 0

Required: false

Data type: long


Default value: AsConnection

Range:

AsConnection

AlwaysOn

AlwaysOff

Required: false

Data type: string

priority


Description: The relative priority for messages sent to this destination, inthe range 0 to 9, with 0 as the lowest priority and 9 as the highestpriority.

Default value: 1

Required: false

Data type: int

properties.jms.TopicConnectionFactory

Topic Connection Factory. PID is properties.jms.TopicConnectionFactory, and it isthe child of complex type “jmsTopicConnectionFactory”.


Attributes



Required: false

Data type: string

clientIDDescription: The JMS client identifier needed for durable topicsubscriptions on all connections that are created using this connectionfactory.


Required: false

Data type: string



Required: false

Data type: string



Range:




Required: false

Data type: string



Range:

ReliablePersistent

AssuredPersistent

Required: false

Data type: string




Range:

Default

AlwaysOn

AlwaysOff

Required: false

Data type: string

connectionNameDescription: The Connection Name that has triplets separated by acomma, with the syntax hostName:portNumber:chainName, used toconnect to a bootstrap server. For exampleMerlin:7276:BootstrapBasicMessaging. If hostName is not specified, thedefault is localhost. If portNumber is not specified, the default is 7276. IfchainName is not specified, the default is BootstrapBasicMessaging. Referto the information center for more information.


Required: false

Data type: string



Range:

BINDING

CLIENT

BINDING_THEN_CLIENT

Required: false

Data type: string

temporaryQueueNamePrefixDescription: The prefix used at the start of temporary topics created byapplications using this connection factory.


Required: false

Data type: string

properties.microsoft.sqlserverData source properties for Microsoft SQL Server JDBC Driver. PID iscom.ibm.ws.jdbc.dataSource.properties.microsoft.sqlserver, and it is the child ofcomplex type “dataSource”.


Attributes


Required: false

Data type: string

instanceNameDescription: JDBC driver property: instanceName.

Required: false

Data type: string



Required: false

Data type: string


Default value: 1433

Required: false

Data type: int


Required: false

Data type: string


Required: false


applicationIntentDescription: JDBC driver property: applicationIntent.

Range:

ReadOnly

ReadWrite

Required: false

Data type: string

applicationNameDescription: JDBC driver property: applicationName.

Required: false

Data type: string

authenticationScheme


Description: JDBC driver property: authenticationScheme.

Range:

JavaKerberos

NativeAuthentication

Required: false

Data type: string

encryptDescription: JDBC driver property: encrypt.

Required: false

Data type: boolean

failoverPartnerDescription: JDBC driver property: failoverPartner.

Required: false

Data type: string

hostNameInCertificateDescription: JDBC driver property: hostNameInCertificate.

Required: false

Data type: string

integratedSecurityDescription: JDBC driver property: integratedSecurity.

Required: false

Data type: boolean

lastUpdateCountDescription: JDBC driver property: lastUpdateCount.

Required: false

Data type: boolean

lockTimeoutDescription: JDBC driver property: lockTimeout. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),seconds (s), or milliseconds (ms). For example, specify 500 milliseconds as500ms. You can include multiple values in a single entry. For example,1s500ms is equivalent to 1.5 seconds.

Required: false

Data type: string


Required: false

Data type: string


multiSubnetFailoverDescription: JDBC driver property: multiSubnetFailover.

Required: false

Data type: boolean

packetSizeDescription: JDBC driver property: packetSize.

Required: false

Data type: int

responseBufferingDescription: JDBC driver property: responseBuffering.

Range:

adaptive

full

Required: false

Data type: string

selectMethodDescription: JDBC driver property: selectMethod.

Range:

cursor

direct

Required: false

Data type: string

sendStringParametersAsUnicodeDescription: JDBC driver property: sendStringParametersAsUnicode.


Required: false

Data type: boolean

sendTimeAsDatetimeDescription: JDBC driver property: sendTimeAsDatetime.

Required: false

Data type: boolean

trustServerCertificateDescription: JDBC driver property: trustServerCertificate.

Required: false

Data type: boolean

trustStoreDescription: JDBC driver property: trustStore.

Required: false

Data type: string

trustStorePassword


Description: JDBC driver property: trustStorePassword.

Required: false


URLDescription: URL for connecting to the database. Example:jdbc:sqlserver://localhost:1433;databaseName=myDB.

Required: false

Data type: string

workstationIDDescription: JDBC driver property: workstationID.

Required: false

Data type: string

xopenStatesDescription: JDBC driver property: xopenStates.

Required: false

Data type: boolean

properties.oracleData source properties for Oracle JDBC driver. PID iscom.ibm.ws.jdbc.dataSource.properties.oracle, and it is the child of complex type“dataSource”.


Attributes


Default value: thin

Range:

thin

oci

Required: false

Data type: string


Required: false

Data type: string



Required: false

Data type: string


Default value: 1521

Required: false

Data type: int

URLDescription: URL for connecting to the database. Examples:jdbc:oracle:thin:@//localhost:1521/sample or jdbc:oracle:oci:@//localhost:1521/sample.

Required: false

Data type: string


Required: false

Data type: string


Required: false


connectionPropertiesDescription: JDBC driver property: connectionProperties.


Required: false

Data type: string


Required: false

Data type: string


Required: false

Data type: string

ONSConfigurationDescription: JDBC driver property: ONSConfiguration.

Required: false

Data type: string

serviceNameDescription: JDBC driver property: serviceName.

Required: false

Data type: string

TNSEntryNameDescription: JDBC driver property: TNSEntryName.

Required: false

Data type: string

properties.sybaseData source properties for Sybase JDBC driver. PID iscom.ibm.ws.jdbc.dataSource.properties.sybase, and it is the child of complex type“dataSource”.


Attributes


Required: true

Data type: string



Required: false

Data type: string


Default value: 5000

Required: false

Data type: int


Required: false

Data type: string


Required: false


connectionPropertiesDescription: JDBC driver property: connectionProperties.

Default value: SELECT_OPENS_CURSOR=true

Required: false

Data type: string


Required: false

Data type: string


Range:

socket


SSL

Required: false

Data type: string

resourceManagerNameDescription: JDBC driver property: resourceManagerName.

Required: false

Data type: string

SERVER_INITIATED_TRANSACTIONSDescription: JDBC driver property:SERVER_INITIATED_TRANSACTIONS.


Range:

true

false

Required: false

Data type: string

versionDescription: JDBC driver property: version.

Required: false

Data type: int

quickStartSecuritySimple administrative security configuration. PID iscom.ibm.ws.security.quickStartSecurity.

Attributes

userNameDescription: Single user defined as part of the quick start securityconfiguration. This user is granted the Administrator role.

Required: true

Data type: string

userPasswordDescription: Password for the single user defined as part of the quickstart security configuration. It is recommended that you encode thispassword. To do so, use the securityUtility tool with the encode option.

Required: true


realm

The realm configuration. PID is com.ibm.ws.wim.core.realm.


Attributes

nameDescription: Name of the realm.

Required: true

Data type: string

participatingBaseEntryRefDescription: The Base Entry that is part of this realm.

Required: false

Data type: List of configuration IDs of type baseEntry (comma-separatedstring).

delimiterDescription: Delimiter used for this realm

Default value: /

Required: false

Data type: string

enabledDescription: Specifies whether the realm is enabled for security use.

Default value: true

Required: false

Data type: boolean

allowOpIfRepoDownDescription: Specifies whether to allow operation if a repository is down.The default value is false.


Required: false

Data type: boolean

uniqueUserIdMappingRefDescription: The property mapping for uniqueUserId (default:uniqueName).

Required: false

Data type: Configuration ID of type uniqueUserIdMapping (string).

userSecurityNameMappingRefDescription: The property mapping for userSecurityName (default:principalName).

Required: false

Data type: Configuration ID of type userSecurityNameMapping (string).

userDisplayNameMappingRefDescription: The property mapping for userDisplayName (default:principalName).

Required: false


Data type: Configuration ID of type userDisplayNameMapping (string).

uniqueGroupIdMappingRefDescription: The property mapping for uniqueGroupId (default:uniqueName).

Required: false

Data type: Configuration ID of type uniqueGroupIdMapping (string).

groupSecurityNameMappingRefDescription: The property mapping for groupSecurityName (default: cn).

Required: false

Data type: Configuration ID of type groupSecurityNameMapping (string).

groupDisplayNameMappingRefDescription: The property mapping for groupDisplayName (default: cn).

Required: false

Data type: Configuration ID of type groupDisplayNameMapping (string).


Sub-elements

participatingBaseEntryDescription: The Base Entry that is part of this realm.

Required: false

Data type: Element of type baseEntry.

uniqueUserIdMappingDescription: The property mapping for uniqueUserId (default:uniqueName).

Required: false

Data type: Element of type uniqueUserIdMapping.

userSecurityNameMappingDescription: The property mapping for userSecurityName (default:principalName).

Required: false

Data type: Element of type userSecurityNameMapping.

userDisplayNameMappingDescription: The property mapping for userDisplayName (default:principalName).

Required: false

Data type: Element of type userDisplayNameMapping.

uniqueGroupIdMappingDescription: The property mapping for uniqueGroupId (default:uniqueName).

Required: false

Data type: Element of type uniqueGroupIdMapping.

groupSecurityNameMappingDescription: The property mapping for groupSecurityName (default: cn).

Required: false

Data type: Element of type groupSecurityNameMapping.

groupDisplayNameMappingDescription: The property mapping for groupDisplayName (default: cn).

Required: false

Data type: Element of type groupDisplayNameMapping.

remoteAccess

Remote Access configuration. PID iscom.ibm.ws.management.command.remoteAccess.


Attributes

enableTraceDescription: Indicates whether the trace for remote access is enabled. Thedefault value is false.


Required: false

Data type: boolean

connTimeoutDescription: Amount of time to wait for obtaining a remote connection toremote targets. The default value is 180 seconds.

Default value: 180

Required: false

Data type: int

intConnTimeoutDescription: Amount of time to wait for internal operations whileobtaining a remote connection to remote targets. Default is "infinite" or 0second, meaning that there is no internal timeout limit.

Default value: 20

Required: false

Data type: int

useSftpDescription: Indicates whether to use sftp to transfer file. Te default valueis false meaning to use scp to transfer file.


Required: false

Data type: boolean

role

A set of permissions mapped to the users and groups. PID iscom.ibm.ws.messaging.security.role.


Attributes

nameDescription: The name of the role.

Required: true

Data type: string

permissionRefDescription: The permission for a destination for the set of users andgroups that are defined for the particular role.

Required: false

Data type: List of configuration IDs of type permission (comma-separatedstring).

userRefDescription: The users that are assigned to the particular role.

Required: false

Data type: List of configuration IDs of type user (comma-separatedstring).

groupRefDescription: The groups that are assigned to the role.

Required: false

Data type: List of configuration IDs of type group (comma-separatedstring).

Sub-elements

permissionDescription: The permission for a destination for the set of users andgroups that are defined for the particular role.

Required: false

Data type: Element of type permission.

userDescription: The users that are assigned to the particular role.

Required: false

Data type: Element of type user.

groupDescription: The groups that are assigned to the role.

Required: false

Data type: Element of type group.

safAuthorizationControls the operation of the SAF Authorization Service. PID iscom.ibm.ws.security.authorization.saf.


Attributes

roleMapperDescription: OSGi component name of the SAF Role Mapper serviceprovider.

Default value:com.ibm.ws.security.authorization.saf.internal.SAFRoleMapperImpl

Required: false

Data type: string

safCredentialsControls the operation of the SAF Credentials Service. PID iscom.ibm.ws.security.credentials.saf.

Attributes

unauthenticatedUserDescription: SAF user ID of the unauthenticated user.

Default value: WSGUEST

Required: false

Data type: string

profilePrefixDescription: Profile prefix used to specify the SAF APPL-ID whencreating SAF credentials and authorizing users against SAF resourceprofiles.

Default value: BBGZDFLT

Required: false

Data type: string

safRegistryConfiguration properties for a SAF user registry. PID iscom.ibm.ws.security.registry.saf.config.

Attributes


Required: false

Data type: string


safRoleMapperDefines how to generate SAF EJBROLE resource profile names from applicationrole names. PID iscom.ibm.ws.security.authorization.saf.internal.SAFRoleMapperImpl.

Attributes

profilePatternDescription: Pattern to use for generating EJBROLE resource profilenames from application role names.

Default value: %profilePrefix%.%resource%.%role%

Required: false

Data type: string

toUpperCaseDescription: Convert the EJBROLE resource profile name to upper-case.


Required: false

Data type: boolean

securewayLdapFilterPropertiesSpecifies the list of default IBM SecureWay Directory Server LDAP filters. PID iscom.ibm.ws.security.registry.ldap.internal.filters.secureway.


Attributes



Required: true

Data type: string


Default value:

(&(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))

Required: true

Data type: string



Required: true

Data type: string


Default value: *:cn

Required: true

Data type: string


Default value:groupOfNames:member;groupOfUniqueNames:uniqueMember

Required: true

Data type: string

serverCommand

Server Command MBean configuration. PID iscom.ibm.ws.management.command.serverCommand.


Attributes

startServerTimeoutDescription: Amount of time to wait for remote server to start. Thedefault value is 60 seconds.

Default value: 60

Required: false

Data type: int

stopServerTimeoutDescription: Amount of time to wait for remote server to stop. Thedefault value is 60 seconds.

Default value: 60

Required: false

Data type: int

sslAn SSL configuration repertoire with an ID, a defined keystore, and an optionaltruststore. PID is com.ibm.ws.ssl.repertoire.

Attributes

keyStoreRefDescription: A keystore containing key entries for the SSL configurationrepertoire. This attribute is required.

Required: true

Data type: string

trustStoreRefDescription: A keystore containing trusted certificate entries used by theSSL configuration repertoire for signing verification. This attribute isoptional. If unspecified, the same keystore is used for both key andtrusted certificate entries.

Default value: ${keyStoreRef}

Required: false

Data type: string

sslDefaultThe default configuration repertoire for SSL services. PID is com.ibm.ws.ssl.default.


Attributes

sslRefDescription: The default SSL configuration repertoire. The default valueis defaultSSLSettings.

Default value: defaultSSLConfig

Required: false

Data type: string

sslOptionsThe SSL protocol configuration for a transport. PID iscom.ibm.ws.sslchannel.options.

Attributes

sessionTimeoutDescription: Amount of time to wait for a read or write request tocomplete on a socket. This value is overridden by protocol-specifictimeouts. Specify a positive integer followed by a unit of time, which canbe hours (h), minutes (m), or seconds (s). For example, specify 30 secondsas 30s. You can include multiple values in a single entry. For example,1m30s is equivalent to 90 seconds.

Default value: 1d

Required: false

Data type: string

suppressHandshakeErrorsDescription: Disable logging of SSL handshake errors. SSL handshakeerrors can occur during normal operation, however these messages can beuseful when SSL is behaving unexpectedly.


Required: false

Data type: boolean

sslRefDescription: The default SSL configuration repertoire. The default valueis defaultSSLSettings.

Required: false

Data type: string

supportedEntityType

The Supported entity type configuration. PID iscom.ibm.ws.wim.core.config.supportedEntityType.


Attributes

nameDescription: The name of the supported entity type.

Required: true

Data type: string

Sub-elements

rdnPropertyDescription: The Relative distinguished name property for the supportedentity.

Required: true

Data type: string

syncToOSThread

Enabled and configures the Sync-to-OS-thread Service. PID iscom.ibm.ws.security.thread.zos.internal.ThreadIdentityServiceImpl.

Attributes

appEnabledDescription: Enable sync-to-OS-thread for applications.


Required: false

Data type: boolean

j2cEnabledDescription: Enable sync-to-OS-thread for J2C connectors that supportnative thread identity.


Required: false

Data type: boolean

tcpOptionsDefines TCP protocol settings. PID is com.ibm.ws.tcpchannel.options.


Attributes

inactivityTimeoutDescription: Amount of time to wait for a read or write request tocomplete on a socket. This value is overridden by protocol-specifictimeouts. Specify a positive integer followed by a unit of time, which canbe hours (h), minutes (m), seconds (s), or milliseconds (ms). For example,specify 500 milliseconds as 500ms. You can include multiple values in asingle entry. For example, 1s500ms is equivalent to 1.5 seconds.

Default value: 60s

Required: false

Data type: string

soReuseAddrDescription: Enables immediate rebind to a port with no active listener.


Required: false

Data type: boolean

textLog

Use this page to configure High Performance Extensible Logging (HPEL) text logoptions. The HPEL text log can be viewed using any text editor. PID iscom.ibm.ws.logging.textLog, and it is the child of complex type “logging”.


Attributes

dataDirectoryDescription: Specifies the location on the local file system to store the logrecords.

Inherits: com.ibm.hpel.text.dataDirectory

Default value:

Required: false

Data type: string

outputFormatDescription: Text Output Format to use in the Text Log

Inherits: com.ibm.hpel.text.outputFormat

Default value: Basic

Range:

Basic

Advanced

Required: false

Data type: string

includeTraceDescription: Include trace records in the Text Log

Inherits: com.ibm.hpel.text.includeTrace


Required: false

Data type: boolean

purgeMaxSizeDescription: Specifies the maximum size for all log files.

Inherits: com.ibm.hpel.text.purgeMaxSize

Default value: 50

Required: false

Data type: int


Inherits: com.ibm.hpel.text.purgeMinTime

Default value: -1

Required: false

Data type: int



Inherits: com.ibm.hpel.text.fileSwitchTime

Required: false

Data type: int


Inherits: com.ibm.hpel.text.bufferingEnabled

Default value: true

Required: false

Data type: boolean


Inherits: com.ibm.hpel.text.outOfSpaceAction


Range:




Required: false

Data type: string

transactionConfiguration properties for the Transaction Manager service. PID iscom.ibm.ws.transaction.


Attributes

recoverOnStartupDescription: Specifies whether the server should begin transactionrecovery at server startup.


Required: false

Data type: boolean

waitForRecoveryDescription: Specifies whether the server should wait for transactionrecovery to complete before accepting new transactional work.


Required: false

Data type: boolean

acceptHeuristicHazardDescription: Specifies whether all applications on this server accept thepossibility of a heuristic hazard occurring in a two-phase transaction thatcontains a one-phase resource.

Default value: true

Required: false

Data type: boolean

clientInactivityTimeoutDescription: Maximum duration between transactional requests from aremote client. Any period of client inactivity that exceeds this timeoutresults in the transaction being rolled back in this application server.Specify a positive integer followed by a unit of time, which can be hours(h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s.You can include multiple values in a single entry. For example, 1m30s isequivalent to 90 seconds.

Default value: 60s

Required: false

Data type: string

heuristicRetryIntervalDescription: Amount of time that the application server waits beforeretrying a completion signal, such as commit or rollback, after a transientexception from a resource manager or remote partner. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Default value: 60s

Required: false

Data type: string

heuristicRetryWait


Description: The number of times that the application server retries acompletion signal, such as commit or rollback. Retries occur after atransient exception from a resource manager or remote partner.

Default value: 5

Required: false

Data type: int

propogatedOrBMTTranLifetimeTimeoutDescription: Upper limit of the transaction timeout for transactions thatrun in this server. This value should be greater than or equal to the valuespecified for the total transaction timeout. Specify a positive integerfollowed by a unit of time, which can be hours (h), minutes (m), orseconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Default value: 0

Required: false

Data type: string

totalTranLifetimeTimeoutDescription: Default maximum time allowed for transactions started onthis server to complete. Any such transactions that do not completebefore this timeout occurs are rolled back. Specify a positive integerfollowed by a unit of time, which can be hours (h), minutes (m), orseconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Default value: 12000s

Required: false

Data type: string

transactionLogDirectoryDescription: A directory for this server where the transaction servicestores log files for recovery.

Default value: ${server.config.dir}/tranlog/

Required: false

Data type: string

transactionLogSizeDescription: Specifies the size of transaction log files in Kilobytes.

Default value: 1024

Required: false

Data type: int

enableLoggingForHeuristicReportingDescription: Specifies whether the application server logsabout-to-commit-one-phase-resource events from transactions that involveboth a one-phase commit resource and two-phase commit resources.


Required: false


Data type: boolean

timeoutGracePeriodEnabledDescription: Specifies whether there is a delay between a transactiontimeout and the abnormal ending of the servant region that was runningthe transaction.


Required: false

Data type: boolean

lpsHeuristicCompletionDescription: Specifies the direction that is used to complete a transactionthat has a heuristic outcome; either the application server commits orrolls back the transaction, or depends on manual completion by theadministrator. Allowed values are: COMMIT, ROLLBACK and MANUAL

Default value: ROLLBACK

Range:

ROLLBACK

COMMIT

MANUAL

Required: false

Data type: string

defaultMaxShutdownDelayDescription: Default maximum shutdown delay. Specify a positiveinteger followed by a unit of time, which can be hours (h), minutes (m),or seconds (s). For example, specify 30 seconds as 30s. You can includemultiple values in a single entry. For example, 1m30s is equivalent to 90seconds.

Default value: 2s

Required: false

Data type: string

trustAssociationControls the operation of the trust association interceptor (TAI) service. PID iscom.ibm.ws.security.authentication.tai.


Attributes

invokeForUnprotectedURIDescription: Controls whether the TAI is invoked for an unprotected URI.


Required: true

Data type: boolean

failOverToAppAuthTypeDescription: Allow an interceptor to fall back to the applicationauthentication mechanism.


Required: true

Data type: boolean


Sub-elements

interceptorsRequired: true

Data type: Defines a trust association interceptor.

enabledDescription: Enables or disables the interceptor.

Default value: true

Required: true

Data type: boolean

classNameDescription: Fully-qualified package name of the interceptor class.

Required: true

Data type: string

invokeBeforeSSODescription: Invoke an interceptor before single sign-on (SSO).

Default value: true

Required: true

Data type: boolean

invokeAfterSSODescription: Invoke an interceptor after single sign-on (SSO).


Required: true

Data type: boolean

libraryRefDescription: A reference to the ID of the shared library configuration.

Required: false


libraryDescription: A reference to the ID of the shared library configuration.

Required: false


propertiesRequired: false

uniqueGroupIdMapping

The property mapping for uniqueGroupId(default: uniqueName). PID iscom.ibm.ws.wim.uniqueGroupIdMapping.


Attributes


Default value: uniqueName

Required: true

Data type: string

propertyForOutputDescription: The that maps to the user registry attribute for output. Thevalid values are: uniqueId, uniqueName, externalId, externalName andthe attributes of PersonAccount and Group entity types.


Required: true

Data type: string

uniqueUserIdMapping

The property mapping for uniqueUserId(default: uniqueName). PID iscom.ibm.ws.wim.uniqueUserIdMapping.

Attributes



Required: true

Data type: string



Required: true

Data type: string


user

The user that is defined as part of the registry. PID iscom.ibm.ws.messaging.security.user.

Attributes

nameDescription: The name of the user.

Required: true

Data type: string

userDisplayNameMapping

The property mapping for userDisplayName(default: principalName). PID iscom.ibm.ws.wim.userDisplayNameMapping.

Attributes


Default value: principalName

Required: true

Data type: string



Required: true

Data type: string

userSecurityNameMapping

The property mapping for userSecurityName(default: principalName). PID iscom.ibm.ws.wim.userSecurityNameMapping.


Attributes



Required: true

Data type: string



Required: true

Data type: string

variableDeclare a new variable by specifying the name and value for the variable.

Attributes

nameDescription: The name of the variable.

Required: true

Data type: string

valueDescription: The value to be assigned to the variable.

Required: true

Data type: string

virtualHostVirtual host configuration. PID is com.ibm.ws.http.virtualhost.

Attributes

enabledDescription: Enable this virtual host.

Default value: true

Required: false

Data type: boolean


webAppSecurityConfigures web container application security. PID iscom.ibm.ws.webcontainer.security.WebAppSecurityCollaboratorImpl.


Attributes

allowFailOverToBasicAuthDescription: Specifies whether to fail over to basic authentication whencertificate authentication fails. The equivalent custom property in the fullapplication server profile iscom.ibm.wsspi.security.web.failOverToBasicAuth.


Required: false

Data type: boolean

allowLogoutPageRedirectToAnyHostDescription: Warning, security risk: Setting this property to true mayopen your systems to potential URL redirect attacks. If set to true, anyhost can be specified for the logout page redirect. If set to false, and thelogout page points to a different host, or one not listed in the logout pageredirect domain list, then a generic logout page is displayed. Theequivalent custom property in the full application server profile iscom.ibm.websphere.security.allowAnyLogoutExitPageHost.


Required: false

Data type: boolean

displayAuthenticationRealmDescription: Warning, security risk: if this property is set to true, and theuser registry's realm name contains sensitive information, it is displayedto the user. For example, if an LDAP configuration is used, the LDAPserver hostname and port are displayed. This configuration controls whatthe HTTP basic authentication login window displays when the realmname is not defined in the application web.xml. If the realm name isdefined in the application web.xml file, this property is ignored. If set totrue, the realm name displayed will be the user registry realm name forthe LTPA authentication mechanism or the Kerberos realm name for theKerberos authentication mechanism. If set to false, the realm namedisplayed will be "Default Realm". The equivalent custom property in thefull application server profile iscom.ibm.websphere.security.displayRealm.


Required: false

Data type: boolean

httpOnlyCookiesDescription: Specifies whether the HTTP only (HttpOnly) cookies optionis enabled.

Default value: true

Required: false

Data type: boolean

logoutOnHttpSessionExpireDescription: Specifies whether users will be logged out after the HTTP


session timer expires. If set to false, the user credential will stay activeuntil the Single Sign-On token timeout occurs. The equivalent customproperty in the full application server profile iscom.ibm.ws.security.web.logoutOnHTTPSessionExpire.


Required: false

Data type: boolean

logoutPageRedirectDomainNamesDescription: A pipe (|) separated list of domain names that are allowedfor the logout page redirect (localhost is implied). The equivalent customproperty in the full application server profile iscom.ibm.websphere.security.logoutExitPageDomainList.

Required: false

Data type: string

postParamCookieSizeDescription: Size of the POST parameter cookie. If the size of the cookieis larger than the browser limit, unexpected behavior may occur. Thevalue of this property must be a positive integer and represents themaximum size of the cookie in bytes. The equivalent custom property inthe full application server profile iscom.ibm.websphere.security.util.postParamMaxCookieSize.


Required: false

Data type: int

postParamSaveMethodDescription: Specifies where POST parameters are stored upon redirect.Valid values are cookie (POST parameters are stored in a cookie), session(POST parameters are stored in the HTTP Session) and none (POSTparameters are not preserved). The equivalent custom property in the fullapplication server profile iscom.ibm.websphere.security.util.postParamSaveMethod.

Default value: Cookie

Range:

Cookie

Session

None

Required: false

Data type: string

preserveFullyQualifiedReferrerUrlDescription: Warning, security risk: Setting this to true may open yoursystems to potential URL redirect attacks. This property specifies whetherthe fully qualified referrer URL for form login redirects is preserved. Iffalse, the host for the referrer URL is removed and the redirect is tolocalhost. The equivalent custom property in the full application serverprofile is com.ibm.websphere.security.util.fullyQualifiedURL



Required: false

Data type: boolean

singleSignonEnabledDescription: Specifies whether single sign-on is enabled.

Default value: true

Required: false

Data type: boolean

ssoCookieNameDescription: Customizes the SSO cookie name. A custom cookie nameallows you to logically separate authentication between SSO domains andto enable customized authentication to a particular environment. Beforesetting this value, consider that setting a custom cookie name can causean authentication failure. For example, a connection to a server that has acustom cookie property set sends this custom cookie to the browser. Asubsequent connection to a server that uses either the default cookiename or a different cookie name, is not able to authenticate the requestvia a validation of the in-bound cookie. The equivalent custom propertyin the full application server profile iscom.ibm.websphere.security.customSSOCookieName.

Default value: LtpaToken2

Required: false

Data type: string

ssoDomainNamesDescription: A pipe (|) separated list of domain names that SSO Cookiesshould be presented. The equivalent custom property in the fullapplication server profile iscom.ibm.ws.security.config.SingleSignonConfig

Required: false

Data type: string

ssoRequiresSSLDescription: Specifies whether a SSO cookie is sent over SSL. Theequivalent custom property in the full application server profile iscom.ibm.websphere.security.customSSOCookieName


Required: false

Data type: boolean

ssoUseDomainFromURLDescription: Specifies whether to use the domain name from the requestURL for the cookie domain.


Required: false

Data type: boolean

useAuthenticationDataForUnprotectedResourceDescription: Specifies whether authentication data can be used whenaccessing an unprotected resource. The unprotected resource can access


validated authenticated data that it previously could not access. Thisoption enables the unprotected resource to call the getRemoteUser,isUserInRole, and getUserPrincipal methods to retrieve an authenticatedidentity. The equivalent custom property in the full application serverprofile is com.ibm.wsspi.security.web.webAuthReq=persisting.

Default value: true

Required: false

Data type: boolean

webAlwaysLoginDescription: Specifies whether the login() method will throw anexception when an identity has already been authenticated.


Required: false

Data type: boolean

webContainerConfiguration for the web container. PID is com.ibm.ws.webcontainer.


Attributes

listenersDescription: A comma separated list of listener classes.

Default value:

Required: false

Data type: string

decodeUrlAsUtf8Description: Decode URL using the an encoding setting of UTF-8.

Default value: true

Required: false

Data type: boolean

fileServingEnabledDescription: Enable file serving if this setting was not explicitly specifiedfor the application.

Default value: true

Required: false

Data type: boolean

disallowAllFileServingDescription: Disables all file serving by applications. The equivalentcustom property in the full application server profile iscom.ibm.ws.webcontainer.disallowAllFileServing.


Required: false

Data type: boolean

directoryBrowsingEnabledDescription: Enable directory browsing of an application.


Required: false

Data type: boolean

serveServletsByClassnameEnabledDescription: Enable servlets to be accessed in a web application using aclass name if not explicitly specified.


Required: false

Data type: boolean

disallowServeServletsByClassNameDescription: Disallows the use of serveServletsByClassnameEnabled onthe application server level. The equivalent custom property in the fullapplication server profile iscom.ibm.ws.webcontainer.disallowserveservletsbyclassname.



Required: false

Data type: boolean

doNotServeByClassNameDescription: A semi-colon delimited list of classes to be completelydisallowed from being served by classname. The equivalent customproperty in the full application server profile iscom.ibm.ws.webcontainer.donotservebyclassname.

Default value:

Required: false

Data type: string

trustHostHeaderPortDescription: Set this property to true and thecom.ibm.ws.webcontainer.extractHostHeaderPort custom property to trueto return the port number from the request host header first.


Required: false

Data type: boolean

trustedDescription: Enables the application server to use inbound privateheaders from the web server plug-in.

Default value: true

Required: false

Data type: boolean

extractHostHeaderPortDescription: The web container will return a port number from the hostheader, if any, or the URL port on which the client connection wasaccepted. The equivalent custom property in the full application serverprofile is com.ibm.ws.webcontainer.extracthostheaderport.


Required: false

Data type: boolean

httpsIndicatorHeaderDescription: For SSL offloading, set to the name of the HTTP headervariable inserted by the SSL accelerator/proxy/load balancer.

Default value:

Required: false

Data type: string

exposeWebInfOnDispatchDescription: If true, a servlet can access files in the WEB-INF directory. Iffalse (default), a servlet cannot access files the WEB-INF directory.


Required: false

Data type: boolean


decodeUrlPlusSignDescription: Decode the plus sign when it is part of the URL. Theequivalent custom property in the full application server profile iscom.ibm.ws.webcontainer.decodeurlplussign.


Required: false

Data type: boolean

channelWriteTypeDescription: When set to 'sync', responses will be written synchronously;otherwise, responses will be written asychronously. The equivalentcustom property in the full application server profile iscom.ibm.ws.webcontainer.channelwritetype.

Default value: async

Required: false

Data type: string

suppressHtmlRecursiveErrorOutputDescription: Suppresses the HTML output of a recursive error that cannotbe handled by an application's configured error page. The equivalentcustom property in the full application server profile iscom.ibm.ws.webcontainer.suppressHtmlRecursiveErrorOutput.


Required: false

Data type: boolean

fileWrapperEventsDescription: Web container will generate SMF and PMI data whenserving the static files. The equivalent custom property in the fullapplication server profile is com.ibm.ws.webcontainer.fileWrapperEvents.


Required: false

Data type: boolean

defaultTraceRequestBehaviorDescription: Restore HTTP TRACE processing. The equivalent customproperty in the full application server profile iscom.ibm.ws.webcontainer.DefaultTraceRequestBehavior.


Required: false

Data type: boolean

defaultHeadRequestBehaviorDescription: Restore the behavior where the HEAD request is not subjectto the security constraint defined for the GET method. The equivalentcustom property in the full application server profile iscom.ibm.ws.webcontainer.DefaultHeadRequestBehavior.


Required: false


Data type: boolean

tolerateSymbolicLinksDescription: Enables the web container to support the use of symboliclinks. The equivalent custom property in the full application server profileis com.ibm.ws.webcontainer.TolerateSymbolicLinks.


Required: false

Data type: boolean

symbolicLinksCacheSizeDescription: Initial size of the symbolic link cache. The equivalent customproperty in the full application server profile iscom.ibm.ws.webcontainer.SymbolicLinksCacheSize.

Default value: 1000

Required: false

Data type: int

enableErrorExceptionTypeFirstDescription: Web container is updated to search and use theexception-type before the error-code. The equivalent custom property inthe full application server profile iscom.ibm.ws.webcontainer.enableErrorExceptionTypeFirst.


Required: false

Data type: boolean

enableMultiReadOfPostDataDescription: Retain post data for multiple read accesses. The equivalentcustom property in the full application server profile iscom.ibm.ws.webcontainer.enablemultireadofpostdata.


Required: false

Data type: boolean

copyAttributesKeySetDescription: Web container will return an enumeration of a copy of thelist attributes to the servlet to avoid a concurrent access error by theservlet. The equivalent custom property in the full application serverprofile is com.ibm.ws.webcontainer.copyattributeskeyset.


Required: false

Data type: boolean

dispatcherRethrowsErDescription: Web container will re-throw errors allowing interestedresources to process them. The equivalent custom property in the fullapplication server profile iscom.ibm.ws.webcontainer.dispatcherRethrowser.

Default value: true


Required: false

Data type: boolean

ignoreSessiononStaticFileRequestDescription: Improves performance by preventing the web containerfrom accessing a session for static file requests involving filters. Theequivalent custom property in the full application server profile iscom.ibm.ws.webcontainer.IgnoreSessiononStaticFileRequest.


Required: false

Data type: boolean

invokeFilterInitAtStartupDescription: Web container will call the filter's init() method atapplication startup. The equivalent custom property in the full applicationserver profile is com.ibm.ws.webcontainer.invokeFilterInitAtStartup.

Default value: true

Required: false

Data type: boolean

enableJspMappingOverrideDescription: Allow the JSP mapping to be overridden so that theapplication can serve the JSP contents itself. The equivalent customproperty in the full application server profile iscom.ibm.ws.webcontainer.enablejspmappingoverride.


Required: false

Data type: boolean

enableDefaultIsElIgnoredInTagDescription: Correct the default behavior of the EL expression'sevaluation in the tag files. The equivalent custom property in the fullapplication server profile is com.ibm.ws.jsp.enabledefaultiselignoredintag.


Required: false

Data type: boolean

parseUtf8PostDataDescription: Web container will detect non URL encoded UTF-8 post dataand include it in the parameter values. The equivalent custom property inthe full application server profile iscom.ibm.ws.webcontainer.parseutf8postdata.


Required: false

Data type: boolean

logServletContainerInitializerClassLoadingErrorsDescription: Log servlet container class loading errors as warnings ratherthan logging them only when debug is enabled. The equivalent customproperty in the full application server profile iscom.ibm.ws.webcontainer.logservletcontainerinitializerclassloadingerrors.



Required: false

Data type: boolean

allowIncludeSendErrorDescription: Allow RequestDispatch to send errors on Include methods.The equivalent custom property in the full application server profile iscom.ibm.ws.webcontainer.allowincludesenderror.


Required: false

Data type: boolean

skipMetaInfResourcesProcessingDescription: Do not search the meta-inf directory for applicationresources. The equivalent custom property in the full application serverprofile is com.ibm.ws.webcontainer.skipmetainfresourcesprocessing.


Required: false

Data type: boolean

metaInfResourcesCacheSizeDescription: Initial size (number of entries) of the meta-inf resourcecache. The equivalent custom property in the full application serverprofile is com.ibm.ws.webcontainer.metainfresourcescachesize.name.

Default value: 20

Required: false

Data type: int

xPoweredByDescription: Alternative string for the X-Powered-By header setting. Theequivalent custom property in the full application server profile iscom.ibm.ws.webcontainer.xpoweredby.

Required: false

Data type: string

disableXPoweredByDescription: Disable setting of the X-Powered-By header. The equivalentcustom property in the full application server profile iscom.ibm.ws.webcontainer.disablexpoweredby.


Required: false

Data type: boolean

deferServletLoadDescription: Defer servlet loading and initialization until the first request.

Default value: true

Required: false

Data type: boolean

asyncMaxSizeTaskPool


Description: Maximum size of tasks in the Async task pool beforeautomatically purging canceled tasks. The equivalent custom property inthe full application server profile iscom.ibm.ws.webcontainer.asyncmaxsizetaskpool.

Default value: 5000

Required: false

Data type: int

asyncPurgeIntervalDescription: Time interval to wait between each required purge of thecancelled task pool. The equivalent custom property in the fullapplication server profile is com.ibm.ws.webcontainer.asyncpurgeinterval.


Required: false

Data type: int

asyncTimeoutDefaultDescription: Async servlet timeout value used when a timeout value hasnot been explcitly specified. The equivalent custom property in the fullapplication server profile iscom.ibm.ws.webcontainer.asynctimeoutdefault.


Required: false

Data type: int

asyncTimerThreadsDescription: Maximum number of threads to use for async servlettimeout processing. The equivalent custom property in the fullapplication server profile is com.ibm.ws.webcontainer.asynctimerthreads.

Default value: 2

Required: false

Data type: int

wimRegistry

Configuration properties for the Federated Manager user registry. PID iscom.ibm.ws.wim.registry.config.

Attributes

realmDescription: The realm name that represents the user registry.

Default value: WIMRegistry

Required: false

Data type: string


wlmClassificationContains, as child elements, the classification rules WLM will use when classifyingrequests. PID is com.ibm.ws.zos.wlm.classification.

Attributes

classificationNameDescription: optional classification name

Default value: null

Required: false

Data type: string

wsSecurityClient

Web Services Security default configuration. PID iscom.ibm.ws.wssecurity.client.config.

Attributes

ws-security.usernameDescription: User information to create Username Token.

Required: false

Data type: string

ws-security.passwordDescription: User password information needed to create UsernameToken.

Required: false


ws-security.callback-handlerDescription: Password callback handler implementation class.

Required: false

Data type: string

ws-security.encryption.usernameDescription: Alias used for accessing encryption keystore.

Required: false

Data type: string

ws-security.signature.usernameDescription: Alias used for accessing signature keystore.

Required: false

Data type: string


Sub-elements

signaturePropertiesDescription: Required Signature configuration.

Required: false

Data type: Config information such as keystore type, keystore password.

org.apache.ws.security.crypto.merlin.keystore.typeDescription: JKS, JCEKS or PKCS11

Required: false

Data type: string

org.apache.ws.security.crypto.merlin.keystore.passwordDescription: Password to access keystore file.

Required: false


org.apache.ws.security.crypto.merlin.fileDescription: The location of the keystore

Required: false

Data type: string

org.apache.ws.security.crypto.merlin.truststore.fileDescription: The location of the truststore

Required: false

Data type: string

org.apache.ws.security.crypto.merlin.truststore.passwordDescription: The truststore password.

Required: false


org.apache.ws.security.crypto.merlin.truststore.typeDescription: The truststore type.

Required: false

Data type: string

org.apache.ws.security.crypto.providerDescription: Provider used to create Crypto instances. Defaults to"org.apache.ws.security.components.crypto.Merlin".

Default value: org.apache.ws.security.components.crypto.Merlin

Required: false

Data type: string

org.apache.ws.security.crypto.merlin.keystore.providerDescription: The provider used to load keystores. Defaults toinstalled provider.

Required: false

Data type: string


org.apache.ws.security.crypto.merlin.cert.providerDescription: The provider used to load certificates. Defaults tokeystore provider.

Required: false

Data type: string

org.apache.ws.security.crypto.merlin.x509crl.fileDescription: The location of an (X509) CRL file to use.

Required: false

Data type: string

org.apache.ws.security.crypto.merlin.keystore.private.passwordDescription: The default password used to load the private key.

Required: false


encryptionPropertiesDescription: Required Encryption configuration.

Required: false



Required: false

Data type: string


Required: false




Required: false

Data type: string


Required: false

Data type: string


Required: false

Data type: string

org.apache.ws.security.crypto.merlin.cert.providerDescription: The provider used to load certificates. Defaults to


keystore provider.

Required: false

Data type: string


Required: false

Data type: string


Required: false


wsSecurityProvider

Web Services Security default configuration for provider. PID iscom.ibm.ws.wssecurity.config.


Attributes

ws-security.usernameDescription: User information to create Username Token.

Required: false

Data type: string

ws-security.callback-handlerDescription: Password callback handler implementation class.

Required: false

Data type: string

ws-security.encryption.usernameDescription: Alias used for accessing encryption keystore.

Required: false

Data type: string

ws-security.signature.usernameDescription: Alias used for accessing signature keystore.

Required: false

Data type: string

callerTokenDescription: Caller token.

Required: false

Data type: string

ws-security.enable.nonce.cacheDescription: Whether to cache UsernameToken nonces.

Default value: true

Required: false

Data type: boolean


Sub-elements

signaturePropertiesDescription: Required Signature configuration.

Required: false



Required: false

Data type: string


Required: false



Required: false

Data type: string

org.apache.ws.security.crypto.merlin.truststore.fileDescription: The location of the truststore

Required: false

Data type: string

org.apache.ws.security.crypto.merlin.truststore.passwordDescription: The truststore password.

Required: false


org.apache.ws.security.crypto.merlin.truststore.typeDescription: The truststore type.

Required: false

Data type: string



Required: false

Data type: string


Required: false

Data type: string


org.apache.ws.security.crypto.merlin.cert.providerDescription: The provider used to load certificates. Defaults tokeystore provider.

Required: false

Data type: string


Required: false

Data type: string


Required: false


encryptionPropertiesDescription: Required Encryption configuration.

Required: false



Required: false

Data type: string


Required: false




Required: false

Data type: string


Required: false

Data type: string


Required: false

Data type: string

org.apache.ws.security.crypto.merlin.cert.providerDescription: The provider used to load certificates. Defaults to


keystore provider.

Required: false

Data type: string


Required: false

Data type: string


Required: false


Administering the Liberty profile by using developer tools


You can modify how the workbench interacts with the Liberty profile by using theserver editor.

Procedure1. In the Servers view, right-click the server and select Open.2. The server editor opens.

What to do next

You can modify the publishing, timeout, and other settings regarding theinteraction between the workbench and the server.

Editing the Liberty profile configuration by using developertools


You can modify the behavior of the Liberty profile by editing the configuration.For example, you can configure which HTTP ports to use, what features areenabled, and logging and tracing settings.

Before you begin

For a description of the underlying process of configuring a server, and detailedinformation about specific aspects of server configuration, see “Administering theLiberty profile manually” on page 351.

Procedure1. To open the Server Configuration editor, select any of the following options:

v In the Servers view, right-click the server configuration and select Open.v In the Enterprise Explorer view, expand your server project and the server

folder. Right-click the server.xml file and select Open.


2. Under the Configuration Structure section the elements in the configurationare displayed.

3. Under the Feature Manager Details section the details for the currentlyselected element are displayed.

4. To add new elements, select Server Configuration under the ConfigurationStructure section then click Add.

5. To add child elements, select the parent element under the ConfigurationStructure section and then click Add.

6. You can remove or move elements by selecting the element and using theRemove, Up, and Down buttons.

Starting and stopping a server by using developer toolsYou can start and stop a server by using the Liberty profile developer tools.

Procedurev To start a server:

In the Servers view, right-click the server and click Start to start the server or

click Debug to start the server in the debug mode. Alternatively, click to

start the server, or click to start the server in the debug mode.v To stop the server:

In the Servers view, right-click the server and click Stop. Alternatively, clickto stop the server.

Tip: In the Servers view, you must select the server entry to perform these tasks.Do not select the server configuration entry, for example Server Configuration[server.xml], to perform these tasks.

What to do next

You can configure the server elements by using the tools.

Defining a utility project as a shared libraryDistributed operating systems

You can define a utility project as a shared library and associate defined sharedlibraries with an application or web project.

Before you begin

To use the shared library function in the workbench, you must create a utilityproject and define it as a shared library. The utility project is the only project typethat can be used as a shared library.

About this task

A shared library is an external Java archive (JAR) file that is used by one or moreapplications. Using shared libraries enables multiple application published on aserver to use a single library, rather than use multiple copies of the same library.After you associate shared libraries with an application or project, the application


or module class loader loads classes in the shared libraries and makes those classesavailable to the application or module.You can define a utility project as a shared

library, or, alternatively, you can drop the shared library into one of:v ${shared.resources.dir}/mylib/<lib id>

v ${server.config.dir}/mylib/<lib id>

where <lib id> is a directory that you have created. You can drop the jar(s) intothat directory and then use the <lib id> to reference them.

Procedure

To define a utility project as a shared library:1. Create a utility project:

a. In the toolbar, select File > New > Project.b. Expand Java EE and select Utility Project. Click Next.c. In the Project name field, specify a name for the utility project.d. Under the Target runtime section, verify the WebSphere Application Server

Liberty profile is selected.e. Under the Ear membership section, clear the Add project to an EAR check

box.f. Click Finish.

2. Define the artifacts in the newly created utility project. For example, you canadd Java classes to the utility project.

3. Define the utility project as a shared library:a. In the Project Explorer view, right-click the utility project and select

Properties > Liberty Profile Shared Library.b. In the Shared library ID field, type a string as an identifier for the shared

library.c. In the Archive directory field, type or browse to a directory where you

want to place the compressed copy of your utility project as a JAR file. Thefile name convention of the JAR file is utilityProjectName.jar, whereutilityProjectName is the name of the utility project.

d. In the Liberty Profile Shared Library page, click Apply to confirm yourchanges. Click OK to close the Properties window.

4. Add the utility project to the server. Distributed operating systems For more detailssee “Adding and running an application on the Liberty profile by usingdeveloper tools” on page 519 topic.

Results

Here is an example entry added to the server configuration (server.xml) file:<library id="libid"><fileset dir="C:\temp" includes="Util.jar"/></library>

In addition, the JAR file is added in the specified archive directory. In the previousexample, the Util.jar file is added in the C:\temp directory.

Setting a web project to use shared libraries



If you have a utility project defined as a shared library, you can associate definedshared libraries with a web project.

Before you beginv Define a utility project as a shared library.

About this task

A shared library is an external Java archive (JAR) file that is used by one or moreapplications. Using shared libraries enables multiple application published on aserver to use a single library, rather than use multiple copies of the same library.After you associate shared libraries with an application or project, the applicationor module class loader loads classes in the shared libraries and make those classesavailable to the application or module.

Procedure1. To set a web project to use shared libraries:

a. In the Project Explorer view, right-click your web project that you want toassociate shared libraries.

b. Select Properties > Liberty Profile Shared Libraries.c. In the IDs field, specify one or more shared library identifiers that you want

the project to reference. To specify multiple identifiers, use acomma-separated list. For example: ID1, ID2, ID3

Tip: The shared library identifier is the value specified in the Shared LibaryID field from the Defining a utility project as a shared library task. You canset an library id by defining a utility project as a shared library, or,

alternatively, you can create a directory name under either:v ${shared.resources.dir}/mylib/

v ${server.config.dir}/mylib/

2. You might want to add its associating utility projects to the class path forcompilation-purpose:a. In the Project Explorer view, right-click your project that you are

associating shared libraries.b. Select Properties > Java Build Path.c. Select the Projects tab.d. Click Add.e. Select the utility projects that the project references.

3. Develop the artifacts in the web project. For example, you can add a servlet ina web project that references classes in the shared libraries.

4. Add the web project to the server. Distributed operating systems For more detailssee “Adding and running an application on the Liberty profile by usingdeveloper tools” on page 519 topic.

Results

Here is an example entry added to the server configuration (server.xml) file:<application type="war" id="web" name="web" location="web.war"><classloader commonLibraryRef="libid"/></application>


Exploring the runtime environment by using developer toolsDistributed operating systems

You can use the WebSphere Runtime Explorer view to browse the availableservers as well as any shared configurations and applications for a runtimeenvironment. This view shows all of the available servers for the runtimeenvironment as opposed to the Servers view which shows only those servers thatare configured in the workspace. In both the WebSphere Runtime Explorer andServers view, you can expand each server to show the configuration for that server.

Before you begin

The application server that the WebSphere Runtime Explorer view supports is theWebSphere Application Server Liberty profile.

About this task

You can use the WebSphere Runtime Explorer view to complete the followingtasks:v View the servers defined in a runtime environmentv View the shared applications defined in a runtime environmentv View the shared configurations files defined in a runtime environmentv Create a new runtime environmentv Create a server in a runtime environment

Procedure

To open the WebSphere Runtime Explorer view:1. In the toolbar of the workbench, select Window > Show View > Other.2. In the Show View window, expand Server and select WebSphere Runtime

Explorer. Click OK.

Displaying the server configuration in a merged viewDistributed operating systems

You can use the Merged Configuration view to see a flattened view of the serverconfiguration and any recursively included configuration files.

About this task

In the Server Configuration editor, under the Configuration Structure section, youcan use the Include element to import files that contain additional configurationsettings. The Include element can embed multiple layers of configuration fileswithin the server.xml file, which can make the configuration difficult to readwithout tools. The Merged Configuration view provides a flattened view of theserver configuration and any recursively included configuration files. This is aread-only view and cannot be edited.

Procedure

To display the server configuration in a merged view:


In the Servers view, right-click the server configuration and select Open MergedView.

Example

Here is an example of the source code for the server.xml file. Look at the includetag which imports the common.xml file:<server><featureManager><feature>jsp-2.2</feature><feature>servlet-3.0</feature></featureManager><application id="Web2.5" location="Web2.5.war" name="Web2.5" type="war"/><include location="common.xml"/></server>

Here is an example of the source code for the common.xml file:<server><application id="Setup" location="Setup.war" name="Setup" type="war"/></server>

Look under the Configuration Structure sections to see the difference between theServer Configuration editor and Merged Configuration view. The MergedConfiguration view replaces the Include: common.xml element from the ServerConfiguration editor with Application: Setup element.

Viewing the schema documentation for the serverconfiguration


You can view the schema documentation for the server configuration (server.xmlfile) within the workbench. The documentation provides information about theconfiguration elements that are available, the default settings, and details for eachof the elements.

Procedure

In the Servers view, right-click on the server configuration and select OpenSchema Reference.

Generating a Liberty profile server dump using developertools

Using the Liberty profile Utilities menu, you can generate a server dump forsupport.

About this task

You can use the Utilities menu of your Liberty profile to generate a server dump tocapture all service-related information for support.

Procedure1. In the Servers view, right-click your Liberty server profile, and select Utilities >

Generate dump for Support....2. In the Generate Dump page, click Finish to create the server dump file.3. In the Console view, the path to the server dump is indicated:


Server TestServer dump complete inD:\LibertyUnzip\wlp\usr\servers\TestServer\TestServer.dump-12.03.22_15.00.11.zip.

Packaging a Liberty profile server by using developer toolsYou can create a compressed file containing a server runtime environment, serverconfiguration, and applications using the packaging wizard.

About this task

Because a Liberty server is lightweight, you might find it useful to package upyour applications and server in a compressed file. You can then store this package,distribute it to colleagues, use it to deploy the application to a different location orto another machine, or even embed it in your product distribution.

Procedure1. In the Servers view, stop the server.2. Right-click your Liberty server profile, and select Utilities > Package Server....3. In the Package Server page, in the Archive field, type a filename and path for

your archive package, or click Browse to locate a filename and path. Thisfilename can include a full path name. If the full path is omitted, a compressedfile called package_file_name.zip is created in the ${server.output.dir} directory.In the Include: field, select whether to include:v All server content (all), which includes binary files.v Only server configuration and applications (usr)

4. Click Finish.

Adding a data source by using developer toolsYou can add a data source to your application using the developer tools.

Procedure1. In the Project Explorer view, expand liberty_profile_name > servers >

server_name > server.xml, and select Open With > Liberty ProfileConfiguration Editor.

2. In the design view, select Server Configuration, and click Add.3. On the Select item to add to Server Configuration: page, select Data Source.4. On the Data Source Details panel, beside JDBC Driver, click New.5. On the Configure a JDBC driver page,

v In the Id field, type an ID for your JDBC driver, for example derbyEmbedded.v In the Library ref: field, select an option from the drop-down list, or click

New to create a new one.– On the Configure a shared library page, in the Id field, type the ID for

your JDBC driver that you created, for example derbyEmbedded.– In the Fileset ref: field, select an option from the drop-down list, or click

New to create a new one.- On the Configure a fileset page, in the Id field, type an ID for your

JDBC driver, for example derbyEmbedded.- In the Base directory field, type a path for your base directory or click

Browse to locate a library location path.- In the Includes field, type the name of your data source, for example

derby.jar, or click Browse to locate the data source archive file thatyou want to include.


- In the Excludes field, type the archives that you want to exclude, orclick Browse to locate the data source archive file that you want toexclude. Click Okay

– Click Okay

v Click Okay

6. Your JDBC data source has been added to your application.

Administering the Liberty profile manuallyYou can administer the Liberty profile from the command prompt, configure itwith web server plug-ins, and capture its status. You can package a Liberty serverconfiguration along with the applications that it runs, for distribution to colleagues,or installation on other systems. If available, you can use the Equinox OSGiconsole to aid with debugging.

About this task

The server.xml file is the primary configuration file for the server. You can editthis file, and the files it includes, in a text editor. You can also change the locationof the server.xml file. However, for most configurations you do not need to dothis.

The bootstrap.properties file is used to specify properties that need to beavailable before the main configuration is processed. If you update thebootstrap.properties file, you must restart the server with the --clean option forthe changes to take effect.

Example

All the elements that can be configured in the server.xml file, and the files itincludes, are described in “Liberty profile: Configuration elements in the server.xmlfile” on page 97. However, the only required element is a server definition:<server/>

Beyond this server definition, you only specify overrides and additions to thedefault configuration values. For example, to change the transaction timeout value,you specify:<transactions timeout="30" />

Some attributes can have multiple values. For example, you use a list of values todefine the features that are to be provided by the server:<server>



See also “Adding and removing Liberty features” on page 368.

Where multiple instances of a resource type can be configured, for exampleapplications or data sources, you need only provide the attributes that are uniquefor the resource. You can let the other attributes use the default values, or overridethem as needed. Therefore the contents of the server.xml file can be brief. Forexample, here is a complete server configuration to run a web application:


<server><featureManager>

<feature>servlet_3.0</feature></featureManager><application name="snoop" location="/mywebapps/snoop" id="snoop" type="war"/>

</server>

For detailed information about specific aspects of server configuration, see thesubtopics.

Customizing the Liberty profile environmentYou can customize the Liberty profile environment by using certain specificvariables to support the placement of product binary files and shared resources inread-only file systems.

About this task

The following Liberty profile specific variables can be used to customize theLiberty profile environment:v ${wlp.install.dir}

This configuration variable has an inferred location. The installation directory isalways set to the parent of the directory containing the launch script, or theparent of the /lib directory containing the target JAR files.

v WLP_USER_DIR

This environment variable can be used to specify an alternative location for${wlp.user.dir}. This variable must be an absolute path. If this variable isspecified, the runtime environment looks for shared resources and serverdefinitions in the specified directory. The ${server.config.dir} is equivalent to${wlp.user.dir}/servers/serverName.

v WLP_OUTPUT_DIR

This environment variable can be used to specify an alternative location forserver generated output such as logs, the workarea directory, and generated files.This variable must be an absolute path. If this environment variable is specified,${server.output.dir} is set to the equivalent of WLP_OUTPUT_DIR/serverName. Ifthis environment variable is not specified, ${server.output.dir} is the same as${server.config.dir}.

You can specify WLP_OUTPUT_DIR and WLP_USER_DIR environment variables inserver.env files. You can also specify JVM options in jvm.options files.

Procedurev Specify environment variables by using server.env files.

You can use server.env files at the installation and server levels to specifyenvironment variables such as JAVA_HOME, WLP_USER_DIR, and WLP_OUTPUT_DIR.For example:# Use a specific Java binaryJAVA_HOME=/opt/ibm/java-i386-60/jre# JAVA_HOME=c:\Java

Note:

– The server.env files support only key=value pairs.– Empty lines and lines starting with the # character are ignored.– There are no escape characters; all characters are literal, including

back-slashes and leading and trailing whitespace.– Shell and variable expansion are not supported.


– WLP_USER_DIR can be specified only in the ${wlp.install.dir}/etc/server.env file because the purpose of this variable is to specify where theremaining configuration is located. After the remaining configuration is foundand merged, no further configuration in a different location is expected, orsupported.

The server management script searches for server.env files in two locations:${wlp.install.dir}/etc/server.env and ${server.config.dir}/server.env. Ifboth files are present, the contents of the two files are merged; values in theserver-level file take precedence over values in the runtime-level file.You can also specify these environment variables in the shell environment, butthe server.env files take precedence over those variables.

v Customize JVM options by using jvm.options files.You can use jvm.options files at the runtime and server levels to specifyadditional server startup options, for example, -X arguments. The options areapplied when the start, run, and debug actions are started through the servermanagement script. Be sure to specify only one option per line. For example:# Set the maximum heap size to 1024m.-Xmx1024m

# Set a system property.-Dcom.ibm.example.system.property=ExampleValue

# Enable verbose output for class loading.-verbose:class

The server management script searches for jvm.options in two locations:${wlp.install.dir}/etc/jvm.options and ${server.config.dir}/jvm.options. Ifboth files are present, the options in the ${server.config.dir}/jvm.options fileare used.

Note:

– Empty lines and lines starting with the # character are ignored.– There are no escape characters; all characters are literal, including

back-slashes and leading and trailing whitespace.– Shell and variable expansion are not supported.

Administering the Liberty profile from the command promptYou can use the server and ws-launch.jar commands to create a server, to start, orstop a server, to check if it is running, and to help debug it.

About this task

The wlp/bin directory contains a script called server to help with controlling theserver process. The syntax of this script is as follows:server <action> [server] [options]

For available values of the options, see “Liberty profile: server command options”on page 354.

This script supports the following actions:

create A command that creates a new server.

run A command that launches the server in the foreground.

debug A command that runs the named server in the console foreground after adebugger connects to the debug port. The default port is 7777.


dump A command that creates a snapshot of a server and saves the result into anarchive file for further tuning and diagnosis.

javadumpA command that creates a snapshot of the server JVM and saves the resultinto files. Each dump type creates a file in ${server.output.dir}, but notall dump types are supported by all virtual machines.

packageA command that packages a server.

start A command that launches the server as a background process.

stop A command that stops a running server.

status A command that checks to see whether a specified server is running.

versionA command that displays the version information of current server andJava runtime environment.

help A command that gets command-line script help, including details ofadditional options.

Note: If a server is not specified on the command line, the action is performedagainst the default server instance, defaultServer, if it exists.

You can also carry out similar actions by using the executable JAR filews-launch.jar that is in the wlp/lib directory.

Example

To run the server script on Windows systems:server.bat create server_nameserver.bat package server_nameserver.bat run server_nameserver.bat help server_name

To run the server script on other systems:server create server_nameserver package server_nameserver run server_nameserver help server_name

To run the executable JAR file ws-launch.jar without using the server script:java -javaagent:lib/bootstrap-agent.jar -jar lib/ws-launch.jar server_name --createjava -javaagent:lib/bootstrap-agent.jar -jar lib/ws-launch.jar server_namejava -javaagent:lib/bootstrap-agent.jar -jar lib/ws-launch.jar --help

The --help option provides information about additional command-lineparameters for the executable JAR file ws-launch.jar , such as --stop, --version,--clean, --include.

Liberty profile: server command optionsThe server command supports starting, stopping, creating, packaging, anddumping a Liberty profile server. This topic describes all available options and exitcodes that you can use with the server command and the equivalent executable jarfile ws-launch.jar.


Syntax

The command syntax is as follows:server action serverName [options]

where the value of action represents the operation that you can perform on aLiberty profile server. See available administration operations for the Libertyprofile from the command prompt.


Options

The following options are available for the server command:

--archive=“path to the target archive file”Specifies a target file for the package or dump operation. This path can beeither a relative path, which is relative to the installation root directory ofthe Liberty profile, or an absolute path. The default archive target is acompressed file with the server name, which will be stored in theinstallation root directory. Use quotation marks if the value containsspaces. You can use this option for both package and dump operations.

--cleanCleans all cached information related to this server instance.

--include=value,value,...Specifies the type of diagnostic information to be captured. The value of--include is a comma-delimited list of values, which depends on theaction and can be as follows:v all specifies to package all the files in the Liberty profile installation

directory. If the ${WLP_USER_DIR} and ${WLP_OUTPUT_DIR} are defined inthe server.env file, the files under them are packaged. This value onlyapplies to the package operation.

v usr specifies to package the files in the ${WLP_USER_DIR} directory. Thisvalue only applies to the package operation.

v heap is used to help diagnose the excessive memory consumption andmemory leaks, which shows live objects in the memory and referencesbetween them. On IBM J9 virtual machines, the resulting file is namedheapdump.date.time.processID.sequenceNumber.phd. On HotSpot virtualmachines, the resulting file is namedjava.date.time.processID.sequenceNumber.hprof. This value applies toboth the dump and javadump operations

v system is also used to help diagnose the excessive memory consumptionand memory leaks, but they are also useful for finding defects in thevirtual machine. These dumps are only supported on IBM J9 virtualmachines, the resulting file is namedcore.date.time.processID.sequenceNumber.dmp. This value applies toboth the dump and javadump operations.

v thread is used to help diagnose hung threads, deadlocks, and cansometimes be used for diagnose excessive CPU issues. These dumps arealways created with the server javadump command. On IBM J9 virtualmachines, the resulting file is namedjavacore.date.time.processID.sequenceNumber.txt. On HotSpot virtual


machines, the resulting file is namedjavadump.date.time.processID.sequenceNumber.txt. This value can alsobe applied to the dump operation.

Note: The thread dump type is only supported when the server isrunning on the Java SDK. If the server is started with a JRE, an errorwill be reported indicating that the server does not support the dumptype. This restriction only applies to HotSpot virtual machines; thethread Java dump type is supported on any IBM JVM (JRE or SDK).

Exit codes

The following exit codes are available for the server command and the equivalentexecutable JAR file ws-launch.jar:

0 OK. 0 indicates successful completion of the requested operation. Forserver status, 0 indicates that the server is running.

1 For server status, 1 indicates that the server is not running. For otheroperations, it indicates invocation of a redundant operation. For example,starting a started server or stopping a stopped server. This code might alsobe returned by JVM if invalid Java options are used.

2 The server does not exist.

3 An unsupported action was called on a running server. For example, theserver is running when the package action is called.

4 An unsupported action was called on a stopped server. For example, theserver is not running when the dump action is called

5 Unknown server status. For example, the workarea directory is missing, orthe Attach API fails to work.

>=20 Return codes greater than or equal to 20 indicates that an error occurredwhile performing the requested . Messages will be printed and captured inlog files with more information about the error.

Usage

The following examples demonstrate the correct syntax:server runserver start myserver --cleanserver package myserver --archive="c:\mybackup\" --include=allserver dump myserver --archive="c:\mybackup\" --include=threadserver javadump myserverserver javadump myserver --include=heap,system

Generating a Liberty profile server dump from the commandpromptFrom the command prompt you can use the server dump or server javadumpcommand to capture status information for a Liberty profile server.

About this task

The server dump command is useful for problem diagnosis of a Liberty profileserver because the result file contains server configuration, log information, anddetails of the deployed applications in the workarea directory. The command canbe applied to either a running or a stopped server.

For a running server, the following information is also included:


v State of each OSGi bundle in the serverv Wiring information for each OSGi bundle in the serverv Component list managed by the Service Component Runtime (SCR) environmentv Detailed information of each component from SCRv Configuration administration data of each OSGi bundlev Information about registered OSGi servicesv Runtime environment settings such as JVM, heap size, operating system, thread

information, and network status

The server javadump command is useful fordiagnosing problems at the JVM level, such as hung threads, deadlocks, excessiveprocessor, excessive memory consumption, memory leaks, and defects in thevirtual machine. The command can only be used on a running server. Each dumptype creates a file in ${server.output.dir}, but not all dump types are supportedby all virtual machines. See “Liberty profile: server command options” on page354.

Procedure1. Open a command prompt, then change directory to the wlp/bin directory.2. Capture the status information by using one of the following command-line

tools. If you do not specify a server name, defaultServer is used.v To create a snapshot of the server status, use server dump command.

– Distributed operating systems

server dump server_name --archive=package_file_name.dump.zip --include=heap

where package_file_name.dump.zip is a file name that you choose. Thisfile name can include a full path name. If the full path is omitted, acompressed file called package_file_name.dump.zip is created in the${server.output.dir} directory.

The --include parameter is optional. You canrequest additional memory dump types. For example, --include=heap optionrequests a heap dump; --include=thread,heap,system option requests athread dump, a heap dump, and a system dump.

v To create a snapshot of the JVM status, useserver javadump command.

– Distributed operating systems

server javadump server_name --include=heap

The --include parameter is optional. You can request additional memorydump types. For example, --include=heap option requests a thread dumpand a heap dump; --include=heap,system option requests a thread dump, aheap dump, and a system dump.

Note: The resulting file is created by using UTF-8 encoding for entry names, soyou must use a tool capable of opening the file by using UTF-8 encoding forentry names. The jar command in a Java SDK uses this format.


Results

If the specified server does not exist, the command does not succeed. If thespecified server exists, a result file is created that contains the status information ofthe server.

Packaging a Liberty profile server from the command promptFrom the command prompt you can create a compressed file containing a Libertyprofile runtime environment, the files in the shared resources directory, a specificserver, and the applications that are embedded in the server. You can also chooseto exclude the runtime binaries from the compressed file.

About this task

The Liberty server is lightweight, therefore you can easily package a serverinstallation in a compressed file. You can then store this package, distribute it tocolleagues, use it to deploy the installation to a different location or to anothermachine, or even embed the installation in a product distribution.

Note: Distributed operating systems The resulting file is created by using UTF-8encoding for entry names, so you must use a tool capable of opening the file byusing UTF-8 encoding for entry names. The jar command in a Java SDK uses thisformat.

Procedure

To package a Liberty profile server from the command prompt, complete thefollowing steps:1. Open a command prompt, then change directory to the wlp/bin directory.2. Stop the server.3. Package the server.

Run the following command. If you do not specify a server name,defaultServer is used. If you do not specify the --archive parameter, the valueof server_name is used for package_file_name, and the compressed file is createdin the ${server.output.dir} directory.

vDistributed operating systems

server package server_name --archive=package_file_name.zip --include=all

where package_file_name.zip is a file name that you choose. This file namecan include a full path name. If the full path is omitted, a compressed filecalled package_file_name.zip is created in the ${server.output.dir} directory.

You can also use the --include option with this command. For example, the--include=all option packages the runtime binaries and the relevant files inthe ${WLP_USER_DIR} directory; the --include=usr option packages onlyrelevant files in the ${WLP_USER_DIR} directory, effectively excluding the runtimebinaries from the compressed file.

Starting and stopping a server from the command promptYou can use the server tasks to start or stop a server.


About this task

The wlp/bin directory contains a script called server to help with controlling theserver process. The syntax of this script is as follows:server action serverName [options]

For available values of [options], see “Liberty profile: server command options” onpage 354.


Procedurev Use the following command to start the server:

server start serverName

where serverName is the name of the server.v Use the following command to stop the server:

server stop serverName

where serverName is the name of the server.

Example

To start or stop a server by using the server script on Windows systems:server.bat start serverName

server.bat stop serverName

To start or stop a server by using the server script on other systems:server start serverName

server stop serverName

Using Ant to automate tasks for the Liberty profileApache Ant is a Java library tool for automating the build process. You can useAnt tasks provided by the Liberty profile to manage the server and applications.

Before you begin

The Ant plug-in for the Liberty profile is located in the dev/tools/ant directory ofthe server image. This plug-in contains a set of Ant tasks. If you want to use thesetasks in your build script, you must make sure the plug-in is available on the Antclasspath. One way of doing this is to copy the plug-in file wlp-anttasks.jar tothe /lib directory of the Ant installation, and declare the antlib namespace in thebuild.xml file. For example:

<project .... xmlns:wlp="antlib:com.ibm.websphere.wlp.ant">...

</project>

The namespace can be any string, provided you avoid name conflicts. After that,you must use the namespace as a prefix of the Ant tasks for the Liberty profile. Forexample, you must use wlp:server when calling the server task.

About this task

You can create build scripts that use these Ant tasks to package, install, and testyour application on the Liberty profile.


Procedurev Manage the Liberty profile server.v Install applications on a Liberty profile server.v Remove application from a Liberty profile server.

Liberty profile: Ant task - server:

The server task can be used to manage the status of a Liberty profile server.

Description

The server task supports the following options to manage the status of a Libertyprofile server:v create, which creates a named server instance.v start, which starts the named server instance. If the server instance does not

exist, this option creates one by default.v stop, which stops the named server.v status, which checks the server status.v package, which packages the named server and its deployed applications.

Attributes

The following table describes attributes of the server task.

Table 11. The attributes of the server task.

The first column contains a list of attributes, the second column contains a description ofeach attribute, and the third column states whether this attribute is required.

Attribute Description Required

installDir Location of the Libertyprofile server.

Yes

operation Server operations availableas options: create, start,stop, status, and package.

Yes

serverName Name of the Liberty profileserver instance. The defaultvalue is defaultServer.

No

userDir Value of the ${wlp_user_dir}variable. The default value is${installDir}/usr/servers/${serverName}.

No

outputDir Value of the${wlp_output_dir} variable.The default value is${installDir}/usr/servers/${serverName}

No

clean Attributes that determineswhether to operate the serverusing the clean option.

No

timeout Waiting time before theserver starts or stops. Thedefault value is 30 seconds.The unit is milliseconds.

No


Table 11. The attributes of the server task (continued).



archive Location of the compressedfile when packaging a server.The value must be a filename and only works for thepackage option.

No

ref Reference to an existingserver task definition toreuse its serverconfiguration. The value canbe null when other requiredattributes are set.

No

Example

This example shows how to use the server task in your build.xml file:<wlp:server id="wlp.ant.test" installDir="${wlp_install_dir}" operation="start"

serverName="${serverName}" userDir="${wlp_usr}" outputDir="${wlp_output}" /><wlp:server ref="wlp.ant.test" operation="status"/>

Liberty profile: Ant task - deploy:

The deploy task can be used to install applications on a Liberty profile server.

Description

The deploy task supports deployment of one or more applications to the Libertyprofile server.

Attributes

The following table describes attributes of the deploy task.

Table 12. The attributes of the deploy task.




Yes


No


No


Table 12. The attributes of the deploy task (continued).



outputDir Value of the${wlp_output_dir} variable.The default value is${installDir}/usr/servers/${serverName}.

No

file Location of a singleapplication to be deployed.See file attribute in ApacheAnt. The application typecan be war, eba, zip, rar , orjar.

Yes, only when the filesetattribute is not specified.

fileset Location of multipleapplications to be deployed.See fileset attribute inApache Ant.

Yes, only when the fileattribute is not specified.

timeout Waiting time before thedeployment completessuccessfully. The defaultvalue is 30 seconds. The unitis milliseconds.

No


No

Example

This example shows how to use the deploy task in your build.xml file:<wlp:deploy ref="wlp.ant.test" >

<fileset dir="${basedir}/resources/"><include name="**/*.war"/>

</fileset></wlp:deploy><wlp:deploy ref="wlp.ant.test" file="${basedir}/resources/SimpleOSGiApp.eba" timeout="40000"/>

Liberty profile: Ant task - undeploy:

The undeploy task can be used to remove applications from a Liberty profile server.

Description

The undeploy task supports undeployment of a single application from the Libertyprofile server.


http://ant.apache.org/manual/Types/fileset.html




Attributes

The following table describes attributes of the undeploy task.

Table 13. The attributes of the undeploy task.

The first column contains a list of attributes, the second column contains a description ofeach attribute, and the third column represents whether this attribute is required.



Yes


No


No

outputDir Value of the${wlp_output_dir} variable.The default value is${installDir}/usr/servers/${serverName}.

No

file Name of application to beremoved. The applicationtype can be war, eba, zip,rar, or jar.

Yes

timeout Waiting time before theundeployment completessuccessfully. The defaultvalue is 30 seconds. The unitis milliseconds.

No


No

Example

This example shows how to use the undeploy task in your build.xml file:<wlp:undeploy ref="wlp.ant.test" file="SimpleOSGiApp.eba" timeout="60000" />

Using Maven to automate tasks for the Liberty profileApache Maven is a software project management tool based on the concept of aproject object model (POM). You can use the Maven plug-in provided by theLiberty profile to manage the server and applications.

Before you begin

The Maven plug-in for the Liberty profile is located in a public central repository.This plug-in contains a set of Maven tasks. If you want to use these tasks in yourMaven project, you must make sure the plug-in repository is specified in thepom.xml file of your project. For example:


<pluginRepository><id>Liberty</id><name>Liberty Repository</name><url>http://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/wasdev/maven/repository/</url><layout>default</layout><snapshots>

<enabled>false</enabled></snapshots><releases>

<enabled>true</enabled></releases>

</pluginRepository>

About this task

You can use the provided Maven plug-in to install, start, stop, package, and createa Liberty profile server, and test your application on the Liberty profile. Each taskis represented by a specific goal in Maven.

Procedurev Install the Liberty profile server.v Start the Liberty profile server.v Create a Liberty profile server.v Stop the Liberty profile server.v Package a Liberty profile server.v Install applications on a Liberty profile server.v Remove application from a Liberty profile server.

Liberty profile: Maven goal - liberty:install-server:

If you install the Maven plug-in, you can use the liberty:install-server goal toinstall a Liberty profile server from a compressed archive or a directory that hasthe server installation files. Additionally, you can assemble a Liberty profile serverinto a Maven artifact.

Installing the server from an existing directory

Usage: This is the Maven goal that you can use to install a server from an existingdirectory.mvn liberty:install-server -DserverHome=/path/to/server_home -DserverName=[server_instance_name]

Example: installing the server from an existing directoryThis is the code snippet that you can use in the pom.xml file of yourproject.<plugin><groupId>com.ibm.websphere.wlp.maven.plugins</groupId><artifactId>liberty-maven-plugin</artifactId><version>1.0</version><configuration><serverHome>${project.build.directory}/wlp</serverHome><background>true</background><serverName>test</serverName> </configuration></plugin>

Installing the server as a Maven artifact

Usage: This is the command that you can use with the Maven plug-in for theLiberty profile to install a server as a Maven artifact.mvn liberty:install-server -DassemblyArtifact=[maven_artifact] -DserverName=[server_name]

Example: Installing the server as a Maven artifactThis is the code snippet that you can use in the pom.xml file of yourproject.


<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-install-plugin</artifactId><version>2.2</version><executions><execution><id>install-liberty-to-repo</id><phase>process-resources</phase><goals><goal>install-file</goal></goals><configuration><file>wlp***.zip</file><groupId>com.ibm.ws.liberty.test</groupId><artifactId>liberty-test-server</artifactId><version>1.0</version><packaging>zip</packaging></configuration></execution><!—install the liberty server as maven artifact<plugin><groupId>com.ibm.websphere.wlp.maven.plugins</groupId><artifactId>liberty-maven-plugin</artifactId><version>1.0</version><executions><execution><id>install-liberty-server</id><phase>compile</phase><goals><goal>install-server</goal></goals></execution></executions><configuration><assemblyArtifact><groupId>com.ibm.ws.liberty.test</groupId><artifactId>liberty-test-server</artifactId><version>1.0</version><type>zip</type></assemblyArtifact><serverName>test</serverName></configuration></plugin>

Installing a server from a compressed archive

Usage: This is the command that you can use with the Maven plug-in for theLiberty profile to install a server from a compressed archive.mvn liberty:install-server -DassemblyArchive=/path/to/assembly.zip

Example: Installing the server from a compressed archiveThis is the code snippet that you can use in the pom.xml file of yourproject.<plugin><groupId>com.ibm.websphere.wlp.maven.plugins</groupId><artifactId>liberty-maven-plugin</artifactId><version>1.0</version><configuration><assemblyArchive>/path/to/compressed_archive</assemblyArchive></configuration></plugin>

Liberty profile: Maven goal - liberty:start-server:

If you install the Maven plug-in, you can use the liberty:start-server goal tostart a Liberty profile server in the file system. If the server does not exist, this taskcan create a Liberty profile server automatically.

Usage: This is the Maven goal that you can use to start a server.mvn liberty:start-server -DserverHome=/path/to/server_home -DserverName=[server_name]

Example: starting a serverThis is the code snippet that you can use in the pom.xml file of yourproject.<plugin><groupId>com.ibm.websphere.wlp.maven.plugins</groupId><artifactId>liberty-maven-plugin</artifactId>

<version>1.0</version><executions><execution><id>start-server</id><phase>pre-integration-test</phase><goals><goal>start-server</goal></goals><configuration><serverHome>${project.build.directory}/wlp</serverHome><serverName>test</serverName></configuration></execution><executions></plugin>

Liberty profile: Maven goal - liberty:create-server:

If you install the Maven plug-in, you can use the liberty:create-server goal tocreate a Liberty profile server.

Usage: This is the Maven goal that you can use to create a server.mvn liberty:create-server -DserverHome=/path/to/server_home -DserverName=[server_name]

Example: creating a serverThis is the code snippet that you can use in the pom.xml file of yourproject.<plugin><groupId>com.ibm.websphere.wlp.maven.plugins</groupId><artifactId>liberty-maven-plugin</artifactId><version>1.0</version><executions><execution><id>create-liberty-server</id><phase>pre-integration-test</phase><goals><goal>create-server</goal></goals><configuration><serverHome>${project.build.directory}/wlp</serverHome><serverName>testcreate</serverName></configuration></execution></executions></plugin>

Liberty profile: Maven goal - liberty:package-server:

If you install the Maven plug-in, you can use the liberty:package-server goal topackage a Liberty profile server.

Usage: This is the Maven goal that you can use to package a server.mvn liberty:package-server -DserverHome=/path/to/server_home -DserverName=[server_name]-DpackageFile=/path/to/packaged_file

Example: packaging a serverThis is the code snippet that you can use in the pom.xml file of yourproject.<plugin><groupId>com.ibm.websphere.wlp.maven.plugins</groupId><artifactId>liberty-maven-plugin</artifactId><version>1.0</version><executions><execution><id>package-server</id><phase>post-integration-test</phase><goals><goal>package-server</goal></goals><configuration><serverHome>${project.build.directory}/was4d</serverHome><serverName>test</serverName><packageFile>/path/to/packaged_file</packageFile></configuration></execution></executions></plugin>


Liberty profile: Maven goal - liberty:stop-server:

If you install the Maven plug-in, you can use the liberty:stop-server goal to stopa Liberty profile server.

Usage: This is the Maven goal that you can use to stop a running server.mvn liberty:stop-server -DserverHome=/path/to/server_home -DserverName=[server_name]

Example: stopping a serverThis is the code snippet that you can use in the pom.xml file of yourproject.<plugin><groupId>com.ibm.websphere.wlp.maven.plugins</groupId><artifactId>liberty-maven-plugin</artifactId><version>1.0</version><executions><execution><id>stop-server</id><phase>post-integration-test</phase><goals><goal>stop-server</goal></goals><configuration><serverHome>${project.build.directory}/wlp</serverHome><serverName>test</serverName></configuration></execution></executions></plugin>

Liberty profile: Maven goal - liberty:deploy:

If you install the Maven plug-in, you can use the liberty:deploy goal to deployapplications on a Liberty profile server.

Usage: This is the Maven goal that you can use to deploy an application from theserver.mvn liberty:deploy -DserverHome=/path/to/server_home

-DserverName=[server_name] -DappArchive=/appname

Example: deploying an applicationThis is the code snippet that you can use in the pom.xml file of yourproject.<plugin><groupId>com.ibm.websphere.wlp.maven.plugins</groupId><artifactId>liberty-maven-plugin</artifactId><version>1.0</version><executions><execution><id>deployapp</id><phase>pre-integration-test</phase><goals><goal>deploy</goal></goals><configuration><appArchive>SimpleOSGiApp.eba</appArchive></configuration></execution></executions></plugin>

Liberty profile: Maven goal - liberty:undeploy:

If you install the Maven plug-in, you can use the liberty:undeploy goal to removean application from the Liberty profile server.

Usage: This is the Maven goal that you can use to remove an application from theserver.mvn liberty:undeploy -DserverHome=/path/to/server_home

-DserverName=[server_name] -DappArchive=/appname


Example: undeploying an applicationThis is the code snippet that you can use in the pom.xml file of yourproject.<plugin><groupId>com.ibm.websphere.wlp.maven.plugins</groupId><artifactId>liberty-maven-plugin</artifactId><version>1.0</version><executions><execution><id>undeploy</id><goals><goal>undeploy</goal></goals><configuration><appArchive>foo.ear</appArchive></configuration></execution></executions></plugin>

Using an OSGi consoleEclipse Equinox currently provides an OSGi console that you can use to aid withdebugging. This console is not available by default. When you work with theLiberty profile, you can enable this console by configuring a port for it.

About this task

The Liberty profile uses the Eclipse Equinox implementation of the OSGi corespecification. Equinox currently provides an OSGi console. To enable this console,you first allocate a specific port to it by setting the osgi.console property in thebootstrap.properties file. Then you can use Telnet to connect to the console onthat port, and explore the OSGi framework.

Procedure

v Add the osgiconsole-1.0 Liberty feature to your server.xml file.<feature>osgiconsole-1.0</feature>

v Allocate a specific port to the OSGi console.You set the OSGi console port by specifying the osgi.console property. You setthis property as a bootstrap property in the bootstrap.properties file. See“Specifying Liberty profile bootstrap properties” on page 95.osgi.console=5471

The OSGi console is disabled when the osgi.console property is not set.v Use Telnet to connect to the OSGi console port.

telnet localhost 5471

v Use the console to explore the framework.The available commands vary, depending on the OSGi framework being used.Command-line help provides enough information to get started.

Adding and removing Liberty featuresFeatures are the units of functionality by which you control the pieces of theruntime environment that are loaded into a particular server. To add or remove aLiberty feature, you add or remove an XML snippet in the <feature> subelementof the server.xml configuration file. When you add or remove Liberty features, thechanges are applied dynamically.



Before you begin

You can add and remove Liberty features as described in this topic, or as describedin “Editing the Liberty profile configuration by using developer tools” on page 344.

About this task

These are the XML snippets that enable the main features:v <feature>appSecurity-2.0</feature>

v <feature>beanvalidation-1.0</feature>

v <feature>blueprint-1.0</feature>

v <feature>cdi-1.0</feature>

v <feature>collectiveController-1.0</feature>

v <feature>collectiveMember-1.0</feature>

v <feature>ejblite-3.1</feature>

v <feature>jaxrs-1.1</feature>

v <feature>jaxws-2.2</feature>

v <feature>jaxb-2.2</feature>

v <feature>jdbc-4.0</feature>

v <feature>jmsComms-1.0</feature>

v <feature>jmsMessaging-1.1</feature>

v <feature>jmsSecurity-1.0</feature>

v <feature>jmsServer-1.0</feature>

v <feature>jndi-1.0</feature>

v <feature>jpa-2.0</feature>

v <feature>jsf-2.0</feature>

v <feature>jsp-2.2</feature>

v <feature>json-1.0</feature>

v <feature>localConnector-1.0</feature>

v <feature>mongo-2.0</feature>

v <feature>monitor-1.0</feature>

v <feature>osgi.jpa-1.0</feature>

v <feature>serverStatus-1.0</feature>

v <feature>servlet-3.0</feature>

v <feature>sessionDatabase-1.0</feature>

v <feature>ssl-1.0</feature>

v <feature>wab-1.0</feature>

v <feature>webProfile-6.0</feature>

v <feature>wssecurity-1.0</feature>

Including a feature in the configuration might cause one or more additional,required features to be loaded automatically. For example, if you include thewab-1.0 feature, then the servlet-3.0 and blueprint-1.0 features are loaded


automatically. For more information about these features, see “Liberty features” onpage 14.

Procedure

To add or remove Liberty features, complete the following steps:1. Open the server.xml configuration file for editing.

You can do this using a text editor. By default, the path and file name for theconfiguration root document file is usr/servers/server_name/server.xml.However, you can change the path. See “Customizing the Liberty profileenvironment” on page 352.

2. Add or remove features in the configuration file.The set of features is enclosed within the <featureManager> element, and eachfeature within the <feature> subelement. For example:<server>



The matching of feature names is not case-sensitive; the following example isalso a valid server configuration:<featureManager>

<feature>Servlet-3.0</feature><feature>localConnector-1.0</feature>

</featureManager>

3. Save the changes to the configuration file.

Results

Your changes are applied. If the server is running, the changes are applieddynamically.

Using include elements, variables, and Ref tags inconfiguration files

You can keep all your configuration settings in a single server.xml file, or you canuse include elements to consolidate configuration settings from separate files. Youcan use variables in the configuration to avoid hardcoding values that might notbe appropriate when the configuration is reused in different environments. You canuse Ref tags to refer to (and thereby reuse) existing code blocks that are definedelsewhere in the configuration.

Procedurev “Using include elements in configuration files”v “Using variables in configuration files” on page 372v “Using Ref tags in configuration files” on page 373

Using include elements in configuration filesYou can keep all your configuration in a single server.xml file, or you can useinclude elements to consolidate configurations from separate files to create thestructure that is most useful to you.


About this task

It can be easier to maintain a complex configuration by splitting it across a set offiles. For example:v You might want to include a file that contains variables that are specific to the

local host, so that your main configuration can be used on multiple hosts.v You might want to keep all of the configuration for a particular application in a

separate file that can be versioned with the application itself.

Example

This is the syntax for including a configuration file. You can set the optionalattribute as true if you want to skip the include file when it cannot be found :<include optional="true" location="pathname/filename"/>or<include optional="true" location="url"/>

The following list shows the possible locations; they are searched in the ordershown.1. in a location specified relative to the parent file2. in the shared configuration directory3. in a location specified as an absolute path4. on a web server

To ensure that your include configuration behaves predictably, you need to beaware of the following processing rules for included configuration files:v For singleton services such as logging, or application monitoring, entries are

processed in the order they appear in the file and later entries add to or overrideprevious ones. This is also true for configuration instances, for example anapplication or data source, where the configuration instances have the same ID.

v Include statements can be placed anywhere within the <server /> element.v Each included file must contain a <server /> element that matches the one in

the parent configuration file.v Included files can nest other included files.v Each included file is logically merged into the main configuration at the position

that the <include /> statement occurs in the parent file.

In the following example, the primary server configuration file server.xml includesthe contents of the blogDS.xml configuration file, which is located in the sharedconfiguration directory. The blogDS.xml file contains a data source definition. Thisdefinition has been put in a separate configuration file so that it can be included inseveral different server.xml files, and thereby used across multiple serverinstances.

Here is example code from the server.xml file:<server><featureManager><feature>servlet-3.0</feature><feature>jdbc-4.0</feature>

</featureManager><application id="blog" location="blog.war" name="blog" type="war"/><include optional="true" location="${shared.config.dir}/blogDS.xml"/>

</server>

Here is the example code from the blogDS.xml file:


<server><dataSource id="blogDS" jndiName="jdbc/blogDS" jdbcDriverRef="derbyEmbedded"><properties createDatabase="create" databaseName="C:/liberty/basics/derby/data/blogDB" />

</dataSource><jdbcDriver id="derbyEmbedded"/><library><fileset dir="C:/liberty/basics/derby" includes="derby.jar" />

</library></jdbcDriver>

</server>

Using variables in configuration filesYou can use variables in the configuration to avoid hard coding values that mightnot be appropriate when the configuration is reused in different environments.

About this task

Variables can be defined by setting a property in any of the following places:v in the server configuration file, or an included filev in the bootstrap.properties filev on the ws-launch.jar command script that is used to start the server

Best practice: Variables that are specific to a particular server, for example portnumbers, are usually specified in the bootstrap.properties file, allowing theserver.xml to be shared across multiple servers while keeping those valuesdifferent in each server. Variables that are shared across a group of servers, forexample database configuration for a particular host, is better specified in an xmlfile that is included into the parent configuration file.

Procedurev Specify a variable in a configuration file.

Variables defined in the configuration files are scoped to the configurationelements by which they are used. For example, the following code fragmentcreates a variable called updateTrigger_var to be used in applicationMonitorconfiguration elements:<applicationMonitor updateTrigger_var="mbean" />

To create a variable that is used in a particular configuration instance (such as anapplication or resource entry), you must also specify the instance identifier. Forexample:<httpEndpoint id="defaultHttpEndpoint" HTTP_default_var="8889" />

v Specify a variable in the bootstrap.properties file.Variables defined in the bootstrap.properties file are not scoped to particularconfiguration elements. You enter the variables as key-value pairs. For example:HTTP_default_var=8006

v Specify a variable on the ws-launch.jar command script.Variables defined on the Java command are not scoped to particularconfiguration elements. You enter the variables as Java system properties. Forexample:java -DHTTP_default_var=8008 -jar ws-launch.jar myServer

v Use a defined variable in the configuration.The variable substitution syntax is ${variable_name}. For example, to use theHTTP_default_var variable, add the following code fragment to the configurationfile:<httpEndpoint id="defaultHttpEndpoint"httpPort="${HTTP_default_var}"></httpEndpoint>


v Use variable element in the configurationYou can use the variable element to define a variable globally in the serverconfiguration. If the same variable is defined in an included file, it is overriddenby the one in the server.xml file . For example, to use the variable element,add the following code fragment to the configuration file:<variable name="HTTP_default_var" value="8889" />

v Override inheritable attributes in the configurationYou can override the default values of inheritable attributes in the configuration.The inheritable attributes are listed on the “Liberty profile: Configurationelements in the server.xml file” on page 97 page with an Inherits type. Forexample, the onError attribute is one of inheritable attributes. You can define avariable name for the onError attribute globally by either setting it in thebootstrap.properties or server.xml file with a variable element. If the samevariable name is specified in both files, the value in the server.xml file is used.If the attribute is not explicitly set in either of two files, it uses the default value.If an invalid value is set to the inheritable attribute, the attribute value falls backto the global value defined in bootstrap.properties or server.xml file or thedefault value if not defined at the global level.Another example is logging properties in the Liberty profile. See “Liberty profile:Trace and logging” on page 552.

Using Ref tags in configuration filesYou can define a common configuration element, then reuse that definition byreferring to it (using a Ref tag) from elsewhere in the configuration. Ref tags can beused in the same configuration file that contains the element definition, or in anincluded configuration file.

About this task

Different approaches are used to specify relationships between the requiredconfiguration elements. For example, the following data source definitions are allvalid. The first uses no Ref tags, the second uses a combination of direct elementdefinition and Ref tags, and the third uses Ref tags only.

Example

Example 1: Using no Ref tags.<dataSource id="blogDS" jndiName="jdbc/blogDS"><properties createDatabase="create" databaseName="C:/liberty/basics/derby/data/blogDB"/><jdbcDriver><library><fileset dir="C:/liberty/basics/derby" includes="derby.jar"/>

</library></jdbcDriver><connectionManager maxPoolSize="10"/>

</dataSource>

Example 2: Combining direct element definition and Ref tags.<dataSource id="blogDS" jndiName="jdbc/blogDS" connectionManagerRef="derbyPool"><properties createDatabase="create" databaseName="C:/liberty/basics/derby/data/blogDB"/><jdbcDriver libaryRef="derbyLib"/>

</dataSource>

<connectionManager id="derbyPool" maxPoolSize="10"/>

<library id="derbyLib"/><fileset dir="C:/liberty/basics/derby" includes="derby.jar"/>

</library>


Example 3: Using Ref tags only (except for the properties element, which is onlypermitted as nested).<dataSource id="blogDS" jndiName="jdbc/blogDS"

connectionManagerRef="derbyPool" jdbcDriverRef="derbyEmbedded"><properties createDatabase="create" databaseName="C:/liberty/basics/derby/data/blogDB"/>

</dataSource>

<connectionManager id="derbyPool" maxPoolSize="10"/>

<jdbcDriver id="derbyEmbedded" libraryRef="derbyLib"/>

<library id="derbyLib" filesetRef="derbyFileset"/>

<fileset id="derbyFileset" dir="C:/liberty/basics/derby" includes="derby.jar"/>

Controlling dynamic updatesThere are three types of dynamic update that can be controlled throughconfiguration: changing the server configuration; adding and removingapplications; updating installed applications. For all deployed applications, you canconfigure whether application monitoring is enabled and how often to check forupdates to applications. For the “dropins” directory, you can also configure thename and location of the directory and choose whether to deploy the applicationsthat are in the directory.

About this task

By default, deployed applications are monitored for updates, and the updates aredynamically applied to the running application. This applies both to applicationsthat are deployed through configuration entries, and those deployed from the“dropins” directory. You can change these default behaviors by setting the configand applicationMonitor elements in the server.xml configuration file. You can usea text editor to do this, or you can use the developer tools and selectConfiguration Admin Service or Application Monitor in the server configurationdesign view.

See also the descriptions of the config and applicationMonitor elements in“Liberty profile: Configuration elements in the server.xml file” on page 97.

The default settings for application monitoring are as follows:<applicationMonitor updateTrigger="polled" pollingRate="500ms"

dropins="dropins" dropinsEnabled="true"/>

Notes:

v The updateTrigger property has three possible values:

polled The runtime environment scans the server.xml file for changes using thetiming interval specified by the monitorInterval property.

mbeanThe runtime environment only looks for updates when prompted to doso through a call to an MBean. This is the mode that is used by thedeveloper tools to update the server.xml file, unless you override it.

disabledThe updates are not dynamically applied.

v When you specify the pollingRate property, you include the unit of time afterthe number:– ms (milliseconds)– s (seconds)


– m (minutes)– h (hours)

v The dropins property specifies the name of the directory used as the “dropins”directory.

v The dropinsEnabled property is a boolean property that determines whether theapplications in the “dropins” directory are deployed.

Procedurev Configure dynamic changes to the server configuration.

Changes to the server.xml file, or any files it includes, are detected by theruntime environment and applied to the active configuration. You can disablethis behavior by setting the config element in the server.xml file:<config updateTrigger="disabled"/>

v Configure dynamic addition and removal of applications.As described in Chapter 10, “Deploying applications to the Liberty profile,” onpage 517, applications can be dynamically added to and removed from theserver runtime environment through two mechanisms:– By adding or removing application entries in the server.xml file.

If you disable dynamic changes to the server configuration as described in theprevious step, then adding or removing application entries has no effect on arunning server. Your changes are only applied at the next server restart. Thechanges are picked up immediately, if you update application entries usingthe developer tools.

– By moving application files into and out of the “dropins” directory.This behavior can be controlled by setting the applicationMonitor element inthe server.xml file. For example, to disable dynamic installation ofapplications from the “dropins” location, create an entry as follows:<applicationMonitor dropinsEnabled="false"/>

v Configure dynamic updates to installed applications.By default, if you add, remove or modify any files within a deployedapplication, or you replace the whole application with an updated version, theprevious version is automatically stopped and the new version is started. Thisprocess applies for any deployed application, whether the application is in the“dropins” directory or at a location defined in the server.xml file. You cancontrol this behavior by setting the applicationMonitor element in theserver.xml file. For example, to disable dynamic update of all applications,create an entry as follows:<applicationMonitor updateTrigger="disabled"/>

v Configure the name and location of the “dropins” directory.By default, the “dropins” directory is ${server.config.dir}/dropins. You canchange this by setting the applicationMonitor element in the server.xml file.For the location, you can use any known variable, or a property in thebootstrapping.properties file, or an absolute path, or a path relative to theserver directory. For example, both the following settings point to the samelocation:<applicationMonitor dropins="${server.config.dir}/applications" /><applicationMonitor dropins="applications" />


Configuring class loaders and libraries for Java EEapplications

By default, each application can access a set of provided APIs and its own internalclasses and libraries. You can override the default settings, and configure classloading for each application.

About this task

Each Java EE application has its own class loader in a running Liberty profileserver. The Liberty profile assumes some default settings for all Java EEapplications, so that they can access the supported specification APIs (for examplethe servlet APIs if the servlet feature is enabled), and the IBM APIs. By default,each application can access these provided APIs and access its own internal classesand libraries. If you have to override the default settings and configure classloading for your application, complete one or more of the following tasks.

Note: If you use configuration to override the default settings, you cannot deploythe application by dropping it into the “dropins” directory.

Procedurev “Using a Java library with a Java EE application”v “Sharing a library across multiple Java EE applications” on page 377v “Accessing third-party APIs from a Java EE application” on page 379v “Removing access to third-party APIs for a Java EE application” on page 380v “Overriding a provided API with an alternative version” on page 380v “Providing global libraries for all Java EE applications” on page 378

Using a Java library with a Java EE applicationOne way of using Java libraries with an application is to include them in theapplication itself. This might not always be desirable or appropriate, especially ifthe application is already packaged and does not include the library.

About this task

In the following example, a library called Alexandria consists of two files:v alexandria-scrolls.jar andv commons-lang.jar

An application called Scholar, running on a server called Academy, needs access tothis library.

Procedure1. Create a mylib/Alexandria directory in the servers/Academy directory under

the ${WLP_USER_DIR} directory.For example: wlp/usr/servers/Academy/mylib/Alexandria.

2. Copy the alexandria-scrolls.jar and commons-lang.jar files into the newfolder.

3. Configure class loading for the application, so that the Alexandria library isloaded.In the server.xml file, or an included file, add the following code:<application id="scholar" name="Scholar" type="ear" location="scholar.ear"><classloader><privateLibrary>


<fileset dir="${server.config.dir}/mylib/Alexandria" includes="*.jar" scanInterval="5s" /></privateLibrary>

</classloader></application>

Note: The <privateLibrary> element can also take a filesetRef attribute witha comma-separated list of <fileset> element IDs.

Sharing a library across multiple Java EE applicationsLibraries can be shared across multiple Java EE applications. All the applicationscan use the same classes at run time, or each application can use its own separatecopy of those classes loaded from the same location.

About this task

In the following example, a library called Alexandria consists of two files:v alexandria-scrolls.jar andv commons-lang.jar

An application called Scholar and an application called Student are running on aserver called Academy, and both need access to this library.

Procedure1. Create a mylib/Alexandria directory in the servers/Academy directory under

the ${WLP_USER_DIR} directory.For example: wlp/usr/servers/Academy/mylib/Alexandria.

2. Copy the alexandria-scrolls.jar and commons-lang.jar files into the newfolder.

3. Configure class loading for the application, so that the Alexandria library isloaded.In the server.xml file, or an included file, define the library by adding thefollowing code:<library id="Alexandria"><fileset dir="${server.config.dir}/mylib/Alexandria" includes="*.jar" scanInterval="5s" />

</library>

Note: The <library> element can also take a filesetRef attribute with acomma-separated list of <fileset> element IDs.

4. Reference the library from the applications, so that both these applicationsshare a single copy of the library.In the server.xml file, or an included file, add the following code:<application id="scholar" name="Scholar" type="ear" location="scholar.ear"><classloader commonLibraryRef="Alexandria" />

</application>

<application id="student" name="Student" type="ear" location="student.ear"><classloader commonLibraryRef="Alexandria" />

</application>

Note: The <commonLibraryRef> element can take a comma-separated list oflibrary IDs.

5. Optional: Configure another application to have its own set of classes loadedfrom the same JAR files.For example, if another application called Spy needs its own copy of the classes,the same physical files on disk can be used. In the server.xml file, or anincluded file, add the following code:


<application id="spy" name="Spy" type="war" location="spy.war"><classloader privateLibraryRef="Alexandria" />

</application>

Note: The <privateLibraryRef> element can take a comma-separated list oflibrary IDs.

Creating an automatic shared library

Shared libraries can be created automatically, and are given an ID that is the sameas the directory name. When creating an automatic shared library, you provide areference to the directory name of the library.

About this task

Under the ${WLP_USER_DIR} directory, there are two locations in which you canplace automatic shared libraries:v ${shared.config.dir}/lib

v ${server.config.dir}/lib

Example

This example shows how you code an automatic shared library in the server.xmlfile:<application type="war" id="MyApplication" name="myApplication" location="myapp.war"><classloader privateLibraryRef="AutomaticSharedLibraryA" /></application>

You must also copy the JAR files and property files to the relevant directory. Forexample:<server_install_dir>\usr\servers\<server_name>\lib\AutomaticSharedLibraryA\

Providing global libraries for all Java EE applicationsYou can provide global libraries that can be used by any application. You do thisby putting the JAR files for those libraries in a global library directory, thenspecifying use of global libraries in the class loader configuration for eachapplication.

About this task

Under the user directory specified by using the environment variableWLP_USER_DIR, there are the following locations in which you can place globallibraries:v ${shared.config.dir}/lib/global

v ${server.config.dir}/lib/global

If there are files present in these locations at the time an application is started, andthat application does not have a <classloader> element configured, the applicationuses these libraries. If a class loader configuration is present, these libraries are notused unless the global library is explicitly referenced.


Attention: If you use global libraries, you are advised also to configure a<classloader> element for every application. The servlet specification requiresapplications to share the global library class loader in their class loader parentchain. This breaks the separation of class loaders for each application that isotherwise possible. So, applications are more likely to have long-lasting effects onclasses loaded in Liberty and on each other, and class space consistency issues aremore likely to arise between applications, especially as features are added andremoved from a running server. None of these considerations apply forapplications that specify a <classloader> element in their configuration, becausethey maintain this separation.

Example

In the following example, an application called Scholar is configured to use acommon library called Alexandria, and also to use the global library.

In the server.xml file, or an included file, enable the global library for anapplication by adding the following code:<application id="" name="Scholar" type="ear" location="scholar.ear"><classloader apiTypeVisibility="spec" commonLibraryRef="Alexandria, global" />

</application>

The settings for the global library can also be configured explicitly, as a libraryelement with the special ID global. For example:<library id="global"><fileset dir="/path/to/folder" includes="*.jar" />

</library>

Accessing third-party APIs from a Java EE applicationBy default, Java EE applications do not have access to the third-party APIsavailable in the Liberty profile. To enable this access, the application must beconfigured in the server.xml file, or an included file.

About this task

In the following example, an application called Scholar needs access to thethird-party APIs that are available in the Liberty profile.

The application also uses a common library called Alexandria. This library islocated in the ${server.config.dir}/mylib/Alexandria directory.

Avoid trouble: Third party APIs might not remain compatible after an upgrade.For more information, see “Liberty profile externals support” on page 11.

Procedure1. Configure class loading for the application, so that the application can access

the third-party APIs.In the server.xml file, or an included file, configure the API type visibility byadding the following code:<application id="scholar" name="Scholar" type="ear" location="scholar.ear"><classloader apiTypeVisibility="spec, ibm-api, third-party" commonLibraryRef="Alexandria" />

</application>

2. Optional: If the application uses any common libraries, set those libraries to usethe same API type visibility setting.In the server.xml file, or an included file, add the following code:


<library id="Alexandria" apiTypeVisibility="spec, ibm-api, third-party"><fileset dir="${server.config.dir}/mylib/Alexandria" includes="*.jar" scanInterval="5s" />

</library>

Removing access to third-party APIs for a Java EE applicationBy default, Java EE applications do not have access to the third-party APIsavailable in the Liberty profile. You can also remove access explicitly in theserver.xml file, or an included file.

About this task

In the following example, an application called Scholar has previously beenconfigured to access third-party APIs, as described in “Accessing third-party APIsfrom a Java EE application” on page 379. You want to remove this access, and tomake it explicit in the configuration that the application now uses the defaultaccess setting.

The application also uses a common library called Alexandria. This library is in the${server.config.dir}/mylib/Alexandria directory.

Procedure1. Configure class loading for the application, to show that the application can no

longer access the third-party APIs.In the server.xml file, or an included file, remove third-party from the set ofvalues included for the apiTypeVisibility attribute:<application id="scholar" name="Scholar" type="ear" location="scholar.ear"><classloader apiTypeVisibility="spec, ibm-api" commonLibraryRef="Alexandria" />

</application>

2. Optional: If the application uses any common libraries, set those libraries to usethe same API type visibility setting.In the server.xml file, or an included file, add the following code:<library id="Alexandria" apiTypeVisibility="spec, ibm-api"><fileset dir="${server.config.dir}/mylib/Alexandria" includes="*.jar" scanInterval="5s" />

</library>

Overriding a provided API with an alternative versionIf an application provides (or uses a library that provides) classes that are alsoavailable in the Liberty profile, by default the classes from the Liberty profile areused. To change this so that the application uses the alternative versions of theseclasses, the application must be configured in the server.xml file, or an includedfile.

About this task

If a web application includes classes that are also present in the server runtimeenvironment, you might want to control which copy of each of those classes isused by the application. For example, if different versions of the classes are presentin both the application and the server runtime environment, you must ensure thatthe version packaged in the application is used.

By default, classes from the Liberty profile runtime environment are used by allJava EE applications. You can override this behavior by using the class loaderconfiguration delegation attribute. This configuration is specific to a particularapplication, or to a shared library that can be selected for use by an application.


Example

In the following example, an application called Scholar needs to use classes that itprovides (or that are provided in a library that it uses), rather than using thecopies of the classes that are available in the Liberty profile.v When the classes are packaged within the application, override the default

parentFirst delegation behavior with a classloader element in the server.xmlconfiguration file or a file that it includes:<application id="" name="Scholar" type="ear" location="scholar.ear"><classloader delegation="parentLast" />

</application>

This tells the application class loader to look at the Liberty profile classes onlyafter looking in the application and its associated libraries for a class.

v When the classes are packaged in a shared library, add the delegation attributeto the classloader element that configures the use of the shared library asfollows:<application id="" name="Scholar" type="ear" location="scholar.ear"><classloader delegation="parentLast" commonLibraryRef="mySharedLib"/>

</application>

<library id="mySharedLib"><fileset dir="${server.config.dir}/myLib" includes="*.jar" />

</library>

You can also use the privateLibraryRef attribute for private libraries in anapplication. See “Sharing a library across multiple Java EE applications” on page377.

Configuring a web server plug-in for the Liberty profileYou can configure a web server plug-in so that, when the web server receives anHTTP request for dynamic resources, the request is forwarded to the Libertyprofile.

About this task

A web server plug-in is used to forward HTTP requests from a supported webserver to one or more application servers. The plug-in takes a request and checksthe request against configuration data in the plugin-cfg.xml file. The configurationdata maps the URI for the HTTP request to the host name of an application server.The web server plug-in then uses this information to forward the request to theapplication server.

Procedure1. Install a supported web server, such as the IBM HTTP server that is shipped

with IBM WebSphere Application Server. See Installing IBM HTTP server.2. Install the web server plug-ins and the WebSphere Customization Toolbox

(WCT).v To install the web server plug-in, see Installing and configuring web server

plug-ins.v To install the WCT, see Installing and using the WebSphere Customization

Toolbox.3. Configure the web server plug-in for your desired web server by using the

WCT.v When prompted in WCT, choose the “remote” scenario and specify the host

name that the Liberty profile is accessible on.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tins_webserver

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tins_webplugins

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tins_webplugins

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tins_wct

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tins_wct

v Do not copy or run the generated configureWebserver script because thisscript is not required with the Liberty profile.

4. Start the server that hosts your applications, and ensure that thelocalConnector-1.0 feature and other required features are included in theserver configuration.In the pluginConfiguration element of the server configuration file, you canspecify the webserverPort and webserverSecurePort attributes to forwardrequests from the web server. By default, the value of webserverPort is 80 andthe value of webserverSecurePort is 443. However, you might want to changethese settings. For example for Linux and similar platforms, if you are anon-root user, you must use port numbers greater than 1024.For all configurable attributes of the pluginConfiguration element, see “Libertyprofile: Configuration elements in the server.xml file” on page 97.Here is an example of a server.xml server configuration file:<server description="new server"><featureManager><feature>localConnector-1.0</feature><feature>jsp-2.2</feature>

</featureManager>

<keyStore id="defaultKeyStore" password="{xor}PGY6bW4wOyw+" />

<httpEndpoint id="defaultHttpEndpoint"host="*"httpPort="9080">

<tcpOptions soReuseAddr="true" /></httpEndpoint>

<pluginConfiguration webserverPort="80"webserverSecurePort="443"sslKeyringLocation="path/to/sslkeyring"sslStashfileLocation="path/to/stashfile"sslCertlabel="definedbyuser"/>

<application type="war" id="myapp" name="myapp" location="${server.config.dir}/apps/myapp.war" /><application type="war" id="snoop" name="snoop" location="${server.config.dir}/apps/snoop.war" /></server>

Note:

v If you configure the web server plug-in to use SSL, you must enable thessl-1.0 Liberty feature of the Liberty profile.

v If the web server is using the default ports, you don't have to include thepluginConfiguration element in the server.xml file.

v The keystore that is used by the web server plug-in must be a CMS keystore,which can be created by using the Key Management (IKEYMAN) utility. Youcannot use the JKS keystore that is created by the Liberty profile or fullprofile for the web server plug-in, though you have to exchange signercertificates between the web server plug-in keystore and the Liberty profilekeystore.

v To configure the location of the plug-in log file, add the following codesnippet to the server.xml file:<Log LogLevel="Error" Name="String\logs\String\http_plugin.log"/>

5. Generate the plugin-cfg.xml file for your Liberty profile server andapplications by calling theWebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean.a. Using the same Java SDK as the server, run the jconsole Java utility in a

command window.For example, run the following command:c:\java\bin\jconsole


The server process should be listed in the choices waiting for connection.b. Connect to your server then click the MBeans tab.c. Locate the com.ibm.ws.jmx.mbeans.generatePluginConfig MBean under the

WebSphere domain.d. Call the generateDefaultPluginConfig operation to generate the

plugin-cfg.xml file, or call the generatePluginConfig operation tocustomize installation root directory and server name before generating theplugin-cfg.xml file.

Here is an example of a plugin-cfg.xml file:<?xml version="1.0" encoding="UTF-8"?><Config ASDisableNagle="false" AcceptAllContent="false" AppServerPortPreference="HostHeader"

ChunkedResponse="false" FIPSEnable="false" IISDisableNagle="false"IISPluginPriority="High" IgnoreDNSFailures="false" RefreshInterval="60"ResponseChunkSize="64" SSLConsolidate="false" SSLPKCSDriver="REPLACE"SSLPKCSPassword="REPLACE" TrustedProxyEnable="false" VHostMatchingCompat="false">

<Log LogLevel="Error" Name=".\logs\defaultServer\http_plugin.log"/><Property Name="ESIEnable" Value="true"/><Property Name="ESIMaxCacheSize" Value="1024"/><Property Name="ESIInvalidationMonitor" Value="false"/><Property Name="ESIEnableToPassCookies" Value="false"/><Property Name="PluginInstallRoot" Value="."/><VirtualHostGroup Name="default_host">

<VirtualHost Name="*:80"/><VirtualHost Name="*:443"/><VirtualHost Name="*:9080"/>

</VirtualHostGroup><ServerCluster CloneSeparatorChange="false" GetDWLMTable="false" IgnoreAffinityRequests="true"

LoadBalance="Round Robin" Name="defaultServer_default_node_Cluster"PostBufferSize="64" PostSizeLimit="-1" RemoveSpecialHeaders="true"RetryInterval="60">

<Server CloneID="b564bdc7-2c27-4a4b-ad37-9213c66e60d1" ConnectTimeout="0"ExtendedHandshake="false" MaxConnections="-1" Name="default_node_defaultServer0"ServerIOTimeout="900" WaitForContinue="false">

<Transport Hostname="somehost.example.com" Port="9080" Protocol="http"/></Server>

<PrimaryServers><Server Name="default_node_defaultServer0"/></PrimaryServers>

</ServerCluster><UriGroup Name="default_host_defaultServer_default_node_Cluster_URIs">

<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/myapp/*"/><Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/snoop/*"/>

</UriGroup><Route ServerCluster="defaultServer_default_node_Cluster"

UriGroup="default_host_defaultServer_default_node_Cluster_URIs"VirtualHostGroup="default_host"/>

</Config>

The plugin-cfg.xml file is generated in the ${server.output.dir} directory.

Note:

v You can use the JConsole utility with the Liberty profile. However, anyissues with the utility itself must be reported to your Java SDK provider.

v The management interface for theWebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean iscom.ibm.websphere.webcontainer.GeneratePluginConfigMBean. You can usethe management interface to obtain a proxy object. See “Liberty profile:Examples of accessing MBean attributes and operations” on page 396. Formore information about the management interface, see the Java APIdocument for the Liberty profile. The Java API documentation for eachLiberty profile API is available in a separate JAR file under the/dev/ibm-api/javadoc directory of the server image.

6. Copy the plugin-cfg.xml file to the machine that hosts the web server.7. Find the location of your current plugin-cfg.xml by finding the value specified

for the WebSpherePluginConfig directive at the bottom of the configuration fileof the HTTP server. For example <IHS_ROOT>/conf/httpd.conf.


Typically, you have to enable the plug-in within the httpd.conf file of the webserver by using the LoadModule phrase, and specify the location ofplugin-cfg.xml file using the WebSpherePluginConfig phrase. For example:

v On Windows systems: Windows

LoadModule was_ap22_module "path/to/mod_was_ap22_http.dll"WebSpherePluginConfig "C:\Program Files\IBM\HTTPServer\conf\plugin-cfg.xml"

v On other distributed systems: Linux

LoadModule was_ap22_module "path/to/mod_was_ap22_http.so"WebSpherePluginConfig "/opt/IBM/HTTPServer/conf/plugin-cfg.xml"

8. Optional: If you want the web server plug-in to forward HTTP requests tomore than one Liberty profile server, repeat the previous steps for eachadditional server. Make sure that you consolidate all the plug-in configurationsinto one plugin-cfg.xml file.

Note:

v If an application programmatically modifies the session cookie configurationusing Servlet 3.0 APIs, then the application needs to be initialized beforegenerating the plugin-cfg.xml file. Otherwise, the AffinityCookie attributedefined for that application might be wrong. To avoid this problem, you canset deferServletLoad to false, start the server, generate the plug-in, and thenremove the deferServletLoad attribute.

v You can use a utility named pluginCfgMerge in the full profile to mergemultiple plugin-cfg.xml files. See Configuring simple load balancing acrossmultiple application server profiles.

v If you are using the job manager to merge multiple plugin-cfg.xml files. SeeGenerating a merged plug-in configuration for Liberty profile servers usingthe job manager.

Configuring session persistence for the Liberty profileWhen session data must be maintained across a server restart or an unexpectedserver failure, you can configure the Liberty profile to persist the session data to adatabase. This configuration allows multiple servers to share the same session data,and session data can be recovered in the event of a failover.

About this task

To configure one or more servers in the Liberty profile to persist session data to adatabase, complete the following steps.

Procedure1. Define a shared session management configuration that you can reuse among

all of your servers. You must complete the following steps, as a minimumrequirement:a. Enable the sessionDatabase-1.0 feature.b. Define a data source:

<dataSource id="SessionDS" ... />

c. Refer to the data source from the session database configuration.<httpSessionDatabase id="SessionDB" dataSourceRef="SessionDS" ... />

d. Refer to the persistent storage location from the session managementconfiguration.<httpSession storageRef="SessionDB" ... />

See “Liberty profile: Configuration elements in the server.xml file” on page 97for details about the httpSession and httpSessionDatabase elements.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twsv_configsimplelb

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twsv_configsimplelb

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tagt_jobmgr_liberty_plugin_merge

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tagt_jobmgr_liberty_plugin_merge

For example, you can create a file named ${shared.config.dir}/httpSessionPersistence.xml as follows:<server description="Demonstrates HTTP Session Persistence Configuration">

<featureManager><feature>sessionDatabase-1.0</feature><feature>servlet-3.0</feature>

</featureManager>

<httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="${httpPort}"><tcpOptions soReuseAddr="true"/>

</httpEndpoint>

<fileset id="DerbyFiles" includes="*.jar" dir="${shared.resource.dir}/derby/client"/><library id="DerbyLib" filesetRef="DerbyFiles"/><jdbcDriver id="DerbyDriver" libraryRef="DerbyLib"/><dataSource id="SessionDS" jdbcDriverRef="DerbyDriver" jndiName="jdbc/sessions">

<properties.derby.client user="user1" password="password1"databaseName="${shared.resource.dir}/databases/SessionDB"createDatabase="create"/>

</dataSource>

<httpSessionDatabase id="SessionDB" dataSourceRef="SessionDS"/><httpSession storageRef="SessionDB" cloneId="${cloneId}"/>

<application id="test" name="test" type="ear" location="${shared.app.dir}/test.ear"/>

</server>

Note: When multiple servers are configured to persist session data to the samedatabase, those servers must share the same session management configuration.Any other configuration is not supported. For example, it is not possible forone server to use a multi-row schema while another server uses a single-rowschema.

Best Practice: If session affinity is important to your application, explicitlydefine a unique clone ID for each server. In that way, you do not have todepend on the default clone ID generated by the server, and you can be certainthat the value of the clone ID never changes.

2. Include the shared session management configuration in each of your servers.For example, create two server.xml files for server instances named s1 and s2,as follows:v ${wlp.user.dir}/servers/s1/server.xml

v ${wlp.user.dir}/servers/s2/server.xml<server description="Example Server">

<include location="${shared.config.dir}/httpSessionPersistence.xml"/></server>

See “Using include elements in configuration files” on page 370.3. Specify unique variables in the bootstrap.properties file of each server.

v ${wlp.user.dir}/servers/s1/bootstrap.propertieshttpPort=9081cloneId=s1

v ${wlp.user.dir}/servers/s2/bootstrap.propertieshttpPort=9082cloneId=s2

4. Create a table for session persistence before you start the servers.v If you want to change the default row size, table name, or table space name,

see “Liberty profile: Configuration elements in the server.xml file” on page97 for details about the httpSessionDatabase element.

vDistributed operating systems No additional action is required if your server is

installed on one of the distributed operating systems. The serverautomatically creates the table.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tperswsk

v If your server is using DB2 for session persistence, you can increase thepage size to optimize performance for writing large amounts of data to thedatabase.

5. Optional: If required, integrate HTTP sessions and security in the Libertyprofile. By default, after a session is created and accessed within a protectedresource with security enabled, only the originating owner of that session canaccess it. Session security (security integration) is enabled by default.

6. Optional: If required, Install and configure the web server plug-in to routerequests to each of the servers you configured. The session affinity is onlymaintained if your plug-in configuration specifies clone IDs that match theclone IDs defined in the server configuration.

Connecting to the Liberty profile by using JMXThis topic describes how to access Java Management Extensions (JMX) connectorson the Liberty profile. You can also access the secured JMX connector remotely byusing SSL.

About this task

There are two JMX connectors supported on the Liberty profile, each connector isenabled through a different Liberty feature: localConnector-1.0 andrestConnector-1.0.v The local connector is enabled through the Liberty feature localConnector-1.0.

Access through the local connector is protected by the policy implemented bythe SDK in use. Currently the SDKs require that the client runs on the same hostas the Liberty profile, and under the same user ID.

v The REST connector is enabled through the Liberty feature restConnector-1.0.Remote access through the REST connector is protected by a single administratorrole. In addition, SSL is required to keep the communication confidential. TherestConnector-1.0 feature already includes the ssl-1.0 feature.

Note: An application deployed on the Liberty profile has unrestricted access to itsMBeanServer directory.

Procedurev Connect to the local JMX connectorv Connect to the REST connector

v Work with JMX MBeans

Configuring local JMX connection to the Liberty profileYou can access the local Java Management Extensions (JMX) connector on theLiberty profile. The local connector is enabled through the Liberty featurelocalConnector-1.0.

About this task

The local connector is enabled through the Liberty feature localConnector-1.0.Access through the local connector is protected by the policy implemented by theSDK in use. Currently the SDKs require that the client runs on the same host asthe Liberty profile, and under the same user ID.



http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tperdb2t

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tperdb2t

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=rpersecg

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tins_installation_plugins

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=rwsv_plugincfg

The following section describes how to configure and access the local connector onthe Liberty profile.

Procedure1. Enable the local connector by using the following code in the server.xml file.

<featureManager><feature>localConnector-1.0</feature>

</featureManager>

2. Access the local connector by using the JConsole tool or JMX client that isinstalled on the same host.v For the JConsole tool, select the local process ws-launch.jar defaultServer

from the connection panel then click Connect.

v For the JMX client, see “Working with JMXMBeans on the Liberty profile” on page 391.

Configuring secure JMX connection to the Liberty profileYou can access the secured Java Management Extensions (JMX) connectors on theLiberty profile by using SSL. The secured JMX connection is enabled by the Libertyprofile feature restConnector-1.0.

About this task

The REST connector is enabled through the Liberty feature restConnector-1.0.Remote access through the REST connector is protected by a single administratorrole. In addition, SSL is required to keep the communication confidential. TherestConnector-1.0 feature already includes the ssl-1.0 feature.


The following section describes how to configure and access the REST connectoron the Liberty profile.

Procedure1. Enable the REST connector using the following code in the server.xml file.

<featureManager><feature>restConnector-1.0</feature>

</featureManager>

2. Configure SSL certificates in the server.xml file.3. Configure a user or group to the administrator role in the server.xml file.

v Map to the administrator role for the Liberty profile4. Access the REST connector from a JMX client application or by using the

jConsole tool provided in the Java SDK. Use -J flags to pass the systemproperties as Java options and set the class path to include the connector classfiles. The connector class files are packed in the clients/restConnector.jarfile.v Use the following properties for SSL certificates:

-J-Djavax.net.ssl.trustStore=<location of your client trust store>-J-Djavax.net.ssl.trustStorePassword=<password for the trust store>-J-Djavax.net.ssl.trustStoreType=<type of trust store>

The following example shows the jConsole tool being used with SSLconfigurations:


jconsole -J-Djava.class.path=%JAVA_HOME%/lib/jconsole.jar;%JAVA_HOME%/lib/tools.jar;%WLP_HOME%/clients/restConnector.jar

-J-Djavax.net.ssl.trustStore=key.jks-J-Djavax.net.ssl.trustStorePassword=Liberty-J-Djavax.net.ssl.trustStoreType=jks

After the jConsole starts, select Remote Process, and enter the JMX serviceURL: service:jmx:rest://<host>:<port>/IBMJMXConnectorREST. The portnumber is the HTTPS port. You must also provide the user name andpassword.

Note:

You can specify some JMX REST connection options as system properties. See“Liberty profile: JMX REST connector settings” on page 390.

Mapping the administrator role for the Liberty profile:

You can use quickStartSecurity element or any supported user registries for theadministrator role mapping on the Liberty profile.

About this task

All the JMX methods and MBeans accessed through the REST connector arecurrently protected by a single role named "administrator". To get started quickly,use quickStartSecurity element to configure a single user with administrator roleand configure the default SSL configuration.

You can also use any supported user registry. You cannot use quickStartSecurityelement if you have already configured another user registry. In this case, you haveto map users or roles from the registry to the administrator role.

Procedure

v Use quickStartSecurity element for a single user mapping.Here is an example showing the minimal required configuration:


</featureManager><quickStartSecurity userName="bob" userPassword="bobpassword" /><keyStore id="defaultKeyStore" password="keystorePassword"/>

v Or use the basic registry for administrator role mapping.Here is an example of the basic registry that gives the user "bob" or the group"group1" administrator role:<basicRegistry>

<user name="bob" password="bobpassword"/><user name="joe" password="joepassword"/><group name="group1" ...></group>

</basicRegistry>

<administrator-role><user>bob</user><group>group1</group>

</administrator-role>

v Or use the LDAP registry for administrator role mapping .Here is an example of the LDAP registry that gives the user "bob" administratorrole.<ldapRegistry id="basic" host="" port="">

<tds.properties ... /></ldapRegistry>


<administrator-role><user>cn=bob,o=ibm,c=us</user>


Developing a JMX Java client for the Liberty profile:

This topic describes how to develop a Java Management Extensions (JMX) clientapplication that can access the secured REST connector of the Liberty profile.

About this task

Using a JMX remote client application, you can administer the Liberty profilethrough JMX programming.

Procedure

v Develop a sample JMX client as follows. The REST connector supports thestandard JMX API.import javax.management.remote.JMXServiceURL;import javax.management.MBeanServerConnection;import javax.management.remote.JMXConnector;import javax.management.remote.JMXConnectorFactory;import java.util.HashMap;

public class Test {

public static void main(String[] args) {System.setProperty("javax.net.ssl.trustStore", <truststore location>);System.setProperty("javax.net.ssl.trustStorePassword", <truststore password>);

//If the type of the trustStore is not jks, which is default,//set the type by using the following line.System.setProperty("javax.net.ssl.trustStoreType", <truststore type>);

try {HashMap<String, Object> environment = new HashMap<String, Object>();environment.put("jmx.remote.protocol.provider.pkgs", "com.ibm.ws.jmx.connector.client");environment.put(JMXConnector.CREDENTIALS, new String[] { "bob", "bobpassword" });

JMXServiceURL url = new JMXServiceURL("service:jmx:rest://<host>:<port>/IBMJMXConnectorREST");JMXConnector connector = JMXConnectorFactory.newJMXConnector(url, environment);connector.connect();MBeanServerConnection mbsc = connector.getMBeanServerConnection();

} catch(Throwable t) {...

}}

}

v Optional: Disable host name verification for SSL certificates. The certificatesinstalled with the Liberty profile might not contain the host name of where theserver is actually running. If you want to disable host name verification of SSLcertificates, you can set the system propertycom.ibm.ws.jmx.connector.client.disableURLHostnameVerification to true,which disables host name verification for all connections. To disable host nameverification on a per-connection basis, pass the property as a new environmentwhen creating the JMX connection:HashMap<String, Object> environment = new HashMap<String, Object>();environment.put("jmx.remote.protocol.provider.pkgs", "com.ibm.ws.jmx.connector.client");environment.put("com.ibm.ws.jmx.connector.client.disableURLHostnameVerification", Boolean.TRUE);environment.put(JMXConnector.CREDENTIALS, new String[] { "bob", "bobpassword" });...

v Optional: Configure JMX REST connector settings by using the environmentMap.


...HashMap<String, Object> environment = new HashMap<String, Object>();environment.put("com.ibm.ws.jmx.connector.client.rest.maxServerWaitTime", 0);environment.put("com.ibm.ws.jmx.connector.client.rest.notificationDeliveryInterval", 65000);...

Liberty profile: JMX REST connector settings:

When you connect to a Liberty profile by using JMX REST connectors, you canspecify settings in the form of constants that have associated key values.

These keys are constants in thecom.ibm.ws.jmx.connector.client.rest.ConnectorSettings interface, and each constantrequires an integer value to specify an amount of time in milliseconds except forthe DISABLE_HOSTNAME_VERIFICATION constant, which accepts the boolean valueonly.

Thecom.ibm.ws.jmx.connector.client.rest.ConnectorSettings interface is a managementinterface. For more information about the management interface, see the Java APIdocument for the Liberty profile. The Java API documentation for each Libertyprofile API is available in a separate JAR file under the /dev/ibm-api/javadocdirectory of the server image.

DISABLE_HOSTNAME_VERIFICATIONBoolean setting that disables hostname verification on the clientconnections when it is enabled. This can be useful for environments wherethe hostname used does not match the one specified in the servercertificate. The key for constant DISABLE_HOSTNAME_VERIFICATION is theStringcom.ibm.ws.jmx.connector.client.disableURLHostnameVerification.

MAX_SERVER_WAIT_TIMEAmount of time that the client waits for the server to become availablebefore the JMX connection fails and a new connection must be created. Thekey for constant MAX_SERVER_WAIT_TIME is the Stringcom.ibm.ws.jmx.connector.client.rest.maxServerWaitTime. If theconnection is restored, any previous notification listeners are registeredagain. To disable this behavior, set the value to zero.

NOTIFICATION_DELIVERY_INTERVALMaximum amount of time that the server waits for new notificationsbefore responding to a request for notifications from the client. The key forconstant NOTIFICATION_DELIVERY_INTERVAL is the Stringcom.ibm.ws.jmx.connector.client.rest.notificationDeliveryInterval. Alarger value results in better notification delivery times because less time isspent establishing new connections. Normally it is not necessary to adjustthis value.

NOTIFICATION_INBOX_EXPIRYAmount of time that the server waits before discarding notificationregistrations if the client has not checked for new notifications. The key forconstant NOTIFICATION_INBOX_EXPIRY is the Stringcom.ibm.ws.jmx.connector.client.rest.notificationInboxExpiry.Normally it is not necessary to adjust this value.

NOTIFICATION_READ_TIMEOUTThe value of timeout for notification fetching. Because the server mightwait up to the value of the NOTIFICATION_DELIVERY_INTERVAL constant


before responding, this value must be somewhat larger, though normally itis not necessary to adjust this value. The key for constantNOTIFICATION_READ_TIMEOUT is the Stringcom.ibm.ws.jmx.connector.client.rest.notificationReadTimeout.

READ_TIMEOUTThe value of timeout for all client communications with the server, exceptnotification fetching. Adjust this value if the client throws read timeoutexceptions because of a slow connection or client or server process. Thekey for constant READ_TIMEOUT is the Stringcom.ibm.ws.jmx.connector.client.rest.readTimeout.

SERVER_STATUS_POLLING_INTERVALAmount of time that the client waits between checks that the server isavailable again when the MAX_SERVER_WAIT_TIME value is non-zero.Normally it is not necessary to adjust this value. The key for constantSERVER_STATUS_POLLING_INTERVAL is the Stringcom.ibm.ws.jmx.connector.client.rest.serverStatusPollingInterval.

You can enable the JMX REST connector options using the system properties. Forexample, for the MAX_SERVER_WAIT_TIME constant, you can use one of the followingoptions:v In the command prompt, set the system property

-Dcom.ibm.ws.jmx.connector.client.rest.maxServerWaitTime=0

v In a JMX client program, add the settingenvironment.put("com.ibm.ws.jmx.connector.client.rest.maxServerWaitTime",0);

Working with JMX MBeans on the Liberty profile

You can access the attributes and call the operations of Java ManagementExtensions (JMX) management beans (MBeans) on the Liberty profile. In addition,you can register your own MBeans from an application running on the Libertyprofile.

About this task

The primary interfaces for interacting with MBeans on the Liberty profile are asfollows:v javax.management.MBeanServer, which is for application code running on the

Liberty profile.v javax.management.MBeanServerConnection, which is for external code running in

a separate Java virtual machine.

You can use an instance of either of these interfaces to access the attributes and callthe operations of MBeans.

Procedurev For application code running on the Liberty profile, you can use a

javax.management.MBeanServer instance by using the following code:import java.lang.management.ManagementFactory;import javax.management.MBeanServer;

...

MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();...


v For external code running in a separate Java virtual machine, you can use ajavax.management.MBeanServerConnection instance. See “Developing a JMX Javaclient for the Liberty profile” on page 389.

Liberty profile: List of provided MBeans:

Liberty profile provides a list of MBeans and corresponding management interfacesthat you can use to manipulate and monitor the server.

For each MBean or MXBean in the list:v The name is the javax.management.ObjectName value that uniquely identifies the

MBean or MXBean. When there are multiple instances of an MBean or MXBean,the ObjectName value can contain a wildcard (*), which is described in theComments entries in this topic.

v The Management interface entries specify the name of the Java interface thatcan be used to construct a proxy object for the MBean or MXBean as describedin “Liberty profile: Examples of accessing MBean attributes and operations” onpage 396. For more information about the management interface, see the JavaAPI document for the Liberty profile. The Java API documentation for eachLiberty profile API is available in a separate JAR file under the/dev/ibm-api/javadoc directory of the server image.

WebSphere:feature=collectiveController,type=ServerCommands,name=ServerCommands

v Management interface:com.ibm.websphere.management.command.ServerCommandMBean

v Comments: This MBean runs in the collective controller and can remotelyinvoke the Liberty server command on a target host. It has two operations,startServer and stopServer. The parameters are explained in the APIdocumentation.

WebSphere:feature=restConnector,type=FileService,name=FileService

v Management interface:com.ibm.websphere.management.filetransfer.mbean.FileServiceMXBean

v Comments: This MXBean allows you to perform various file-related operationson the host where Liberty resides.You can find its class and API documentation in the following locations:liberty_home/dev/ibm-api/com.ibm.websphere.appserver.api.restConnector_1.0.0.jarliberty_home/dev/ibm-api/javadoc/com.ibm.websphere.appserver.api.restConnector-javadoc.zip

The exposed operations include the ability to query certain metadata (lastmodified date, size, and so on) for a given file or directory and also to query allchild files (and corresponding metadata) for a given directory. Support forarchive creation and expansion is also provided, which can be useful tocompress Liberty log files or to extract an application before deploying it.This MXBean contains two attributes: the read list and the write list. Theyrepresent the lists of locations that users can read or write to when using theFileService or FileTransfer capabilities provided by Liberty. Through theMXBean, these attributes can only be read, but they can be configured orcustomized through the following elements in the server.xml file:


<fileTransfer><readLocation>${server.output.dir}/logs</readLocation><readLocation>${server.output.dir}/apps</readLocation><writeLocation>${server.output.dir}/dropins</writeLocation>

</fileTransfer>

If the readLocation element is not specified, the default is the combination of:${wlp.install.dir}, ${wlp.user.dir}, and ${server.output.dir}. If awriteLocation element is not specified, the default is the empty set.The restConnector-1.0 feature must be included in the server.xml file in orderfor this MXBean to be loaded and to honour its configuration elementsUsing Liberty-defined variables is allowed with all the server-side parametersthat take a string representing a file path. Such variables are defined on theliberty_home/README.TXT file.

WebSphere:feature=restConnector,type=FileTransfer,name=FileTransfer

v Management interface:com.ibm.websphere.management.filetransfer.mbean.FileTransferMBean

v Comments: This MBean allows you to perform various file-transfer operationson the host where Liberty resides.You can find its class and API documentation in the following locations:liberty_home/dev/ibm-api/com.ibm.websphere.appserver.api.restConnector_1.0.0.jarliberty_home/dev/ibm-api/javadoc/com.ibm.websphere.appserver.api.restConnector-javadoc.zip

This MBean is registered on the PlatformMBeanServer from the same JVM thatits corresponding Liberty process is running, but it can be accessed only byusing the IBM JMX REST Connector. The connection can be local or remote, butthe REST Connector must be used.The exposed operations include the ability to download, upload, and delete afile. Each read and write request on the server is bound to the configurable readand write lists that are accessed through the FileServiceMXBean. TheFileTransferMBean can also be fully accessed and operated from the built-in JavaJConsole, provided that the JConsole is connected through the IBM JMX RESTConnector.Using Liberty-defined variables is allowed with all the server-side parametersthat take a string representing a file path. Such variables are defined on theliberty_home/README.TXT file.

WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig

v Management interface:com.ibm.websphere.webcontainer.GeneratePluginConfigMBean

v Comments: See “Configuring a web server plug-in for the Liberty profile” onpage 381.

WebSphere:service=com.ibm.ws.kernel.filemonitor.FileNotificationMBean

v Management interface: com.ibm.websphere.filemonitor.FileNotificationMBean

WebSphere:service=com.ibm.websphere.application.ApplicationMBean,name=*

v Management interface: com.ibm.websphere.application.ApplicationMBeanv Comments: One instance is available for each application in the system, where *

is a unique application name.


WebSphere:type=JvmStats

v Management interface: com.ibm.websphere.monitor.jmx.JvmMXBeanv Comments: Available when the monitor-1.0 feature is enabled. See “Liberty

profile: JVM monitoring” on page 537.

WebSphere:type=ServletStats,name=*

v Management interface: com.ibm.websphere.webcontainer.ServletStatsMXBeanv Comments: When the monitor-1.0 feature is enabled, one instance is available

for each servlet that has been served, where * is of the form<AppName>.<ServletName>. See “Liberty profile: Web application monitoring” onpage 538.

WebSphere:type=ThreadPoolStats,name=Default Executor

v Management interface: com.ibm.websphere.monitor.jmx.ThreadPoolMXBeanv Comments: Available when the monitor-1.0 feature is enabled. See “Liberty

profile: ThreadPool monitoring” on page 539.

org.apache.cxf:type=WebServiceStats,service=*,port=*

v Management interface:org.apache.cxf.management.counters.ResponseTimeCounterMBean

v Comments: Available when the monitor-1.0 feature is enabled. TheWebServiceStats can be either Performance.Counter.Server orPerformance.Counter.client, where service=* is the qualified name of a serviceendpoint, port=* is the port name of the service endpoint. See “Liberty profile:JAX-WS monitoring” on page 540.

org.apache.cxf:type=Bus,instance.id=*,bus.id=*

v Management interface: org.apache.cxf.bus.ManagedBusv Comments: Available when the localConnector-1.0 or restConnector-1.0

feature is enabled and the JAX-WS application is accessed at least once. For eachweb module there are two bus instances: one is for server and another is forclient. The instance.id=* is the instance ID of the MBean, where * is the uniquesequence number that is created by JAX-WS engine. The bus.id=* is the name ofthe bus, where * is of the form <AppName>-<WorkScope>-Bus, where the<WorkScope> can be Server or Client.

org.apache.cxf:type=Bus.Service.Endpoint,bus.id=*,service=*,port=*,instance.id=*

v Management interface: org.apache.cxf.endpoint.ManagedEndpointv Comments: Available when the localConnector-1.0 or restConnector-1.0

feature is enabled and the JAX-WS application is accessed at least once. Theinstance.id=* is the instance ID of the MBean, where * is the unique sequencenumber created by JAX-WS engine. The bus.id=* is the name of the bus, where* is of the form <AppName>-Server-Bus. The service=* is the qualified name ofthe endpoint, where * is of form {<ServiceNamespace>}<ServiceName>. The port=*is the port name of the endpoint, where * is the current port name.


org.apache.cxf:type=WorkQueueManager,WorkQueueManager=Bus.WorkQueueManager,bus.id=*,instance.id=*

v Management interface:org.apache.cxf.bus.managers.WorkQueueImplMBeanWrapper

v Comments: Available when the localConnector-1.0 or restConnector-1.0feature is enabled and the JAX-WS application is accessed at least once. For eachweb module there are two bus instances: one is for server and another is forclient. The instance.id=* is the instance ID of the MBean, where * is the uniquesequence number created by JAX-WS engine. The bus.id=* is the name of thebus, where * is of the form <AppName>-<WorkScope>-Bus, where the <WorkScope>can be Server or Client.

WebSphere:feature=wasJMSServer,side=com.ibm.websphere.messaging.mbean.MessagingEngineMBean,name=*

v Management interface:com.ibm.websphere.messaging.mbean.MessagingEngineMBean

v Comments: Available when the wasJMSServer-1.0 feature is enabled. Onemessaging engine instance is available for each Liberty profile. The name=* is thename of the MBean, where * is the unique name of the messaging engineMBean. See “Liberty profile: Messaging” on page 48.

WebSphere:feature=wasJMSServer,side=com.ibm.websphere.messaging.mbean.QueueMBean,name=*

v Management interface: com.ibm.websphere.messaging.mbean.QueueMBeanv Comments: The MBean is available when the wasJMSServer-1.0 feature is

enabled and the MBean of the messaging engine is available. The name=* is thename of the MBean, where * is the name of the queue MBean. See “Libertyprofile: Messaging” on page 48.

WebSphere:feature=wasJMSServer,side=com.ibm.websphere.messaging.mbean.TopicMBean,name=*

v Management interface: com.ibm.websphere.messaging.mbean.TopicMBeanv Comments: The MBean is available when the wasJMSServer-1.0 feature is

enabled and the MBean of the messaging engine is available. The name=* is thename of the MBean, where * is the name of the topic MBean. See “Libertyprofile: Messaging” on page 48.

WebSphere:feature=wasJMSServer,side=com.ibm.websphere.messaging.mbean.SubscriberMBean,name=*

v Management interface: com.ibm.websphere.messaging.mbean.SubscriberMBeanv Comments: The MBean is available when the wasJMSServer-1.0 feature is

enabled and the MBean of the messaging engine is available. The name=* is thename of the MBean, where * is the name of the subscriber MBean.

Note: The WEMSubscriber MBean is a subscriber to the existing WEMTopic MBean.See “Liberty profile: Messaging” on page 48.


Liberty profile: Examples of accessing MBean attributes and operations:

This topic demonstrates some examples of accessing the attributes and calling theoperations of Java Management Extensions (JMX) management beans (MBeans) onthe Liberty profile.

After you obtain an MBeanServer instance (for an application running on theLiberty profile) or an MBeanServerConnection instance (for an external client), youcan access the attributes or call the operations of MBeans provided by the Libertyprofile. See “Working with JMX MBeans on the Liberty profile” on page 391.

The following code examples assume the variable mbs is an MBeanServer orMBeanServerConnection instance. You can use the provided methods to access theattributes and operations in a similar way to Java reflection. Alternatively, eachMBean has a management interface with getter methods for the attributes andmethods for the operations. You can use these interfaces via one of thejavax.managementJMX.newMBeanProxy methods or one of thejavax.management.JMX.newMXBeanProxy methods for MXBeans to obtain a proxyobject. The name of a management interface ends with “MXBean”. For the namesof the management interfaces, see “Liberty profile: List of provided MBeans” onpage 392.

Example 1: Check the state of application "myApp"import javax.management.ObjectName;import javax.management.JMX;import com.ibm.websphere.application.ApplicationMBean;...

ObjectName myAppMBean = new ObjectName("WebSphere:service=com.ibm.websphere.application.ApplicationMBean,name=myApp");if (mbs.isRegistered(myAppMBean)) {String state = (String) mbs.getAttribute(myAppMBean, "State");// alternatively, obtain a proxy objectApplicationMBean app = JMX.newMBeanProxy(mbs, myAppMBean, ApplicationMBean.class);state = app.getState();}

Example 2: Get response time statistics for servlet “Example Servlet” fromapplication “myApp”

import javax.management.ObjectName;import javax.management.openmbean.CompositeData;import javax.management.JMX;import com.ibm.websphere.webcontainer.ServletStatsMXBean;

...

ObjectName servletMBean = new ObjectName("WebSphere:type=ServletStats,name=myApp.Example Servlet");if (mbs.isRegistered(servletMBean)) {CompositeData responseTimeDetails = (CompositeData) mbs.getAttribute(servletMBean, "ResponseTimeDetails");CompositeData responseTimeReading = (CompositeData) responseTimeDetails.get("reading");Double mean = (Double) responseTimeReading.get("mean");Double standardDeviation = (Double) responseTimeReading.get("standardDeviation");// alternatively, obtain a proxy objectServletStatsMXBean servletStats = JMX.newMXBeanProxy(mbs, servletMBean, ServletStatsMXBean.class);StatisticsMeter meter = servletStats.getResponseTimeDetails();StatisticsReading reading = meter.getReading();mean = reading.getMean();standardDeviation = reading.getStandardDeviation();

}

Example 3: Create a web server plug-in configuration fileimport com.ibm.websphere.webcontainer.GeneratePluginConfigMBean;

...


ObjectName pluginMBean = new ObjectName("WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig");if (mbs.isRegistered(pluginMBean)) {mbs.invoke(pluginMBean, "generatePluginConfig", new Object[] {

"installRoot", "serverName"}, new String[] {String.class.getName(), String.class.getName()

});// alternatively, use a proxy objectGeneratePluginConfigMBean plugin = JMX.newMBeanProxy(mbs, name, GeneratePluginConfigMBean.class);plugin.generatePluginConfig("installRoot", "serverName");

}

Liberty profile: Examples of registering MBeans:

This topic describes how an application can register its own MBean instances onthe Liberty profile, so that the MBean instance can then be used by otherapplications or external administrators.

Any application can register an MBean by using an MBeanServer instance. Supposean application contains a class called org.example.Example that implements theinterface org.example.ExampleMBean, which defines some attributes and operations.As in the following example, the application might simply instantiate the Exampleclass then register it using a unique ObjectName. If the ObjectName chosen is alreadyin use, a javax.management.InstanceAlreadyExistsException is reported.import java.lang.management.ManagementFactory;import javax.management.MBeanServer;import javax.management.ObjectName;import org.example.Example;

...

MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();Object mbean = new Example();ObjectName name = new ObjectName("org.example.MyApplication:name=Example");mbs.registerMBean(mbean, name);

In addition, an application might register an MBean that extendsjava.lang.ClassLoader and provides access to any number of MBeanimplementation classes. Then you can use any other JMX client, local or remote, tocreate and register MBeans provided by the application. For example, suppose theapplication has an MBean class org.example.ApplicationClassLoader thatperforms the following tasks:v Implements any empty interface org.example.ApplicationClassLoaderMBean

v Extends java.lang.Classloader, andv Provides access to the org.example.Example MBean implementation class

The application can register an instance of ApplicationClassLoader to make theExample MBean available to other JMX clients as follows:import java.lang.management.ManagementFactory;import javax.management.MBeanServer;import javax.management.ObjectName;import org.example.ApplicationClassLoader;

...

MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();Object classLoader = new ApplicationClassLoader();ObjectName name = new ObjectName("org.example.MyApplication:name=ClassLoader");mbs.registerMBean(classLoader, name);

Any JMX client can create an Example instance. The following example assumes thevariable mbs is an MBeanServer or MBeanServerConnection instance. See “Workingwith JMX MBeans on the Liberty profile” on page 391.


import javax.management.ObjectName;

...

ObjectName loaderName = new ObjectName("org.example.MyApplication:name=ClassLoader");ObjectName exampleName = new ObjectName("org.example.MyApplication:name=Example");mbs.createMBean("org.example.Example”, exampleName, loaderName);

If necessary, you can use other forms of the MBeanServer.createMBean method tocreate the MBean by using non-default constructors.

For more information about the management interface, see the Java API documentfor the Liberty profile. The Java API documentation for each Liberty profile API isavailable in a separate JAR file under the /dev/ibm-api/javadoc directory of theserver image.

Establishing a JMX MBean Liberty server connection

You can use Jython-based scripts to establish a Java Management Extensions (JMX)MBean Liberty server connection.

Procedure1. Set up the environment.

The files that you need are located in liberty_home/clients/jython.a. Copy the restConnector.py file to jython_home/Lib.b. Copy the restConnector_sample.py file to jython_home to run the sample

code.c. Set the classpath for restConnector.jar in liberty_home/clients.

set CLASSPATH=%CLASSPATH%;c:\wlp\clients\restConnector.jar

2. Run the sample.The following example shows how to run the sample to get a MBean Libertyserver connection:c:\jython2.5.3>jython -i restConnector_sample.py>>> JMXRESTConnector.trustStore = "c:/key.jks">>> JMXRESTConnector.trustStorePassword = "Liberty">>> connector = JMXRESTConnector()>>> connector.connect("foo.bar.com",9443,"theUser","thePassword")Connecting to the Atlas server...Successfully connected to the server "foo.bar.com:9443">>> mconnection = connector.getMBeanServerConnection()>>> mconnection.invoke(...)>>> connector.disconnect()>>> exit()

JMXRESTConnector.trustStoreSets the path to where the SSL key file is stored

JMXRESTConnector.trustStorePasswordSets the password for the key

JMXRESTConnector.connect(host,port,user,password)Creates a connector to the Atlas server

JMXRESTConnector.getMBeanServerConnectionGets a connection to the MBean server

JMXRESTConnector.disconnect()Closes the connection


What to do next

After a connection to the MBean server is established, you can make calls to theMBean server by using the invoke(...) method.

Configuring HPEL in the Liberty Profile

You can configure the High Performance Extensible Logging (HPEL) log and traceframework. Use this information as a guide for configuring HPEL in your Libertyprofile.

About this task

HPEL provides faster log and trace handling capabilities and more flexible ways touse log and trace content than the default Liberty log and trace framework.

A server configuration consists of a bootstrap.properties file, a server.xml file,and any (optional) files that are included with those files. Thebootstrap.properties file specifies properties that need to be available before themain configuration is processed, and are kept to a minimum. The server.xml file isthe primary configuration file for the server.

The server.xml file and its associated files use a simple xml format that is suitablefor most text editors. A richer editing experience is provided by the eclipse serveradapter for liberty (WAS4D+ adapter), which uses a generated schema to providedrop-down lists of available choices, auto-completion, and other editing tools.

The bootstrap.properties file specifies whether the server should use HPEL as thelog and trace framework, or the default log and trace framework.

You can configure HPEL through the server configuration or thebootstrap.properties file.v Server configuration: To get logging from your own code, which is loaded after

server configuration processing, use the server configuration to configure HPEL.v bootstrap.properties file: You might need to set logging properties to take

effect before the server configuration files are processed. For example, if youneed to analyze problems that occur early in server start or configurationprocessing. In this case, you can configure HPEL in the bootstrap.propertiesfile.

You can set Logging properties in either the bootstrap.properties or theserver.xml file. Use attributes in the server.xml file, or use equivalent propertiesin the bootstrap.properties file. Any settings in the bootstrap.properties file areused from the time the server reads the bootstrap.properties file until the time theserver.xml file is processed. If the logging properties in the bootstrap.propertiesfile are not replaced or reset in the server.xml file, the property values in thebootstrap.properties file will continue to be used.

When HPEL is enabled, the maxFileSize, maxFiles, messageFileName,traceFileName, and traceFormat logging element attributes are ignored (sinceHPEL runs without trace.log and messages.log files). The traceSpecificationand consoleLogLevel attributes continue to be used to set the trace specificationand the level for the console log. The logDirectory attribute is ignored in cases


where the HPEL dataDirectory attribute is explicitly provided -- otherwise thelogDirectory controls the placement of HPEL files.

If you set logging or HPEL attributes in the server.xml file, you can avoid changesin configuration between startup time and runtime by setting the correspondingproperties in the bootstrap.properties file to the same value. Note that if no loggingor HPEL properties are set in the bootstrap.properties file, the server uses thedefault logging and HPEL settings.

Procedurev Enable HPEL for the server by updating the bootstrap.propertiesfile. In the

bootstrap.properties file, add the following text on a line by itself:websphere.log.provider=websphere-binaryLogging_1.0.1

v Configure the HPEL settings. Use the following parameters to configure HPEL.All subelements listed are subelements of the logging element in the server.xmlfile. The following table lists the HPEL attributes that are configurable in theserver.xml file and the equivalent properties that can be set in thebootstrap.properties file:

Table 14. HPEL attributes that are configurable in server.xml and the equivalent properties that can be set inbootstrap.properties

Loggingsubelement Attribute Equivalent bootstrap.properties property

binaryLog dataDirectory

purgeMaxSize

purgeMinTime

fileSwitchTime

bufferingEnabled

outOfSpaceAction

com.ibm.hpel.log.dataDirectory

com.ibm.hpel.log.purgeMaxSize

com.ibm.hpel.log.purgeMinTime

com.ibm.hpel.log.fileSwitchTime

com.ibm.hpel.log.bufferingEnabled

com.ibm.hpel.log.outOfSpaceAction

binaryTrace dataDirectory

memoryBufferSize

purgeMaxSize

purgeMinTime

fileSwitchTime

bufferingEnabled

outOfSpaceAction

com.ibm.hpel.trace.dataDirectory

com.ibm.hpel.trace.memoryBufferSize

com.ibm.hpel.trace.purgeMaxSize

com.ibm.hpel.trace.purgeMinTime

com.ibm.hpel.trace.fileSwitchTime

com.ibm.hpel.trace.bufferingEnabled

com.ibm.hpel.trace.outOfSpaceAction

textLog dataDirectory

outputFormat

traceIncluded

purgeMaxSize

purgeMinTime

fileSwitchTime

bufferingEnabled

outOfSpaceAction

com.ibm.hpel.text.dataDirectory

com.ibm.hpel.text.outputFormat

com.ibm.hpel.text.traceIncluded

com.ibm.hpel.text.purgeMaxSize

com.ibm.hpel.text.purgeMinTime

com.ibm.hpel.text.fileSwitchTime

com.ibm.hpel.text.bufferingEnabled

com.ibm.hpel.text.outOfSpaceAction


The following example shows a bootstrap.properties file configured to enableHPEL:websphere.log.provider=websphere-binaryLogging_1.0.1

The following example shows a server.xml file with the HPEL subelements. Thelog content is set to expire after 96 hours, the trace content is set to retain amaximum of 1024MB, and the text log is set for advanced format:<server description="new server">

<logging><binaryLog purgeMinTime="96"/><binaryTrace purgeMaxSize="1024"/><textLog outputFormat="Advanced"/>

</logging>

</server>

For the full logging configuration reference, see the logging, binaryLog,binaryTrace, and textLog elements in the “Liberty profile: Configurationelements in the server.xml file” on page 97.

Results

After you restart the server, the HPEL log and trace framework will be enabledand configured.

Setting up the server-management environment for the Libertyprofile

To set up the server-management environment for the Liberty profile, define theappropriate features in the server.xml file.

About this task

Server management for the Liberty profile includes the following two key features:v collectiveController-1.0v collectiveMember-1.0

These features can be combined in various servers to define a custom managementtopology.

The collectiveController-1.0 feature enables controller functionality for amanagement collective and includes a management repository MBean that isaccessible using the JMX/REST connector that is provided by therestConnector-1.0 feature. The collective controller acts as a storage andcollaboration mechanism to which collective members can connect.

The collectiveMember-1.0 feature enables a server to be a member of amanagement collective, allowing it to be managed by the collective controller.

Procedurev To enable a server to act as the management repository, define the

collectiveController-1.0 feature in the server.xml file.<featureManager>

<feature>collectiveController-1.0</feature></featureManager>


v The collectiveMember-1.0 feature enables a server that is not a managementrepository, but it enables the server to be managed by a management repository.To enable a server for management, define the collectiveMember-1.0 feature inthe server.xml file.<featureManager>

<feature>collectiveMember-1.0</feature></featureManager>

Tip: All collectiveController-1.0-enabled servers are also managed; therefore,you do not need to specify collectiveMember-1.0 if you already havecollectiveController-1.0 enabled.

Configuring a Liberty collective

You can organize Liberty servers into collectives to support clustering,administration, and other operations that act on multiple Liberty servers at a timein order to efficiently and accurately deliver application services to yourorganization.

About this task

A Liberty collective is a set of Liberty servers that are configured as part of thesame administrative and operational domain.

Configuration and state data about a Liberty collective is housed in an activeoperational repository.

Membership in a Liberty collective is optional. Liberty servers join a collective byregistering with a collective controller to become members. Members shareinformation about themselves through the operational repository of the controller.

The following rules apply:v A Liberty server can be a member of only one collective.v Different Liberty servers on the same host can be in different collectives.v Liberty servers on the same host that are members of a collective can coexist

with Liberty servers that are not members of a collective.

Procedure1. Create and configure your controller.

a. Create a controller.bin\server create myController

b. Create the collective configuration.bin\collective create myController --keystorePassword=yourPassword

c. Update the server.xml file.1) Copy output from the collective command and paste it into the

server.xml file.2) Add a user registry and an admin user (for the join operation).

For example:<server description="controller server">

<featureManager>

<feature>jsp-2.2</feature></featureManager>

<httpEndpoint id="defaultHttpEndpoint"host="localhost"httpPort="9080"httpsPort="9443" />

<featureManager><feature>collectiveController-1.0</feature>

</featureManager>

<quickStartSecurity userName="bob" userPassword="bobpwd" />

<ssl id="defaultSSLConfig"

keyStoreRef="defaultKeyStore"trustStoreRef="defaultTrustStore"clientAuthenticationSupported="true" />

<keyStore id="defaultKeyStore" password="yourPassword"

location="${server.config.dir}/resources/security/key.jks" />

<keyStore id="defaultTrustStore" password="yourPassword"

location="${server.config.dir}/resources/security/trust.jks" />

<keyStore id="serverIdentity" password="yourPassword"

location="${server.config.dir}/resources/collective/serverIdentity.jks" />

<keyStore id="collectiveTrust" password="yourPassword"

location="${server.config.dir}/resources/collective/collectiveTrust.jks" />

<keyStore id="collectiveRootKeys" password="yourPassword"

location="${server.config.dir}/resources/collective/rootKeys.jks" /></server>

d. Start the server.bin\server start myController

2. Create and configure a member.a. Create a member server.

bin\server create myMember

b. Join the member.bin\collective join myMember --host=localhost --port=9443 --user=adminUser --password=adminPassword --keystorePassword=yourPassword

c. Update the server.xml file.1) Copy output from the collective command and paste it into the

server.xml file.2) Modify the ports so that the server can open its HTTP ports.

For example:<server description="member server">

<featureManager>

<feature>jsp-2.2</feature></featureManager>

<httpEndpoint id="defaultHttpEndpoint"host="localhost"httpPort="9081"httpsPort="9444" />

<featureManager><feature>collectiveMember-1.0</feature>

</featureManager>

<collectiveMember controllerHost="localhost"

controllerPort="9443" />

<ssl id="defaultSSLConfig"


<keyStore id="defaultKeyStore" password="yourPassword"

location="${server.config.dir}/resources/security/key.jks" />

<keyStore id="defaultTrustStore" password="yourPassword"

location="${server.config.dir}/resources/security/trust.jks" />

<keyStore id="serverIdentity" password="yourPassword"

location="${server.config.dir}/resources/collective/serverIdentity.jks" />

<keyStore id="collectiveTrust" password="yourPassword"

location="${server.config.dir}/resources/collective/collectiveTrust.jks" /></server>

d. Start the member.bin\server start myMember

Results

You should see the member publish to the controller. The messages.log file shouldlook ike this example:

[1/31/13 11:17:47:699 CST] 0000002e nt.repository.member.internal.publisher.ServerPathsPublisher I CWWKX8114I:The server’s paths have been successfully published to the management repository.[1/31/13 11:17:47:711 CST] 0000002f nt.repository.member.internal.publisher.ServerStatePublisher I CWWKX8116I:The server STARTED state has been successfully published to the management repository.[1/31/13 11:17:47:737 CST] 00000028 pository.member.internal.publisher.ServerManagementPublisher I CWWKX8112I:The server’s host information has been successfully published to the management repository.

Liberty profile: Overriding server host information

The collectiveMember-1.0 feature enables a server to be managed by the collectivecontroller. Most server host information can be automatically detected. In certainscenarios, however, you must provide additional host information so that thecollective controller can establish a connection to the server.

To enable the host information override, add the following element to theserver.xml file:<hostAuthInfo rpcPort="ssh_port"

rpcUser="user_ID"rpcUserPassword="password"rpcUserHome="user_home"sudoUser="sudo_user"sudoPassword="sudo_user_password"sshPublicKeyPath="public_key_path"sshPrivateKeyPath="private_key_path"sshPrivateKeyPassword="private_key_password"/>

rpcUserThis parameter specifies the user ID that the collective controller will use toconnect to the server.

If this value is not specified, the default value isSystem.getProperty("user.name").

rpcUserPasswordThis parameter specifies the password for the specified user ID.

If this value is not specified, the server will either generate an SSH key pair oruse the SSH key pair for the connection that is specified using theprivateKeyPath and publicKeyPath parameters. If SSH is not installed on theserver (such as on a Windows or OS/400® operating system), the password isrequired.

rpcUserHomeThis parameter specifies the home directory of the user.

If this value is not specified, the default value isSystem.getProperty("user.home").

If userId is specified, you should specify userHome.

sudoUserIf this value is specified, it allows the collective controller to executecommands as another, or "sudo", user instead of as the user ID used for theconnection.

This parameter is applicable only to servers that have an SSH server installed.

This parameter has no default value.

sudoPasswordThis parameter specifies the password for the sudo user specified by thesudoUser parameter.

This parameter is applicable only to servers that have an SSH server installed.


rpcPortThe port for the RPC mechanism, which is SSH port 22 by default.

If your system uses a nonstandard port, set this value accordingly.

If this value is not specified, the default value is 22.

sshPrivateKeyPathThis parameter specifies the path and file name of a user-specified private keyfile.

If this value is not specified, the default is ${server.output.dir}/resources/security/ssh/id_rsa.

If the specified file (or default file) does not exist, a new private key file will begenerated.

sshPublicKeyPathThis parameter specifies the path and file name of a user-specified public keyfile.

If this value is not specified, the default is ${server.output.dir}/resources/security/ssh/id_rsa.pub.

If the specified file (or default file) does not exist, a new public key file will begenerated.

sshPrivateKeyPasswordThis parameter specifies the password for the private key.


Examples

Scenario 1: Server is on Windows operating system, no SSH is installed<hostInfo password="myPassword"/> -><hostAuthInfo rpcUserPassword="myPassword"/>

Scenario 2: Server has SSH installed, SSH is running on port 2222<hostInfo sshPort="2222"/> -><hostAuthInfo rpcPort="2222"/>

Scenario 3: Need to execute commands as another user


<hostInfo sudoUser="anotherUser" sudoPassword="anotherPassword"/>

Liberty profile: Starting and stopping a collective member

The collective controller provides a ServerCommands MBean that can be used tostart or stop a collective member.

Prerequisitesv The member server must have the collectiveMember-1.0 feature enabled in its

server.xml file.v The member must be added to a collective controller.

See “Configuring a Liberty collective” on page 402 for more information.

Set up

To enable the collective controller to stop and start a member server, add the<hostAuthInfo> element to the member's server.xml file.

For Windows members, you must provide an administrator user ID andpassword.<hostAuthInfo rpcHost="member_host_name"

rpcUser="admin_user_ID"rpcUserPassword="admin_password"/>

For Linux, AIX, HP-UX, or Solaris members, SSH public and private keys areused for authentication by default. A pair of RSA keys are generated on serverstartup under ${server.config.dir}/resources/security/ssh. The public key isadded to the user's authorized_keys file automatically. The private key is sent tothe controller.<hostAuthInfo rpcHost="member_host_name"/>

If you would like to use a username and password for authentication, specify themin the server.xml file.<hostAuthInfo rpcHost="member_host_name"

rpcUser="user_ID"rpcUserPassword="password"/>

For information on how to construct a Liberty collective, see “Configuring aLiberty collective” on page 402.

For information on running the ServerCommands MBean from the controller, see theAPI documentation for the ServerCommands MBean.

See “Liberty profile: Overriding server host information” on page 404 for moredetails.

Setting the default host name of a Liberty server

You can add the defaultHostName variable to the server.xml file to set the defaulthost name by which a Liberty server is identified.


About this task

This variable is available for use by service configurations. Setting this value isparticularly important for multihomed systems (with multiple NICs and multiplemapped host names for example).

Notes:

v This variable is currently used by the <httpEndpoint> host attribute and the<serverManagement> hostName attribute

v The default host name should be the fully qualified host name of the system.v The value should not contain any wildcards (* for example).v The variable default is localhost.

Procedure

To set the default host name by which a Liberty server is identified, add thedefaultHostName variable to the server.xml file.For example:<variable name="defaultHostName" value="localhost" />

Liberty profile: Collective repository data security

This article provides an overview of collective repository data security.

The current security policy for collective data is as follows:v The system reserves two node names, sys.host.auth.info and

sys.jmx.auth.info, under a host and server's repository namespace.v These nodes are not accessible through the MBean (to prevent disclosure of

system credentials). Accessing the data stored at these nodes will result in a nullresponse.

v A collective member is restricted to modifying only its own information in therepository. Authenticated administrative users have unrestricted access toinformation in the repository except as noted above.

Administering data access applications on the Liberty profileThe Liberty profile provides support to the data access applications using Libertyfeatures such as jdbc-4.0 and other features.

Procedurev Configure database connectivity on the Liberty profile.v Configure connection pooling for database connectionsv Configure database transaction recovery

Configuring database connectivity in the Liberty profileYou can configure a data source associated with different JDBC providers fordatabase connectivity. The JDBC providers supply the driver implementationclasses that are required for JDBC connectivity with your specific vendor database.

About this task

To access a database from your application, you must use a data source. Datasources are provided by JDBC drivers and come in the following varieties:


v javax.sql.DataSource

This is the basic form of a data source. It does not provide interoperability thatenhances connection pooling, and cannot participate as a two-phase capableresource in transactions involving multiple resources.

v javax.sql.ConnectionPoolDataSource

This type of data source is enabled for connection pooling. It cannot participateas a two-phase capable resource in transactions involving multiple resources.

v javax.sql.XADataSource

This type of data source is both enabled for connection pooling and is able toparticipate as a two-phase capable resource in transactions involving multipleresources.

In order to be usable in the Liberty profile, your JDBC driver must provide at leastone of these types of data sources. For the commonly used JDBC drivers, theLiberty profile is already aware of the implementation class names for the variousdata source types. You only need to tell the Liberty profile where to find the JDBCdriver.

Procedure1. In the server.xml file, define a shared library pointing to the location of your

JDBC driver JAR or compressed files. For example:<library id="DB2JCC4Lib">

<fileset dir="C:/DB2/java" includes="db2jcc4.jar db2jcc_license_cisuz.jar"/></library>

2. Define a data source using the JDBC driver. If you don't specify the type ofdata source, the Liberty profile chooses in the following order depending onwhich is available.v javax.sql.ConnectionPoolDataSource

v javax.sql.DataSource

v javax.sql.XADataSource

Here is an example that accepts the default for data source type:<dataSource id="db2" jndiName="jdbc/db2">

<jdbcDriver libraryRef="DB2JCC4Lib"/><properties.db2.jcc databaseName="SAMPLEDB" serverName="localhost" portNumber="50000"/>

</dataSource>

Here is an example that uses javax.sql.XADataSource type:<dataSource id="db2xa" jndiName="jdbc/db2xa" type="javax.sql.XADataSource">


</dataSource>

3. Optional: Configure attributes for the data source, such as JDBC vendorproperties and connection pooling properties.For example:<dataSource id="db2" jndiName="jdbc/db2" connectionSharing="MatchCurrentState"

isolationLevel="TRANSACTION_READ_COMMITTED" statementCacheSize="20"><connectionManager maxPoolSize="20" minPoolSize="5"

connectionTimeout="10s" agedTimeout="30m"/><jdbcDriver libraryRef="DB2JCC4Lib"/><properties.db2.jcc databaseName="SAMPLEDB" serverName="localhost" portNumber="50000"

currentLockTimeout="30s" user="user1" password="pwd1"/></dataSource>

For a full list of configuration attributes for the dataSource element,connectionManager element and some commonly used JDBC vendors, see“Liberty profile: Configuration elements in the server.xml file” on page 97.

4. Optional: Configure data sources for commonly used databases according tothe following examples.


For DB2<dataSource id="db2" jndiName="jdbc/db2">


</dataSource>

<library id="DB2JCC4Lib"><fileset dir="C:/DB2/java" includes="db2jcc4.jar db2jcc_license_cisuz.jar"/>

</library>

For DB2 on iSeries® (Native)<dataSource id="db2iNative" jndiName="jdbc/db2iNative">

<jdbcDriver libraryRef="DB2iNativeLib"/><properties.db2.i.native databaseName="*LOCAL"/>

</dataSource>

<library id="DB2iNativeLib"><fileset dir="/QIBM/Proddata/java400/jdk6/lib/ext" includes="db2_classes16.jar"/>

</library>

For DB2 on iSeries (Toolbox)<dataSource id="db2iToolbox" jndiName="jdbc/db2iToolbox">

<jdbcDriver libraryRef="DB2iToolboxLib"/><properties.db2.i.toolbox databaseName="SAMPLEDB" serverName="localhost"/>

</dataSource>

<library id="DB2iToolboxLib"><fileset dir="/QIBM/ProdData/Http/Public/jt400/lib" includes="jt400.jar"/>

</library>

For Derby Embedded<dataSource id="derbyEmbedded" jndiName="jdbc/derbyEmbedded">

<jdbcDriver libraryRef="DerbyLib"/><properties.derby.embedded databaseName="C:/databases/SAMPLEDB" createDatabase="create"/>

</dataSource>

<library id="DerbyLib"><fileset dir="C:/db-derby-10.8.1.2-bin/lib"/>

</library>

For Derby Network Client<dataSource id="derbyClient" jndiName="jdbc/derbyClient">

<jdbcDriver libraryRef="DerbyLib"/><properties.derby.client databaseName="C:/databases/SAMPLEDB" createDatabase="create"

serverName="localhost" portNumber="1527"/></dataSource>

<library id="DerbyLib"><fileset dir="C:/db-derby-10.8.1.2-bin/lib"/>

</library>

For Informix JCC<dataSource id="informixjcc" jndiName="jdbc/informixjcc">

<jdbcDriver libraryRef="DB2JCC4Lib"/><properties.informix.jcc databaseName="SAMPLEDB" serverName="localhost" portNumber="1526"/>

</dataSource>

<library id="DB2JCC4Lib"><fileset dir="C:/Drivers/jcc/4.8" includes="db2jcc4.jar db2jcc_license_cisuz.jar"/>

</library>

For Informix JDBC<dataSource id="informix" jndiName="jdbc/informix">

<jdbcDriver libraryRef="InformixLib"/><properties.informix databaseName="SAMPLEDB" ifxIFXHOST="localhost"

serverName="ol_machinename" portNumber="1526"/></dataSource>

<library id="InformixLib"><fileset dir="C:/Drivers/informix" includes="ifxjdbc.jar ifxjdbcx.jar"/>

</library>

For Microsoft SQL Server (Microsoft JDBC driver)<dataSource id="mssqlserver" jndiName="jdbc/mssqlserver">

<jdbcDriver libraryRef="MSJDBCLib"/><properties.microsoft.sqlserver databaseName="SAMPLEDB"


<library id="MSJDBCLib"><fileset dir="C:/sqljdbc_4.0/enu" includes="sqljdbc4.jar"/>

</library>

For Microsoft SQL Server (DataDirect Connect for JDBC driver)<dataSource id="ddsqlserver" jndiName="jdbc/ddsqlserver">

<jdbcDriver libraryRef="DataDirectLib"/><properties.datadirect.sqlserver databaseName="SAMPLEDB"



<library id="DataDirectLib"><fileset dir="C:/DataDirect/Connect-4.2/lib" includes="sqlserver.jar"/>

</library>

For MySQL<dataSource id="mySQL" jndiName="jdbc/mySQL">

<jdbcDriver libraryRef="MySQLLib"/><properties databaseName="SAMPLEDB" serverName="localhost" portNumber="3306"/>

</dataSource>

<library id="MySQLLib"><fileset dir="C:/mysql-connector-java-x.x.xx"

includes="mysql-connector-java-x.x.xx.jar"/></library>

For Oracle<dataSource id="oracle" jndiName="jdbc/oracle">

<jdbcDriver libraryRef="OracleLib"/><properties.oracle URL="jdbc:oracle:thin:@//localhost:1521/SAMPLEDB"/>

</dataSource>

<library id="OracleLib"><fileset dir="C:/Oracle/lib" includes="ojdbc6.jar"/>

</library>

For Sybase<dataSource id="sybase" jndiName="jdbc/sybase">

<jdbcDriver libraryRef="SybaseLib"/><properties.sybase databaseName="SAMPLEDB" serverName="localhost" portNumber="5000"/>

</dataSource>

<library id="SybaseLib"><fileset dir="C:/Drivers/sybase" includes="jconn4.jar"/>

</library>

For solidDB®

<dataSource id="solidDB" jndiName="jdbc/solidDB"><jdbcDriver libraryRef="solidLib"/><properties databaseName="SAMPLEDB" URL="jdbc:solid://localhost:2315/"/>

</dataSource>

<library id="solidLib"><fileset dir="C:/Drivers/solidDB" includes="SolidDriver2.0.jar"/>

</library>

For a JDBC driver that is not known to the Liberty profile<dataSource id="sample" jndiName="jdbc/sample" type="javax.sql.XADataSource">

<jdbcDriver libraryRef="SampleJDBCLib"javax.sql.XADataSource="com.ibm.sample.SampleXADataSource"/>

<properties databaseName="SAMPLEDB" hostName="localhost" port="12345"/></dataSource>

<library id=SampleJDBCLib"><fileset dir="C:/Drivers/SampleJDBC/" includes="sampleDriver.jar"/>

</library>

In the example, the JDBC driver is located at C:/Drivers/SampleJDBC/sampleDriver.jar and provides an implementation ofjavax.sql.XADataSource named com.ibm.sample.SampleXADataSource.The JDBC driver also provides vendor-specific data source propertiessuch as databaseName, hostName and port.

Liberty profile: How data source configuration updates are applied:

If you change the attributes of the dataSource element while a server is running,the updates to different attributes are applied at different times and in differentways.

You configure a data source by specifying the attributes of the dataSource elementin the server.xml configuration file. If you change these attributes for a runningserver, the updates are applied at different times and in different ways, dependingon which attribute is changed. The following table describes, for each attribute ofthe dataSource element, how a configuration change is applied at run time.


Table 15. How data source configuration updates are applied at run time. The first column of the table lists theattributes of the dataSource element. The second column describes, for each attribute, how the configuration updateis applied at run time.

Attribute name How the configuration update is applied

beginTranForResultSetScrollingAPIs The update is effective immediately.

beginTranForVendorAPIs The update is effective immediately.

commitOrRollbackOnCleanup The update is effective immediately.

connectionManagerRef All connections and the connection pool are destroyed. The datasource is then managed by the new connection manager.

connectionSharing The update is applied with each first connection handle in atransaction.

isolationLevel The update is applied with new connection requests; currentconnections retain their isolation level.

jdbcDriverRef All connections and the connection pool are destroyed. The newJDBC driver is then used.

jndiName All connections and the connection pool are destroyed. The newJNDI name is then used.

propertiesRef If the data source is Derby Embedded, all connections and theconnection pool are destroyed before new properties go intoeffect. For other JDBC drivers, the new properties go into effectwith new connection requests.

queryTimeout The update is effective immediately.

recoveryAuthDataRef Authentication data for transaction recovery. All connectionsand the connection pool are destroyed. The new recoveryauthentication data is then used.

statementCacheSize The statement cache is resized upon next use.

supplementalJDBCTrace All connections and the connection pool are destroyed. The newsetting is then used.

syncQueryTimeoutWithTransactionTimeout The update is effective immediately.

transactional The update is applied to new connections and existingconnections not in use from the connection pool.

type All connections and the connection pool are destroyed. The newsetting is then used.

Liberty profile: Application-defined data sources:

You can define a data source within your application, through annotations or inthe deployment descriptor, as defined by the Java EE specification.

This capability is limited to names in java:comp. Other namespacessuch as java:module, java:app, and java:global are not available.

When defining a data source in an application, the JDBC driver must be madeavailable to the application. This is accomplished by configuring a shared library inthe server.xml for your application.

For example:<application id="myApp" name="myApp" location="myApp.war" type="war">

<classloader commonLibraryRef="DB2Lib"/></application>

<library id="DB2Lib"><fileset dir="C:/DB2/java" includes="db2jcc4.jar db2jcc_license_cisuz.jar"/>

</library>


Then, you can define a data source in your application either through annotationsor in the deployment descriptor.v Use annotations as in the following example:

@DataSourceDefinition(name = "java:comp/env/jdbc/db2",className = "com.ibm.db2.jcc.DB2DataSource",databaseName = "SAMPLEDB",serverName = "localhost",portNumber = 50000,properties = { "driverType=4" },user = "user1",password = "pwd1")

public class MyServlet extends HttpServlet {

@Resource(lookup="java:comp/env/jdbc/db2")DataSource ds;

v Use the deployment descriptor as in the following example, for example, in aweb.xml file:<data-source>

<name>java:comp/env/jdbc/db2</name><class-name>com.ibm.db2.jcc.DB2DataSource</class-name><server-name>localhost</server-name><port-number>50000</port-number><database-name>SAMPLEDB</database-name><user>user1</user><password>pwd1</password><property><name>driverType</name><value>4</value></property>

</data-source>

In general, properties that can be defined on dataSource or connectionManager inthe server.xml files can also be specified on application defined data sources.However, you cannot specify properties that refer to other elements, such asconnectionManagerRef and jdbcDriverRef, because the application defined datasource implicitly defines the connection manager and JDBC driver. When usingapplication defined data sources for two-phase commit, you can specify therecoveryAuthDataRef property to select the authentication data that is used fortransaction recovery. However, it is important to be aware that recovery oftransactions is only possible while the application is running. You can usevariables, encoded passwords, and duration syntax in application defined datasources.

Note: The duration syntax does not apply to properties that are explicitly definedin the annotation, such as loginTimeout or maxIdleTime.

Here is an example of two data sources using connection manager properties,variables, encoded passwords, and duration syntax.@DataSourceDefinitions(value = {

@DataSourceDefinition(name = "java:comp/env/jdbc/derby",className = "org.apache.derby.jdbc.EmbeddedDataSource40",databaseName = "${shared.resource.dir}/data/SAMPLEDB",minPoolSize = 1,maxPoolSize = 10,maxIdleTime = 180,properties = { "agedTimeout=10m", "connectionTimeout=30s", "createDatabase=create" }),

@DataSourceDefinition(name = "java:comp/env/jdbc/oracle",className = "oracle.jdbc.pool.OracleDataSource",url = "jdbc:oracle:thin:@//localhost:1521/SAMPLEDB",user = "user1",password = "{xor}Oz0vKDtt")

})

Configuring connection pooling for database connections:


You can configure connection pooling for your data source by defining aconnection manager for it.

Example

The following example code uses the connectionManager element in the server.xmlfile to define a connection pool for a data source:<dataSource id="ds1" jndiName="jdbc/example" jdbcDriverRef="DB2" ><connectionManager maxPoolSize="10" minPoolSize="2" numConnectionsPerThreadLocal="1" />

</dataSource>

The server uses default values for any connection management settings that are notdefined on the connection manager element. If a connection manager is notdefined at all for a data source, the server uses default values for all of the settings.

Using thread local storage for connections can increase performance forapplications on multi-threaded systems. See Chapter 12, “Tuning the Libertyprofile,” on page 543.

You can define multiple data sources and associate each with a different connectionmanager. However, you cannot associate multiple data sources with a singleconnection manager.

For more information about the connectionManager element, see “Liberty profile:Configuration elements in the server.xml file” on page 97.

Liberty profile: How connection pooling configuration updates are applied:

If you change the attributes of the connectionManager element while a server isrunning, the updates to different attributes are applied at different times and indifferent ways.

You configure a connection pool by specifying the attributes of theconnectionManager element in the server.xml configuration file. If you changethese attributes for a running server, the updates are applied at different times andin different ways, depending on which attribute is changed. The following tabledescribes, for each attribute of the connectionManager element, how a configurationchange is applied at run time.

Table 16. How connection manager configuration updates are applied at run time. The first column of the table liststhe attributes of the connectionManager element. The second column describes, for each attribute, how theconfiguration update is applied at run time.

Attribute name How the configuration update is applied

agedTimeout The update is effective immediately.

connectionTimeout The update is effective immediately.

maxIdleTime The update is effective immediately.

maxNumberOfMCsAllowableInThread The update is effective immediately.

maxPoolSize The update is effective immediately.

minPoolSize The update is effective immediately.

numConnectionsPerThreadLocal The update is effective immediately.

reapTime The update is effective immediately.

purgePolicy The update is effective immediately.


Note: The attributes agedTimeout and maxIdleTime are updated immediately.However, they are not used fully unless the value of reapTime attribute is greaterthan zero.

Because updates to the connection manager are effective immediately, errors mightoccur if you make changes with active connections; including the potential risksfor the connections to be ended prematurely.

Liberty profile: How database transactions are recovered:

Support for transactions is provided by the transaction service. Recovery can occureither when the transaction service is first used, or at server startup. Whenrecovering any in-doubt database transactions, the Liberty profile transactionmanager uses either the unique identifier or the JNDI name to locate the currentdataSource element.

By default, transaction recovery after a server failure happens when the transactionservice is first used (at first lookup of a UserTransaction), rather than at serverstartup. This behavior can be altered by using a pair of configuration attributes forthe transaction service. These attributes control when recovery happens, andwhether the system waits for recovery to finish before allowing transactional workto proceed. You set these attributes in the server.xml file. For example, thefollowing settings specify that recovery should occur at server startup, and that theserver should wait for recovery to finish before allowing transactional work toproceed:

<transactionrecoverOnStartup="true"waitForRecovery="true"

/>

You configure a data source by specifying the attributes of the dataSource elementin the server.xml configuration file. You also assign a unique identifier or ajndiName attribute for the data source as follows:<dataSource id="ds1" jndiName="jdbc/ds1"... />

You must not change the value of the id or jndiName attribute when a recovery ispending for a transaction in which the data source participated. If you makechanges to any other attributes of the dataSource element, those changes arehonored for the recovery. This enables you to, for example, add arecoveryAuthDataRef attribute that specifies a database user ID and password touse for recovery.

The database user ID and password to use for recovery are determined accordingto the following precedence:1. If the dataSource element has the recoveryAuthDataRef attribute defined, then

the user ID and password from the authData element are used. For example:<authData id="recoveryAuth" user="dbuser1" password="{xor}Oz0vKDtu"/><dataSource id="ds1" jndiName="jdbc/ds1" jdbcDriverRef="DB2"

recoveryAuthDataRef="recoveryAuth" .../>

2. Otherwise, if container managed authentication is used, then the user ID andpassword from the container managed authentication alias are used. Forexample:v In the ibm-web-bnd.xml file, you have the following code:

<resource-ref name="jdbc/ds1ref" binding-name="jdbc/ds1"><authentication-alias name="user1Auth"/>

</resource-ref>

v In the server.xml file, you have to define the following code:


<authData id="user1Auth" user="dbuser1" password="{xor}Oz0vKDtu"/><dataSource id="ds1" jndiName="jdbc/ds1" jdbcDriverRef="DB2" .../>

3. Otherwise, the user ID and password from the dataSource element are used.For example:<dataSource id="ds1" jndiName="jdbc/ds1" jdbcDriverRef="DB2" ...>

<properties.db2.jcc databaseName="testdb" user="dbuser1" password="{xor}Oz0vKDtu"/></dataSource>

4. If none of the above are specified, and the recovery is attempted without anyuser ID and password, then the behavior is determined by the JDBC driver anddatabase.

Note: If the transaction recovery is performed by an application-defined datasource, such as an @DataSourceDefinition annotation or a <data-source> elementin the deployment descriptor, you have to make sure the application is running forthe data source when the recovery is happening. Configurations in the server.xmlfile cannot be used to recover application-defined data sources.

Creating Liberty applications that use MongoDB

Applications that use MongoDB can run on the Liberty profile. For access to aMongoDB instance, the applications use the MongoDB Java driver and datasources that you configure for the server.

Before you begin

Note: The Liberty profile provides configuration support forMongoDB. MongoDB (from “humongous”) is a scalable, high-performance, opensource NoSQL database.

You must use Version 2.10.0 or later of the MongoDB Java driver.

About this task

To enable an application to use MongoDB, you configure a shared library for theMongoDB Java driver and a library reference to the shared library in theserver.xml file of the Liberty profile. An application can access MongoDB directlyfrom the application or through the mongo feature and mongoDB instanceconfigurations in the server.xml file.

Procedure1. Install the MongoDB Java driver in a location that your application and the

Liberty runtime can access.For example, place the MongoDB driver .jar file in the Liberty_profile_root/usr/servers/server_name/lib directory.

2. Configure a shared library for the MongoDB driver .jar file in the server.xmlfile of the Liberty profile server.<library id="MongoLib">

<file name="${server.config.dir}/lib/mongo.jar" /></library>

Alternatively, drop the MongoDB Java driver into an automatic library.3. Enable your application to access MongoDB, either by direct access from the

application or by using the mongo-2.0 feature.v Enable direct access to MongoDB from the application.


a. Configure a library reference for the shared library in an applicationelement in the server.xml file.<application ...>

<classloader commonLibraryRef="MongoLib"/></application>

b. Enable your application to access the MondoDB classes directly.v Use the mongo-2.0 feature and mongoDB instances in the server.xml file.

If you use the mongo-2.0 feature, you must enable the application to use JavaNaming and Directory Interface (JNDI) lookup or use resource injection toaccess MongoDB.a. Add the mongo-2.0 feature to the server.xml file. If you are using JNDI

lookup, also add the jndi-1.0 feature.<featureManager>

<feature>mongo-2.0</feature><feature>jndi-1.0</feature>

</featureManager>

b. Configure a library reference for the shared library in the server.xml file.The library reference creates a connection to MongoDB. The followingexample shows a simple library reference:<mongo id="mongo" libraryRef="MongoLib" />

The following example shows a more complex library reference thatconfigures a JNDI name and a reference to the mongo-2.0 feature:<mongoDB jndiName="mongo/testdb" mongoRef="mongo" databaseName="db-test" />

Configuring a JNDI name enables an application or the Liberty runtimeto look up the MongoDB instance.

c. Enable your application to access MongoDB.The following example shows both JNDI lookup and resource injection:public class TestServlet extends HttpServlet {

@Resource(name = "mongo/testdb")protected DB db;...

protected void doGet(HttpServletRequest request,HttpServletResponse response) throws ServletException, IOException {

// Alternativly use InitialContext lookupDB lookup = (DB) new InitialContext().lookup("java:comp/env/mongo/testdb");

...

d. If you are using JNDI lookup, add a resource environment reference tothe web.xml file of your application:<resource-env-ref>

<resource-env-ref-name>mongo/testdb</resource-env-ref-name><resource-env-ref-type>com.mongodb.DB</resource-env-ref-type>

</resource-env-ref>

What to do next

Test use of the MongoDB from your application.

Optionally, review additional configuration properties for the MongoDBconfiguration element.

Configuring secure MongoDB connections in the Liberty profile:

You can configure application-managed or container-managed security forMongoDB connections in the Liberty profile.

Before you begin

Enable your application to use MongoDB. See Creating Liberty applications thatuse MongoDB.


About this task

You can secure MongoDB applications by using application-managed security orcontainer-managed security. For both types of security, the MongoDB server mustbe running with authentication explicitly enabled to secure MongoDB connections.

Procedure

v Configure application-managed security for MongoDB.If the mongo configuration element does not specify user and passwordattributes, the product assumes that an application is either usingapplication-managed security or is not using security. To enableapplication-managed security, the application must authenticate using theMongoDB APIs; for example:<mongo id="mongo1" libraryRef="MongoLib" /><mongoDB jndiName="mongo/testdb" mongoRef="mongo1" databaseName="db-test-1"/>

{ ...// Java snippet@Resource(name = "mongo/testdb")protected DB db;

private void auth() {if (!db.isAuthenticated())db.authenticate("user", "password".toCharArray());

}

v Configure container-managed security for MongoDB.To use container-managed security, the mongo configuration element must specifya user and password. Only one user is allowed for each mongo configuration. AllMongoDB instances use the specified user and password. For example, allMongoDB instances that reference mongo1 in the following example usemongoUserName and pw:<mongo id="mongo1" libraryRef="MongoLib" user=”mongoUserName” password=”pw”/><mongoDB jndiName="mongo/testdb" mongoRef="mongo1" databaseName="db-test-1"/><mongoDB jndiName="mongo/testdb2" mongoRef="mongo1" databaseName="db-test-2"/>

Applications that use container-managed security must not callcom.mongodb.DB.authenticate(user, pass).

What to do next

Ensure that the MongoDB server is running, and then test the MongoDB securityfrom your application.

Connecting to a distributed set of MongoDB instances:

Accessing data that is stored in a distributed set of MongoDB instances is nearlythe same procedure as connecting to a single MongoDB instance.

Before you begin

Enable your application to use MongoDB. See Creating Liberty applications thatuse MongoDB.

About this task

When you configure the mongo feature in your server.xml file, you can pass acollection of hostNames and ports that are either replica set members or shardedmongos servers.

If the host:port combinations are replica set members, the client finds all membersand uses the master by default. If the combinations are sharded mongos servers,


the client sends all requests to the closest member with the lowest ping time. If theclosest member is down, the client automatically fails over to the next server.

Procedure

Configure the hostNames and ports in your server.xml file.<mongo id="mongo1" libraryRef="MongoLib" hostNames="localhost,localhost,localhost" ports="9991,9992,9993"/>

Results

You configured a sharded MongoDB configuration.

Administering web applications on the Liberty profileThe Liberty profile provides support to the web applications using Liberty featuressuch as servlet-3.0, jsp-2.2, and other features.

Procedure

Specify when servlets are loaded and initialized.

Specifying when servlets are loaded and initializedBy default, the Liberty profile defers servlet loading until a request is received forthe associated web application. You can override this default behavior byspecifying the web container deferServletLoad attribute to false.

About this task

The servlet specification defines the load-on-startup servlet attribute, which isspecified in the web.xml file of a web application. If a servlet has a non-negativevalue for the load-on-startup attribute, the servlet must be loaded and initializedwhen the web application is deployed. The Liberty profile optimizes server starttime and memory use by not starting a servlet until a request is received for theweb application. You can override this deferral so that your servlets are loaded andinitialized when the web application is installed, rather that waiting for the firstrequest for the application.

Example

To configure the server to load servlets when a web application is installed, addthe following line to the server.xml configuration file or a file that it includes:<webContainer deferServletLoad="false"/>

This setting applies to all web applications installed in the server.


Chapter 8. Extending the Liberty profile

You can expand the capability of the Liberty profile by using product extensions.You can write your own Liberty features and install them onto an existing Libertyprofile server, or you can package them for delivery to your users.

About this task

This section describes how to develop features for a product extension, how toinstall features to the built-in “usr” product extension, and how to use yourfeatures in an application server. The Liberty profile provides various SystemProgramming Interfaces (SPIs) that you can use to extend the runtimeenvironment; you can also use more advanced features such as operating theLiberty profile server from your Java applications programmatically. The Java APIdocumentation for each Liberty profile SPI is available in a separate JAR file in the/dev/spi/ibm/javadoc directory of the server image.

For an overview of writing product extensions for the Liberty profile, see “Libertyprofile: Product extension” on page 22.

For full details of how to extend the Liberty profile, see the following subtopics:

Developing a Liberty feature for the Liberty profile

A Liberty feature consists of a feature manifest file, and one or more OSGi bundles.The OSGi bundles contain classes and services that provide a particular capabilitywhen the feature is installed onto a Liberty profile server.

About this task

You can develop a Liberty feature in either of the following ways:v Develop the feature manually; see “Developing a Liberty feature manually.”v Use the WebSphere Application Server Developer Tools; see “Creating a Liberty

feature by using developer tools” on page 425.

For full details on developing Liberty features, see the following subtopics:

Developing a Liberty feature manually

You can create a Liberty feature manually and install it to the Liberty profile.

About this task

A feature can consist of a single OSGi bundle and a feature manifest file. Thisexample makes a library available to applications so that the external packages are


visible on the default application class path. By copying the feature manifest intothe ${wlp.user.dir}/extension/lib/features directory, and the OSGi bundle intothe ${wlp.user.dir}/extension/lib directory, the feature can be installed to theLiberty profile. Then you can use the feature in your server.xml file.

For details about the format of a feature manifest file, see “Liberty feature manifestfiles” on page 421.

This example describes how to construct a Liberty feature manually. Alternatively,you can use the WebSphere Application Server Developer Tools; see “Creating aLiberty feature by using developer tools” on page 425.

Procedure

To create a Liberty feature manually, complete the following steps:1. Create an OSGi bundle containing your Java classes, and a feature manifest file

with appropriate OSGi headers, for example to export the Java packages thatyou want to expose to applications. Bundle-SymbolicName is the only requiredheader; this entry specifies a unique identifier for a bundle, based on thereverse domain name convention. It is good practice to specify a version for thebundle, and in this example some Java packages are exported for applicationuse:Bundle-SymbolicName: com.usr.samplebundleBundle-Version: 1.0.1Export-Package: com.usr.samplebundle.pkg1; version="1.0.0",

com.usr.samplebundle.pkg2; version="1.0.1"

2. Use the jar command to package the Java classes and the feature manifest file.For example:jar cfm samplebundle.jar MANIFEST.Mf *.class

3. Create a feature manifest file named feature-name.mf which describes thefeature to the runtime environment.a. In the IBM-API-Package header, list the packages that are to be exposed on

the default class loader for applications.b. Optional: When you create your Liberty feature, you install it into the user

product extension, and the packages in your feature can be accessed by anyother feature that is installed to the user product extension. To make one ormore SPI packages available to features in other product extensions, list thepackages in the IBM-SPI-Package header.

Subsystem-ManifestVersion: 1.0Subsystem-SymbolicName: sample-1.0; visibility:=publicSubsystem-Version: 1.0.0.qualifierSubsystem-Type: osgi.subsystem.featureSubsystem-Content: samplebundle; version="[1,1.0.100)"IBM-Feature-Version: 2IBM-API-Package: com.usr.samplebundle.pkg1; version="1.0.0"; type="api",

com.usr.samplebundle.pkg2; version="1.0.1"; type="api"IBM-SPI-Package: com.sample.myservice.spi; version="1.0.0"

4. Copy the bundle into the ${wlp.user.dir}/extension/lib directory, and thefeature manifest into the ${wlp.user.dir}/extension/lib/features directory.

Results

After your feature is installed to the Liberty profile, you can add the feature nameto the list of configured feature in your server.xml file. For example:<featureManager>

<feature>usr:sample-1.0</feature></featureManager>


Liberty feature manifest files

A Liberty feature is a feature manifest file and a collection of one or more OSGibundles that provide classes and services corresponding to a particular capabilityin the Liberty profile runtime environment. You can find the introduction of theformat of a feature manifest and the meaning of each header in the manifest file.

The feature manifest file in the Liberty profile uses the Subsystem Service metadataformat in the OSGi Enterprise R5 specification. A feature is defined by a featuremanifest file (.mf file) that is stored in the lib/features directory, and must use acustom type of Subsystem: osgi.subsystem.feature.

The following headers are defined:

Table 17. Headers of a feature manifest file.

This table shows the headers of a feature manifest file in the Liberty profile. The firstcolumn shows a list of headers, the second column shows the description of each header.

Header Description Required?

Subsystem-ManifestVersion The version format for thefeature manifest file. Must be setto 1.

Yes

Subsystem-SymbolicName The symbolic name of thefeature and any attributes ordirectives.

Yes

Subsystem-Version The version of the feature. Seethe OSGi core specificationsection 3.2.5 for the details ofhow this is defined.

Yes

Subsystem-Type The subsystem type for thefeature. All features are currentlyof the same subsystem type:osgi.subsystem.feature.

Yes

Subsystem-Content The subsystem content of thefeature. This is a commaseparated list of bundles andsubsystems that are required torun this feature. If you want toallow the auto feature to beconfigured in the server.xmlfile, you must have thecapability header containing therequired features, and also havethem defined in the subsystemcontent.

Yes

IBM-Feature-Version The version of this subsystemtype. Must be set to 2.

Yes

IBM-Provision-Capability The capability header thatdescribes whether a feature canbe provisioned automatically.

No

IBM-API-Package The API packages that areexposed to applications by thisfeature, features in other productextensions, and the Libertykernel.

No

IBM-API-Service The OSGi services that areexposed to OSGi applications bythis feature.

No

Chapter 8. Extending the Liberty profile 421

Table 17. Headers of a feature manifest file (continued).

This table shows the headers of a feature manifest file in the Liberty profile. The firstcolumn shows a list of headers, the second column shows the description of each header.

Header Description Required?

IBM-SPI-Package The SPI packages that areexposed by this feature tofeatures in other productextensions, and the Libertykernel.

No

Subsystem-SymbolicName

The syntax for this header matches the Bundle-SymbolicName syntax for a bundle. Ithas a symbolic name that follows the package names style syntax, and canoptionally take a set of attributes and directives.

The following attributes are supported:v superseded. This attribute indicates whether this feature is superseded by one or

more features or items of functionality. It takes one of the following values:– true - The feature is superseded.– false - The feature is not superseded.

This attribute is optional; the default value is false.For more information, see “Superseded feature” on page 14.

v superseded-by. This attribute specifies a comma-separated list of the featuresthat supersede this feature, if any, and is optional.

The following directive is supported:v visibility. This directive takes one of the following values:

– public - Feature considered to be API. The feature is supported by thedeveloper tools, for use in the server.xml file, and output in messages.

– protected - Feature considered to be SPI. The feature is not supported by thedeveloper tools, for use in the server.xml file, or output in messages. Thefeature is provided so extenders can make use of it to build higher levelfeatures.

– private - (default) The feature is product internals. The feature is notsupported for use in the server.xml file or to be referenced by extenderfeatures. The feature can be changed at any time, including between fix packs.

For example:Subsystem-SymbolicName: blueprint-1.0;

visibility:=public; superseded=true; superseded-by="appSecurity-2.0"

Best practise: If the developer tools must show the feature, it must be public. Ifthe feature is available only to trusted parties, it must be protected. If the featureis internal and subject to change at any time, it must be private.

Subsystem-Content

This header follows the same header syntax as the Subsystem specification. It usesthe following syntax:


Subsystem-Content ::= content ( ’,’ content )*content ::= unique-name ( ’;’ parameter )*unique-name ::= unique-name ( ’;’ unique-name )* (see OSGi core spec section 1.3.2)

The unique-name uses the form of the Bundle-SymbolicName orSubsystem-SymbolicName headers. The following attributes are supported:v version - The range of versions to be matched when finding a bundle. Only

bundles in this range are selected. A typical example of the version range is[1,1.0.100).

v type - The type of content to be provisioned. You can specify any value toindicate the content type. The following values are predefined:– osgi.bundle - This is the default value and indicates an OSGi bundle.– osgi.subsystem.feature - This value indicates that the feature should be

provisioned.

The following attributes are supported:v location - The location of the bundle. This value is used by the Liberty profile

only to identify spec and API bundles in the dev directory.v start-phase - The start phase when the bundle should start during system

startup. The start-phase attribute can take one of the following values:– SERVICE - This value indicates the earliest phase. By default it maps to a start

level of 9.– CONTAINER - This is the default value if no start-phase is provided. It

indicates the container phase when application containers are started. Bydefault it maps to a start level of 12.

– APPLICATION - This value indicates the latest phase when applications arestarted.

Bundles can also be defined to start just before or just after these phases byadding _LATE to be later, or _EARLY to be earlier than the key phase. So if youwant to run immediately after the container phase, use CONTAINER_LATE, and ifyou want to run before the APPLICATION phase then use APPLICATION_EARLY.

For example:Subsystem-Content: com.ibm.ws.app.manager; version="[1,1.0.100)"; start-phase:=APPLICATION,

artifactapi-1.0; type="osgi.subsystem.feature",com.ibm.websphere.security; version="[1,1.0.100)"

IBM-Provision-Capability

Auto features are features that have the IBM-Provision-Capability header in themanifest, and they describe other features that must be installed for this feature towork. When any features are configured in the server.xml file, the FeatureManagerchecks to see whether any “auto features” have had their capabilities satisfied, andif any have, they are automatically activated.

The format of the IBM-Provision-Capability header uses standard OSGi LDAPfilters.

In the following example, if features requiredFeature1-1.0 andrequiredFeature2-1.0 are configured, then this auto feature must be automaticallyactivated. If either of these required features is removed from the server.xml file,this auto feature is automatically deactivated.


IBM-Provision-Capability: osgi.identity; filter:="(&(type=osgi.subsystem.feature)(osgi.identity=requiredFeature1-1.0))",osgi.identity; filter:="(&(type=osgi.subsystem.feature)(osgi.identity=requiredFeature2-1.0))"

In the following example, if either, or both features requiredFeature1-1.0 andrequiredFeature2-1.0 are configured, then this auto feature must be automaticallyactivated. When neither of these features is present in the server.xml file, this autofeature is automatically deactivated.

IBM-Provision-Capability: osgi.identity; filter:="(&(type=osgi.subsystem.feature)(|(osgi.identity=requiredFeature1-1.0)(osgi.identity=requiredFeature2-1.0)))"

IBM-API-Package

This header is used to indicate which API packages are visible to applications. Itmatches the Export-Package header syntax. This means it is a comma separated listof API packages, but each API package can have some attributes.

The following attributes are supported:v version - The version of the API package. It must exactly match the version that

is exported by the bundles; if the version does not match, then the specified APIpackage will not be available to applications and, furthermore, none of the APIpackages in this feature will be available to OSGi applications.

v type - The type of API package. The type attribute takes one of the followingvalues:– spec - Indicates an API provided by a standard body, such as javax.servlet

or org.osgi.framework.– ibm-api - Indicates a value-add API provided by IBM.– api - Indicates a user-defined API. This is the default value.– third-party - Indicates an API that is visible, but not controlled by IBM.

Typically, these are open source packages.– internal - Indicates non-API packages that must be exposed to applications

for them to function. This might be used if Java code is bytecode enhanced,or weaved, to add references to internal code at run time.

For example:IBM-API-Package: javax.servlet; version="2.6"; type="spec",com.ibm.websphere.servlet.session; version="1.1.0"; type="ibm-api",com.ibm.wsspi.webcontainer.annotation; version="0.0.0"; type="internal"

IBM-API-Service

This header is used to indicate which services from the feature are visible to OSGiapplications. The feature must also register the service in the OSGi service registry.

It has the following syntaxIBM-API-Service ::= service ( ’,’ service )*

service-name ::= unique-name ( ’;’ unique-name )*

The service-name is the Java class or interface name of the service. The attributesare interpreted as the service properties for the services.


IBM-SPI-Package

When you create your own Liberty feature, you install it into the user productextension. All the packages in your feature can be accessed by any other featurethat is installed into the user product extension. However, if you want a package inyour feature to be accessed by a feature that is installed into another productextension, you must list the package name in the IBM-SPI-Package header.

Any package listed in the IBM-SPI-Package header must be exported by a bundlein the Liberty feature, by being listed in the Export-Package header of the bundlemanifest file.

The following attribute is supported:v version - The version of the package. The version must exactly match the

version that is specified by the bundle that exports the package. If the versionattribute is not provided, the package version is defaulted to zero.

For example:IBM-SPI-Package: com.sample.myservice.spi; version="1.0.0"

Example feature manifest file

The following example shows the definition for the example-1.0 feature. Thepublic visibility attribute allows this feature to be directly specified in serverconfiguration (server.xml) files; it will also be included in the drop down list offeatures that are displayed in Server Configuration view of the developer toolsand will be available for inclusion in features that are in other product extensions.If this feature is installed into the usr product extension of a runtime install, it canbe configured into a server by including the following code in the server.xml file:<featureManager><feature>usr:example-1.0</feature></featureManager>

Configuration of this feature in a server will result in the specified bundle,com.example.bundle1, being installed and started in the OSGi framework of theserver runtime environment. The single API package, com.example.publicapi, willbe visible to all applications in that server, except for Java EE applications that areconfigured to not have visibility to the api package type. OSGi applications mustexplicitly import the package if they wish to use it. The two SPI packages,com.example.spi.utils and com.acme.spi.spiservices, will be visible to all featurecode in the server, as will the API package.IBM-Feature-Version: 2Subsystem-ManifestVersion: 1.0Subsystem-SymbolicName: exapmple-1.0;visibility:=publicSubsystem-Version: 1.0.0.qualifierSubsystem-Type: osgi.subsystem.featureSubsystem-Content: com.example.bundle1;version="1.0.0"Manifest-Version: 1.0IBM-API-Package: com.example.publicapi;type="api"IBM-SPI-Package: com.example.spi.utils,

com.example.spi.spiservices

Creating a Liberty feature by using developer tools


You can use the WebSphere Application Server Developer Tools to write your ownfeatures and install them into an existing Liberty profile server, or to package themfor delivery to your users.

About this task

To develop a Liberty feature in the WebSphere Application Server Developer Tools,you create a Liberty feature project and target it to the WebSphere ApplicationServer Liberty profile version 8.5.5 or later.

You add OSGi bundles that contain classes and services that implement thefunction provided by your Liberty feature. If your feature provides any APIpackages to OSGi applications, or SPI packages to features in other productextensions, you can declare those packages in the Liberty feature manifest file.

You can export your liberty feature as a compressed file that can be extracted overan existing WebSphere Application Server Liberty profile to extend its capabilities.

For more information on creating Liberty features, see “Liberty profile: Productextension” on page 22.

Creating a Liberty feature by using WebSphere Application Server Developer Toolsis described in more detail in the following subtopics:

Procedure1. “Creating a Liberty feature project.”2. “Adding OSGi bundles to a Liberty feature project” on page 427.3. “Specifying API and SPI packages for a Liberty feature project” on page 427.4. “Installing a Liberty feature to the Liberty profile” on page 428.

Creating a Liberty feature project

To develop a Liberty feature by using the WebSphere Application Server developertools, you must create a Liberty feature project in your workspace.

About this task

A Liberty feature project contains classes and services that implement the functionprovided by your Liberty feature

Procedure

To create a Liberty feature project, complete the following steps:1. Click File > New > Other > OSGi > Liberty Feature Project and then click

Next. The New Liberty Feature Project wizard opens.2. In the Project name field, enter the name of your Liberty feature project.3. Select a Target runtime from the drop down list. The list will include the

WebSphere Application Server Liberty Profile 8.5.5 if it is defined in yourworkspace as an installed runtime environment.

4. Click Next. The OSGi Bundles Selection dialog box opens.5. Select one or more OSGi bundles to add to the Liberty feature project, or click

New Bundle to create an OSGi bundle to add to the Liberty feature project.


You can add further bundles after you have created the Liberty feature project;see “Adding OSGi bundles to a Liberty feature project.”For information on creating an OSGi bundle, see Creating OSGi bundleprojects.

6. Click Finish to create the Liberty feature project.

Results

The Liberty feature project is added to your workspace.

Adding OSGi bundles to a Liberty feature project

A Liberty feature includes OSGi bundles that contain classes and services. Theclasses and services implement the functions that the Liberty feature provides. Youcan include OSGi bundles in a Liberty feature that was created with theWebSphere Application Server Developer Tools by adding the bundles to thecorresponding Liberty feature project.

Procedure

To add OSGi bundles to a Liberty feature project, complete the following steps:1. From the Project Explorer view, open the feature manifest file for the Liberty

feature project by double-clicking the Manifest node in the project hierarchy,

indicated by the manifest icon ( ).2. In the Contained Bundles pane, click Add to select one or more bundles to add

to the Liberty feature project, or click New to create a new OSGi bundle to addto the Liberty feature project. For information on creating an OSGi bundle, seeCreating OSGi bundle projects.

3. (Optional) Specify the version range for the contained bundle by selecting thebundle, clicking Properties, and entering the required values in the MinimumVersion and Maximum Version fields.

4. (Optional) Use the Location field in the Properties dialog box to specify thelocation where you want the bundle to be packaged when exported, relative tothe Liberty profile installation folder. If you want the bundle to be packaged inmore than one location, enter the locations as a comma-separated list. Bydefault, the bundle is packaged in the /lib folder.

Results

The bundle names are added to the Subsystem-Content header in the manifest file.For more information on the headers in the feature manifest file for a Libertyfeature, see “Liberty feature manifest files” on page 421.

Specifying API and SPI packages for a Liberty feature project

Use the Liberty feature manifest file to declare which packages you want to shareas an API or SPI with other applications and features in the Liberty runtimeenvironment.


http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.osgi.common.doc/topics/tcrtbundleprj.html



About this task

A package cannot be declared as an API or SPI unless it is exported by a bundle inthe Liberty feature, by being listed in the Export-Package header of the bundlemanifest file.

Procedure

To specify API and SPI packages for a Liberty feature project, complete thefollowing steps:1. From the Project Explorer view, open the feature manifest file for the Liberty

feature project by double-clicking the Manifest node in the project hierarchy,

indicated by the manifest icon ( ).2. To make one or more API packages available to OSGi applications, click Add in

the IBM API Packages pane.3. When you create your own Liberty feature, you install it into the user product

extension, and all the packages in your feature can be accessed by any otherfeature that is installed into the user product extension. To make one or moreSPI packages available to features in other product extensions, click Add in theIBM SPI Packages pane.

4. (Optional) Specify the package version by selecting the package, clickingProperties, and entering the required value in the Version field.

5. (Optional) For an API package, select the package type from the Type list in theProperties dialog box. The type can be one of the following values:v spec - Indicates an API provided by a standard body, such as javax.servlet

or org.osgi.framework.v ibm-api - Indicates a value-add API provided by IBM.v api - Indicates a user-defined API. This is the default value.v third-party - Indicates an API that is visible, but not controlled by IBM.

Typically, these are open source packages.v internal - Indicates non-API packages that must be exposed to applications

for them to function. This might be used if Java code is bytecode enhanced,or weaved, to add references to internal code at run time.

Results

The package names are added to the IBM-API-Package and IBM-SPI-Packageheaders in the feature manifest file. For more information on the headers in thefeature manifest file for a Liberty feature, see “Liberty feature manifest files” onpage 421.

Installing a Liberty feature to the Liberty profile

When you develop a Liberty feature by using the WebSphere Application ServerDeveloper Tools, you create a Liberty feature project that packages the Libertyfeature in a compressed file. To install the Liberty feature, you must extract thecontents of the compressed file to the Liberty profile environment.

Before you begin

Create a Liberty feature project.


About this task

The compressed file has the following structure:/lib

OSGi bundle JAR files...

/featuresmanifest file

Procedure

To install a Liberty feature to the Liberty profile, complete the following steps:1. In your workspace, right-click your Liberty feature project and select Export >

Liberty Feature.2. In the To file field, specify the location and name of the compressed file to

which you want to export the Liberty feature project.3. Click Finish to export the Liberty feature project to the specified location.4. Extract the contents of the compressed file to the ${wlp.user.dir}/extension

directory.5. Add the feature name to the list of configured features in your server.xml file;

you must prefix the feature name with usr:.For example:<featureManager>

<feature>usr:sample-1.0</feature></featureManager>

Developing an OSGi bundle with simple activation

The most straightforward way to control the lifecycle of your OSGi bundle code isto implement the org.osgi.framework.BundleActivator interface in one of theclasses within your bundle. When the server starts and stops the bundle, the startand stop methods of the BundleActivator interface are called.

About this task

If you are using the WebSphere Application Server Developer Tools, create anOSGi bundle project, and create an OSGi BundleActivator class in that project.Then identify your bundle activator class to the OSGi framework by adding theBundle-Activator header to the bundle MANIFEST.MF file. For example:Bundle-Activator: com.example.bundle.Activator.

Examplepackage com.example.bundle;

import org.osgi.framework.BundleActivator;import org.osgi.framework.BundleContext;

public class Activator implements BundleActivator {public void start(BundleContext context) throws Exception {System.out.println("Sample bundle starting");// Insert bundle activation logic here}

public void stop(BundleContext context) throws Exception {


System.out.println("Sample bundle stopping");// Insert bundle deactivation logic here}}

Receiving configuration data by using the ManagedServiceinterface

Liberty profile configuration is managed by the OSGi Configuration Admin serviceand can be accessed according to the OSGi Configuration Admin servicespecification. Sets of configuration properties are identified by a persisted identity(PID) that is used to associate an element in the server.xml file, where the PID isused as the element name, with a component that registers to receive theproperties.

About this task

For an OSGi bundle whose lifecycle is managed by using the BundleActivatorinterface, a straightforward way to receive the configuration properties is toimplement the org.osgi.service.cm.ManagedService interface, which specifies thePID as one its properties.

Example

In this example, the Activator class implements the ManagedService interface inaddition to the BundleActivator interface, and receives configuration properties byusing the updated method. You can provide default property values to simplifywhat must be specified in the user configuration.public class Activator implements BundleActivator, ManagedService {

public void start(BundleContext context) throws Exception {System.out.println("Sample bundle starting");// register to receive configurationServiceRegistration<ManagedService> configRef = context.registerService(ManagedService.class,this,getDefaults());

}

public void stop(BundleContext context) throws Exception {System.out.println("Sample bundle stopping");configRef.unregister();

}

Hashtable getDefaults() {Hashtable defaults = new Hashtable();defaults.put(org.osgi.framework.Constants.SERVICE_PID, “simpleBundle”);return defaults;

}

public void updated(Dictionary<String, ?> properties) throws ConfigurationException {if (properties != null){String configColor = (String) properties.get(“color”);String configFlavor = (String) properties.get(“flavor”);

}}

}

User configuration for the bundle can optionally be provided in the server.xmlfile, or an included file, by the following entry:<simpleBundle color=”red” flavor=”raspberry” />


Note: The element name in the user configuration, simpleBundle matches the valueof the org.osgi.framework.Constants.SERVICE_PID property used in theManagedService registration.

For more advanced configuration use, see “Providing descriptionsand default values for configuration metadata” on page 439.

Working with the OSGi service registryYou can create an object and register it as an OSGi service for use by third-partyfeatures that are deployed to the Liberty profile.

About this task

Services are the OSGi lightweight and flexible component model. When you createservices and wire them together with Java code, you can use mechanisms such asServiceTrackers to help find the services that you want, and Declarative Services(DS) and Blueprint to specify the wiring declaratively. The Liberty profile hasstandardized on using DS for wiring, except for a small number of cases whereextra flexibility is required.

Registering OSGi services:

You can create an object and register it as an OSGi service for use by third-partyfeatures.

About this task

By using plain old Java code, you can create an object, and then register it as aservice using the BundleContext class. Because the code has to run, you typicallyregister the object in a BundleActivator interface. When you register the object,you can specify what interfaces it provides, and supply a property map. AServiceRegistration object is returned; if necessary, you can use theServiceRegistration object to change the properties at any time. When the serviceis completed, you use the ServiceRegistration object to unregister the service.

To obtain a service, you query the BundleContext for a service that implements arequired interface and, optionally, supply an LDAP-syntax filter to match theservice properties. Depending on the method you call, you can retrieve the bestmatch or all the matches. You can then use the returned ServiceReference thatprovides the properties to do further matching in your code. You can use theServiceReference to get the actual service object. When you have finished usingthe service, you use the BundleContext to release the service.

Procedure

1. Declare the service interface by adding the following code in your bundle.package com.ibm.foo.simple;

/*** Our multifunctional sample interface*/public interface Foo{}

2. Specify the implementation code of the interface.package com.ibm.foo.simple;

/*** The implementation of the Foo interface


*/public class FooImpl implements Foo{

public FooImpl(){}public FooImpl(String vendor){}

/*** used by the ServiceFactory implementation.*/public void destroy() {

}}

3. Use the BundleContext to register the service, modify the service properties,and unregister the service directly in your code.import java.util.Dictionary;

import org.osgi.framework.BundleContext;import org.osgi.framework.ServiceRegistration;

/*** Registers and unregsiters a Foo service directly,* and shows how to modify the service properties in code.*/public class FooController{

private final BundleContext bundleContext;private ServiceRegistration<Foo> sr;

public FooController( BundleContext bundleContext ){

this.bundleContext = bundleContext;}

public void register(Dictionary<String, Object> serviceProperties) {Foo foo = new FooImpl();//typed service registration with one interfacesr = bundleContext.registerService( Foo.class, foo, serviceProperties );//or//untyped service registration with one interfacesr = (ServiceRegistration<Foo>)bundleContext.registerService(

Foo.class.getName(), foo, serviceProperties );//or//untyped service registration with more than one interface (or class)sr = (ServiceRegistration<Foo>)bundleContext.registerService(new String[] {

Foo.class.getName(), FooImpl.class.getName()}, foo, serviceProperties );}

public void modifyFoo(Dictionary<String, Object> serviceProperties) {//with the service registration you can modify the service properties at any timesr.setProperties( serviceProperties );

}

public void unregisterFoo() {//when you are done unregister the service using the service registrationsr.unregister();

}

}

4. Obtain and return the service from another class:package com.ibm.foo.simple;

import java.util.Collection;

import org.osgi.framework.BundleContext;import org.osgi.framework.InvalidSyntaxException;import org.osgi.framework.ServiceReference;

/*** A simple Foo client that directly obtains the Foo service and returns it when done.*/public class FooUser{

private final BundleContext bundleContext;


public FooUser( BundleContext bundleContext ){

this.bundleContext = bundleContext;}

/*** assume there’s only one Foo*/public void useFooSimple() {

ServiceReference<Foo> sr = bundleContext.getServiceReference( Foo.class );String[] propertyKeys = sr.getPropertyKeys();for (String key: propertyKeys) {

Object prop = sr.getProperty( key );//think about whether this is the Foo we want....

}Foo foo = bundleContext.getService( sr );try {

//use foo} finally {

//we’re donebundleContext.ungetService( sr );

}}

/*** Use a filter to select a particular Foo. Note we get a collection back and have to pick one.* @throws InvalidSyntaxException*/public void useFooFilter() throws InvalidSyntaxException {

Collection<ServiceReference<Foo>> srs = bundleContext.getServiceReferences(Foo.class, "(&(service.vendor=IBM)(id=’myFoo’)" );

ServiceReference<Foo> sr = srs.iterator().next();String[] propertyKeys = sr.getPropertyKeys();for (String key: propertyKeys) {

Object prop = sr.getProperty( key );//think about whether this is the Foo we want....

}Foo foo = bundleContext.getService( sr );try {

//use foo} finally {

//we’re donebundleContext.ungetService( sr );

}}

}

Using OSGi services:

Services can be registered and unregistered asynchronously at any time. Thereforeyou should call a service for as short a time as possible. You can use theServiceTracker class to track service availability concurrently.

About this task

If you want to track services, you can create a ServiceTracker object by using yourbundle context, the interface you want, and the properties you want to match, andthen open the tracker. You can query the tracker for the best match or all matches.Make sure that you do not occupy the service after you use it. You do not have totell the tracker you are done; the tracker caches the matching services internally,and clears them as they are unregistered. When you have finished using thetracker, use the serviceTracker.close() method to close it.

Example

The following example shows how to use a ServiceTracker object to track aservice:package com.ibm.foo.tracker;

import com.ibm.foo.simple.Foo;import org.osgi.framework.BundleContext;


import org.osgi.util.tracker.ServiceTracker;

/*** Simplest use of a ServiceTracker to get a service*/public class TrackingFooUser{

private ServiceTracker<Foo,Foo> serviceTracker;

public TrackingFooUser( BundleContext bundleContext ){

serviceTracker = new ServiceTracker<Foo, Foo>( bundleContext, Foo.class, null );serviceTracker.open();

}

public void doFoo() {Foo foo = serviceTracker.getService();//use foo//no need to return it... just don’t use it for long.

}

public void shutdown() {serviceTracker.close();

}}

Composing advanced features by using OSGi DeclarativeServices

Simple features can be controlled by using bundle activator classes and directimplementation of interfaces such as ManagedService and ServiceTracker. Asrelationships between bundles become more complex, it can be better to usefacilities like OSGi Declarative Services (DS) to decompose a feature into individualservices. DS (sometimes known as the Service Component Runtime, or SCR)provides lifecycle and injection management of OSGi services.

About this task

Organizing your feature logic as a set of declarative services has a number ofadvantages:v Activation of the service (which includes loading the Java classes that provide

the service) can be deferred until the service is used; allowing the server to startquickly and to keep resource use to a minimum.

v A reference to the service is placed into the service registry, even when theservice has not been activated, so that dependencies on the service can beresolved.

v Dependencies on other services can be injected at runtime, and activation of thevarious services will be ordered based on such dependencies.

v A service can be deactivated and reactivated when its service properties change,if required.

Detailed information about use of OSGi Declarative Services is available from anumber of online resources, including the OSGi Community Wiki.

This task provides simple descriptions of how to declare your services to DS, howto obtain references to other services, and how to manage configuration propertiesfor each service.


http://wiki.osgi.org

Declaring your services to OSGi Declarative Services

You can use a separate XML file to declare each service within a bundle.

About this task

The Declarative Services (DS) support operates on declared components, each ofwhich is defined by an XML file in the bundle. When a bundle containingcomponent declarations is added to the framework, DS reads each componentdeclaration and registers provided services in the service registry. DS then managesthe lifecycle of the component: controlling its lifecycle based on a combination ofdeclared attributes and satisfied dependencies.

The XML description of components allows DS to resolve service dependencieswithout requiring the component to be instantiated, or its implementation classesto be loaded. This facilitates late and lazy resource loading, which helps improveserver startup and reduce runtime memory footprint.

The XML files that describe the components are listed in the MANIFEST.MF file of thebundle using the Service-Component header, and by convention are located in the/OSGI-INF directory of the bundle.

There are a number of tools that can be used to generate the required XML; thefollowing examples show the XML itself.

This topic describes a simple OSGi bundle using XML to declare its components toDS.

Procedure1. Identify your component through its implementation class name.

<component><implementation class="com.example.bundle.HelloComponent"/>

</component>

2. Declare the service by referencing the name of the interface that it provides.This is the name that will be published to the service registry by DS when thebundle is started.<component><implementation class="com.example.bundle.HelloComponent"/><service>

<provide interface="com.example.HelloService"/></service>

</component>

3. Name the component. The component name also acts as the service “persistedidentity”, or PID, which is used to associate configuration properties with theservice. Configuration properties with a matching PID will be injected into thecomponent on activation, and whenever the properties are updated.<component name="HelloService"><implementation class="com.example.bundle.HelloComponent"/><service><provide interface="com.example.HelloService"/>

</service></component>

Note: In the Liberty profile, a user can add the following element to theserver.xml configuration file, and the properties will be injected into theHelloComponent class.<HelloService firstKey="firstValue" secondKey="secondValue" />


4. Package the XML file into the bundle.For example, the XML file is at the location OSGI-INF/HelloService.xml, andyou add a header to the bundle manifest MANIFEST.MF file so that DS can locatethe file:Service-Component: OSGI-INF/HelloService.xml

If multiple components are packaged in the same bundle, the correspondingXML files must be entered as a comma-separated list. For example:Service-Component: OSGI-INF/HelloService.xml, OSGI-INF/GoodbyeService

5. The Java implementation of the HelloService component is as follows:package com.example.bundle;

import com.example;import org.osgi.service.component.ComponentContext;

/** This class must be public and have a public default constructor for it to be* usable by DS. This class is not required to be exported from the bundle.*/public class HelloComponent implements HelloService {/*** Optional: DS method to activate this component. If this method exists, it* will be invoked when the component is activated. Best practice: this* should be a protected method, not public or private** @param properties* : Map containing service & config properties* populated/provided by config admin*/protected void activate(ComponentContext cContext,Map<String, Object> properties) {modified(properties);}

/*** Optional: DS method to deactivate this component. If this method exists,* it will be invoked when the component is deactivated. Best practice: this* should be a protected method, not public or private** @param reason* int representation of reason the component is stopping*/protected void deactivate(ComponentContext cContext, int reason) {}

/*** Optional: DS method to modify the configuration properties. This may be* called by multiple threads: configuration admin updates may be processed* asynchronously. This is called by the activate method, and otherwise when* the configuration properties are modified while the component is* activated.** @param properties*/public synchronized void modified(Map<String, Object> properties) {// process configuration properties here}

/*** Service method defined by com.example.HelloService interface*/public void sayHello() {System.out.println("Hello");}}

Enabling a service to receive configuration data

To enable a service to receive configuration data, you associate the service with apersisted identity, and code the service to receive the data. You can also providedescriptions and default values for this data, and make the labels and descriptionsavailable in several languages.


About this task

To enable a service to receive configuration data, there are a number of stepsinvolved. Only associating the service with a configuration Admin persistedidentity and coding the service to receive configuration properties are mandatory,and might be considered sufficient for embedded scenarios. The remaining stepsimprove the configuration experience for users.

The steps involved in enabling a service to receive configuration data are describedin the following subtopics:

Procedure1. Associate the service with a Configuration Admin PID (persisted identity).2. Code the service to receive the configuration properties during activation and

when the configuration is modified.3. Provide descriptions and default values for configuration metadata.4. Provide translated strings for configuration property labels and descriptions.

Associating a service with a persisted identity:

You associate a set of configuration properties with its consuming component asdescribed in the OSGi Configuration Admin specification by using the thepersisted identity (PID).

About this task

The OSGi Configuration Admin specification provides a number of associationmechanisms, of which the following are most commonly used in the Libertyprofile:

Register an implementation of org.osgi.service.cm.ManagedService ororg.osgi.service.cm.ManagedServiceFactory directly with the OSGi ConfigurationAdmin service (CA)

This is most commonly used in low-level kernel bundles, where servicemanagement through OSGi Declarative Services (DS) or Blueprint is notavailable at bundle start time. The registration specifies the PID thatidentifies the configuration set to be received.

Define a service to DSThis is the most common way for services in feature bundles to receivetheir configuration. The service name is used as the PID to associateconfiguration data. DS receives the configuration set from CA and passes iton to the defined service.

Example

A service might be declared by using the following entry in the project *.bnd file:Service-Component: com.ibm.ws.transaction; \

provide:=’com.ibm.tx.config.ConfigurationProvider’; \immediate:=’true’; \modified:=’modified’; \implementation:=com.ibm.ws.transaction.services.JTMConfigurationProvider

This generates the following XML code, which can also be coded by the developerinstead of using the bnd Service-Component entry:


<component name="com.ibm.ws.transaction" xmlns="http://www.osgi.org/xmlns/scr/v1.1.0"immediate="true" modified="modified">

<implementation class="com.ibm.ws.transaction.services.JTMConfigurationProvider" /><service>

<provide interface="com.ibm.tx.config.ConfigurationProvider" /></service><property name="service.vendor" value="IBM" />

</component>

The component name, com.ibm.ws.transaction in this example, is used as the PIDfor the association of configuration data. If this component does not provide anymetadata to describe its configuration, you can specify configuration properties forthe component by using that PID in the server.xml file, or an included file, bydefining an entry of the following form:<com.ibm.ws.transaction made.up.property.key="47">

What to do next

Code the service to receive the configuration properties during activation andwhen the configuration is modified.

Coding the service to receive configuration properties:

Configuration properties are available through theorg.osgi.service.component.ComponentContext object that is provided on theactivation method.

Before you begin

You must complete the task described in “Associating a service with a persistedidentity” on page 437.

About this task

If properties are updated after activation has occurred, the method used forinjection depends on the context that the service provides in its OSGi DeclarativeServices (DS) declaration.

Generally, it is best to declare a method that is to be used specifically for injectionof updated properties by using the modified attribute on the service declaration. Ifa modified method is not available, DS deactivates and then reactivates the servicewith the new properties.

Deactivating and then activating a service can also cause dependent services to berecycled, and should be avoided unless specifically required. Using the modifiedattribute is the preferred way to receive configuration updates.

Example

In the previous task, “Associating a service with a persisted identity” on page 437,you defined a service to DS. The following are examples of activate and modifiedmethods from the DS declaration described in that task.private static Dictionary<String, Object> _props = null;

protected void activate(ComponentContext cc) {_props = cc.getProperties();

}

protected void modified(Map<?, ?> newProperties) {if (newProperties instanceof Dictionary) {


_props = (Dictionary<String, Object>) newProperties;} else {

_props = new Hashtable(newProperties);}

}

When you get values from the configuration properties, use the followingmechanisms to allow some flexibility:v Code the methods to expect at least the default properties that are included in

the same bundle, but to make allowances for user overrides, so that migration ofuser configuration is not necessary.

v Ignore redundant or unrecognized properties.

The service must be able to operate on the default configuration alone. To providea reasonable level of function, user overrides must not be mandatory.

What to do next

Provide descriptions and default values for configuration metadata

Providing descriptions and default values for configuration metadata:

The configuration properties for each service can be described in metadata thatcomplies with the OSGi Metatype Service specification. The resulting XML file ispackaged into the bundle in the OSGI-INF/metatype directory, in accordance withthe specification.

About this task

The metadata for the configuration properties of a service includes the persistedidentity (PID) for the configuration set, and the identifier (unique key), data typeand default value for each property. These attributes are used by the Liberty profileconfiguration parser, along with user-provided additions and overrides, topopulate the Configuration Admin service (CA) with the initial configuration.

The metadata can also include user-friendly names and descriptions for eachattribute, which can be used by administrative clients, for example to build anadministrative interface.

The existence of configuration metadata is optional; configuration sets andindividual properties that have no metadata description are fully supported by theconfiguration system in the Liberty profile, and are still parsed from the userconfiguration file and injected into the owning component. However, it is useful toprovide localized metatype descriptions so that developer tools and administrativeclient applications can provide the best possible user configuration experience.

Object component definitions (OCD) can have the ibm:extends attribute. Thisattribute takes a string value, which is the factory PID of another OCD. Thisattribute is a method of providing a more specialized representation of thereferenced factory. The presence of the ibm:extends attribute means that anyattribute definitions from the extended OCD are inherited on the extending OCD.It is also possible to override attribute definitions in the extending type. Forexample:<OCD id="id1"/><OCD id="id2" ibm:extends="id1"/>


where id1 is the "extended" OCD, and id2 is the "extending" OCD.

An OCD that uses the ibm:extends attribute must define a new unique factoryPID, but must not register the associated ManagedServiceFactory or DS component,due to the configuration being delegated to the factory PID defined on theextended type.

Attribute definitions can have the ibm:rename attribute. This attribute applies toattribute definitions that are defined in OCD elements that extend another OCD,by using the ibm:extends attribute for example. The ibm:rename attribute takes astring value, which is the identifier of the attribute definition on the extended OCDto be renamed.

Note: An attribute definition cannot be specialized further on other OCDs byusing ibm:extends if the ibm:final attribute is present.

Example

The following example shows a metatype XML file that provides labels,descriptions and default values for a configuration set:<?xml version="1.0" encoding="UTF-8"?><metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.1.0">

<OCD description="JSP 2.2 configuration" name="JSP 2.2" id="com.ibm.ws.jsp.2.2"><AD description="disableJspRuntimeCompilation"

id="disableJspRuntimeCompilation" required="false" type="String" default="false" /><AD description="useImplicitTagLibs"

id="useImplicitTagLibs" required="false" type="String" default="true" /><AD description="disableResourceInjection"

id="disableResourceInjection" required="false" type="String" default="true" /></OCD>

<Designate pid="com.ibm.ws.jsp.2.2"><Object ocdref="com.ibm.ws.jsp.2.2"/>

</Designate>

</metatype:MetaData>

All the data types in this example are String objects. Ideally, more appropriatedata types should be specified in the metatype description; for example, a Booleandata type for disableJspRuntimeCompilation. This provides a better level ofvalidation of user-entered configuration, and causes the values to be provided tothe consuming service as those data types.

The following example shows a defining webApplication as a specialization ofapplication:<OCD id="qualified.id1" ibm:alias="myConfig"><AD id="attr1" type="String" default="value"/><AD id="attr2" type="int" default="2"/><AD id="attr3" type="int" default="3"/>

<Designate factoryPid="qualified.id1"><Object ocdref="qualified.id1"/></Designate>

<OCD id="qualified.id2" ibm:alias="mySpecializedConfig" ibm:extends="qualified.id1"><AD id="attr1" type="String" default="newFixedValue" ibm:final="true"/><AD id="attr2" type="int" default="2" ibm:rename="myInt"/><AD id="attr4" type="String" default="anotherValue"/></OCD>

<Designate factoryPid="qualified.id2"><Object ocdref="qualified.id2"/></Designate>


v <myConfig/> would result in passing configuration properties of attr1=value,attr2=2, attr3=3 to the qualified.id1 factory.

v <mySpecializedConfig myInt="10"/> would result in passing configurationproperties of attr1=newFixedValue, attr2=10, attr3=3, attr4=anotherValue tothe qualified.id1 factory.

v <mySpecializedConfig attr1="replaceFixedValue"/> would result in passingconfiguration properties of attr1=newFixedValue, attr2=1, attr3=3,attr4=anotherValue to the qualified.id1 factory, and issue a warning that attr1 isfinal for the metatype qualified.id2.

What to do next

Provide translated strings for configuration property labels and descriptions.

Localizing the configuration metadata:

The name and description attributes of each metadata entry can be localized, andthe translated strings packaged into language-specific properties files.

Example

The following example shows how the location of the localized files is specified inthe header of the metatype file:<metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.1.0"

localization="OSGI-INF/I10n/metatype">

where OSGI-INF/I10n is the location of the translated properties files in the bundle,and metatype is the prefix of the default language properties file. For example, ifthe default values, usually in English, are in a file called metatype.properties,then each locale is added with its own suffix: metatype_fr.properties,metatype_es.properties and so on.

Unlike the metatype XML file, which must always be in the OSGI-INF/metatypedirectory, the translated files can be in any location that is within the bundle andspecified by the localization attribute. Do not put them in the OSGI-INF/metatypedirectory alongside the metatype XML file, because the Equinox implementation ofthe Metatype Service specification attempts to parse anything in that location as anXML file, and although that does not cause a failure, it generates unwantedexceptions in the console, and wastes time. The Liberty profile convention is to putthem in the OSGI-INF/I10n directory, but that is not mandatory.

In the metatype XML file, to show that a value is a localized string you use apercent sign at the start of the value. For example, you might use the followingdefinition in the metatype XML file:<AD name="%client.inactivity.timeout" description="%client.inactivity.timeout.desc"

id="clientInactivityTimeout" required="false" type="Integer" default="60" />

and you might use the following definition in the properties file:client.inactivity.timeout=Client inactivity timeoutclient.inactivity.timeout.desc=The maximum duration, in seconds, between transactional requestsfrom a remote client. Any period of client inactivity that exceeds this timeout results in thetransaction being rolled back in this application server.

Liberty profile: Resource location symbols


Liberty user configuration is made more portable through the use of variables thatrepresent symbolic locations. Use of these variables helps to prevent the coding ofabsolute paths that would make the user configuration brittle and less portable.Feature code that receives configuration properties might have to deal with valuesthat contain such variables.

The location service of the Liberty profile can be used to resolve symbolic locationsto physical resources. For example, the symbolic location ${wlp.install.dir}/myFile can be mapped to the local file myFile in the installation directory of theLiberty profile. Most methods return a WsResource object that wraps the physicalresource, but you can also use the resolveString method to transform thesymbolic location into a String that can be used to obtain a File object.

The name of the location service iscom.ibm.wsspi.kernel.service.location.WsLocationAdmin. The Java APIdocumentation for each Liberty profile SPI is available in a separate JAR file in the/dev/spi/ibm/javadoc directory of the server image.

Symbols

The com.ibm.wsspi.kernel.service.location.WsLocationConstants class definessymbols that refer to directory locations:v /

v server.config.dir

v server.output.dir

v server.workarea.dir

v shared.app.dir

v shared.config.dir

v shared.resource.dir

v wlp.install.dir

v wlp.server.name

v wlp.user.dir

v usr.extension.dir

For the meaning of each symbol, see “Liberty profile: Directory locations andproperties” on page 89.

Monitoring local files for changes

The Liberty profile has highly dynamic behavior, responding to changes inconfiguration, applications and other resources. Much of this dynamic behavior isbased on monitoring of the local file system for changes. The service that performsthis monitoring is available to all Liberty features through the FileMonitor SPI.

About this task

The FileMonitor SPI provides different properties to specify what resources aremonitored and with what frequency. You have to implement the FileMonitorinterface and register the implementation class into the service registry.


The Java API documentation for each Liberty profile SPI is available in a separateJAR file in the /dev/spi/ibm/javadoc directory of the server image.

Example...import com.ibm.wsspi.kernel.filemonitor.FileMonitor;...

public class MyFileMonitor implements FileMonitor {...

private final BundleContext bundleContex;...

public MyFileMonitor(BundleContext bundleContext) {this.bundleContext = BundleContext;...

}

public ServiceRegistration<FileMonitor> monitorFiles(Collection<String> paths, long monitorInterval) {...final Hashtable<String, Object> fileMonitorProps = new Hashtable<String, Object>();fileMonitorProps.put(FileMonitor.MONITOR_FILES, paths);fileMonitorProps.put(FileMonitor.MONITOR_INTERVAL, monitorInterval);...return bundleContext.registerService(FileMonitor.class, this, fileMonitorProps);

}...

}

Configuring tracing and logging for features in the Libertyprofile

You can use the tracing and logging mechanism of the Liberty profile for Libertyfeatures.

About this task

The Liberty profile provides the following SPIs for integrating tracing and loggingin your customized feature code:v com.ibm.websphere.ras

v com.ibm.websphere.logging

The Java API documentation for each Liberty profile SPI is available in a separateJAR file in the /dev/spi/ibm/javadoc directory of the server image.

Procedure

The following steps show you how to configure an example Liberty feature, calledmyfeature, to use the tracing and logging mechanism of the Liberty profile:1. Specify the location of the message file for the feature myfeature, and the name

of the group that is required by the com.ibm.websphere.ras.TraceComponentclass.import java.util.ResourceBundle;

public class myFeatureConstants {

public static final String TR_RESOURCE_BUNDLE ="com.mycompany.myFeature.internal.resources.FeatureMessages";

public static final String TR_GROUP = "myFeature";


public static final ResourceBundle messages = ResourceBundle.getBundle(TR_RESOURCE_BUNDLE);

}

2. In the implementation class of the feature service code, call the register()method of the com.ibm.websphere.ras.TraceComponent class to register theimplementation class with the trace manager that is provided by the Libertyprofile. Then, you can configure the trace manger to track the DS methods ofthe feature....import com.ibm.websphere.ras.Tr;import com.ibm.websphere.ras.TraceComponent;

public class myFeatureServiceImpl {

private static final TraceComponent tc = Tr.register(myFeatureServiceImpl.class);

protected void activate(ComponentContext cc, Map<String, Object> newProps) {if (tc.isDebugEnabled()) {

Tr.debug(tc, "myFeatureComponentImpl activated"); }...

3. Use the TraceOptions annotation to specify the trace group name and themessage bundle name.@TraceOptions(traceGroup = myFeatureConstants.TR_GROUP, messageBundle =

myFeatureConstants.TR_RESOURCE_BUNDLE)package com.mycompany.myFeature;

import com.ibm.websphere.ras.annotation.TraceOptions;import com.mycompany.myfeature.internal.myFeatureConstants;...


Chapter 9. Securing the Liberty profile and its applications

This information applies to all types of applications that are deployed on theLiberty profile.

About this task

Security in the Liberty profile supports all the Servlet 3.0 security features andsecured Java JMX connections. The following Liberty features are applicable tosecurity in the Liberty profile:v appSecurity-2.0 enables security for all application resources (web and EJB).v ssl-1.0 enables SSL connections using HTTPS.v restConnector-1.0 enables remote access by JMX client through a REST-based

connector.

To learn about how security works in the Liberty profile, see “Liberty profile:Security” on page 25.

There are several security configuration examples under the /templates/configdirectory of the server image for reference when configuring security for yourapplications on the Liberty profile.

Best practice: When you use the developer tools to configure the security on theLiberty profile, make sure that the configuration created by the tools is similar tothe examples in the ${wlp.install.dir}/templates/config directory of the serverimage. This directory includes examples of configuring some of the most commonsecurity features. If you see any differences in the configuration created by thedeveloper tools and the examples, modify the configuration to fit the configurationin the examples for that feature.

Procedurev Use quickStartSecurity for minimal security configurationv Secure communications with the Liberty profilev Access a secured JMX connector on the Liberty profilev Authenticate users in the Liberty profilev Authorize access to resources in the Liberty profilev Secure a database access applicationv Develop extensions to the Liberty profile security infrastructure

Getting started with security in the Liberty profileYou can use the quickStartSecurity element to quickly enable a simple (one user)security setup for the Liberty profile.

About this task

This topic describes the basic steps required to set up a secured Liberty profileserver and web application. Additionally, configuration actions within the Libertyprofile are dynamic, which means the configuration updates take effect withouthaving to restart the server.


Procedure1. Create and start your server.

v Windows On Windows systems:server.bat create MyNewServerserver.bat start MyNewServer

v Linux On all systems other than Windows systems:server create MyNewServerserver start MyNewServer

2. Include the appSecurity-2.0 and servlet-3.0 features in the server.xml file.The server.xml file is in the server directory of myNewServer, for example,wlp\usr\servers\myNewServer\server.xml.<featureManager>

<feature>appSecurity-2.0</feature><feature>servlet-3.0</feature>

</featureManager>

3. Define the user name and password that is to be granted the Administratorrole for server management activities.<quickStartSecurity userName="Bob" userPassword="bobpwd" />

Note: Choose a user name and password that are meaningful to you. Neveruse the name and password in the example for your applications.

4. Configure the deployment descriptor with the relevant security constraints toprotect the web resource. For example, use <auth-constraint> and <role-name>elements to define a role that can access the web resource.The following example web.xml file shows that access to all the URIs in theapplication is protected by the testing role.<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app id="myWebApp">

<servlet id="Default">

<servlet-name>myWebApp</servlet-name><servlet-class>com.web.app.MyWebAppServlet</servlet-class><load-on-startup/>

</servlet>

<servlet-mapping id="ServletMapping_Default">

<servlet-name>myWebApp</servlet-name><url-pattern>/*</url-pattern>

</servlet-mapping>

<security-role>

<role-name>testing</role-name></security-role>

<security-constraint>

<web-resource-collection><url-pattern>/*</url-pattern>

</web-resource-collection><auth-constraint><role-name>testing</role-name>

</auth-constraint></security-constraint>

<login-config>

<auth-method>BASIC</auth-method></login-config>

</web-app>

5. Configure your application in the server.xml file.

In the following example, the user Bob is mapped to the testing role of theapplication:<application type="war" id="myWebApp" name="myWebApp"

location="${server.config.dir}/apps/myWebApp.war"><application-bnd>

<security-role name="testing"><user name="Bob" />


</application>

6. Access your application and log in with the user name Bob. The default URLfor the myWebApp application is http://localhost:9080/myWebApp

Results

You have now secured your application.

Liberty profile: Quick overview of securityThis topic describes some common security terms, along with an example thathelps you understand the basic workflow of security in the Liberty profile.

Security key terms

AuthenticationAuthentication confirms the identity of a user. The most common form ofauthentication is user name and password, such as through basicauthentication or form login for web applications. When a user isauthenticated, the source of a request is represented as a Subject object atrun time.

AuthorizationAuthorization determines whether a user has access to a given role withinthe system. The Java EE model uses subjects, roles, and role mappings todetermine if access is allowed.

Role A role is defined within the Java EE application. Some roles, such as theAdministrator role, are predefined by the system. Other roles are definedby the application developer. In Java EE, subjects are usually granted ordenied access to a role based on the roles they perform within theapplication.

SubjectA subject is both a general term and a Java object:javax.security.auth.Subject. Generally, the term subject means activeentities within the system, such as users on the system, and even thesystem process itself.

Security workflow example

The following example demonstrates how the security is applied when a userrequests access to a resource. For example, a user Bob wants to access a servletmyWebApp. See the code samples in “Getting started with security in the Libertyprofile” on page 445.

To access the servlet myWebApp, the following conditions must be true:1. Bob must be able to log in to the system because the servlet is protected.2. Bob must be in the testing role because the servlet is restricted by using an

auth-constraint element in the deployment descriptor.

Chapter 9. Securing the Liberty profile and its applications 447

If Bob cannot log in to the system, or Bob is not in the testing role, then the accessto the servlet myWebApp is denied.

Another user Alice can log in to the system because Alice is a valid user. ButAlice is not in the testing role. An HTTP 403 error (Access Denied/Forbidden)displays when Alice logs in.

Setting up BasicRegistry and role mapping on the Libertyprofile

You can configure the Liberty profile to authenticate and authorize users using abasic user registry.

Before you begin

The Liberty features appSecurity-2.0 and servlet-3.0 must beenabled in the server.xml file of the Liberty profile.

About this task

This topic goes through the steps to set up a basic user registry and configuremore role mapping in the server.xml file for a Liberty profile server.

Procedure1. Configure the basic registry as follows. Make sure to use a user name and

password that are meaningful to you. Never use the name and password in theexample for your applications.<basicRegistry id="basic" realm="WebRealm"><user name="Bob" password="bobpwd" />

</basicRegistry>

2. Optional: Grant the user with the Administrator role if the user is used toperform remote system management activities. This step is done automaticallywhen using the quickStartSecurity element.<administrator-role>

<user>Bob</user></administrator-role>

3. Encode the password within the configuration. You can get the encoded valueby using the securityUtility encode task.

4. Add additional users. Make sure that each user name is unique.<basicRegistry id="basic" realm="WebRealm">

<user name="Bob" password="bobpwd" /><user name="user1" password="user1pwd" /><user name="user2" password="user2pwd" />

</basicRegistry>

5. Create groups for users. Make sure that each group name must be unique.<basicRegistry id="basic" realm="WebRealm">

<user name="Bob" password="bobpwd" /><user name="user1" password="user1pwd" /><user name="user2" password="user2pwd" />

<group name="myAdmins"><member name="Bob" /><member name="user1" />

</group>

<group name="users"><member name="user1" /><member name="user2" />


6. Assign a user group to the Administrator role.


<administrator-role><user>Bob</user><group>myAdmins</group>


7. Assign some users and groups to the testing role of an application.<application type="war" id="myWebApp" name="myWebApp"

location="${server.config.dir}/apps/myWebApp.war"><application-bnd>

<security-role name="tesing"><user name="Bob" /><user name="user1" /><group name="users" />


</application>

What to do next

Configure security-related elements in the deployment descriptor of yourapplication. See “Getting started with security in the Liberty profile” on page 445for a sample web.xml file.

Securing communications with the Liberty profileYou can configure the Liberty profile server to provide secure communicationsbetween a client and the server.

About this task

To configure secure communications, you can either specify a minimal SSLconfiguration or a detailed SSL configuration in the server.xml file. The minimalconfiguration only requires the SSL feature and a keystore entry to be specified. Inthe ${wlp.install.dir}/templates/config directory of the Liberty profile, there isan sslConfig.xml file that contains several examples of SSL configurations.

The SSL configuration that is designated as thedefault SSL configuration is used to create the process's default SSLContext usingthe SSLContext.setDefault() method. The default SSL configuration can be theminimal SSL configuration, or the configuration identified by the sslRef attributeon the sslDefault element if multiple SSL configurations are defined. Because thedefault SSLContext is set on the process, the javax.net.ssl.keyStore andjavax.net.ssl.trustStore properties will not be recognized.

Procedurev Enable SSL communications between a client and a Liberty profile serverv Optional: Create a keystore from the command promptv Optional: Encode passwords from the command promptv Optional: Configure client certificate authentication between your application

and the Liberty profile server

Enabling SSL communication for the Liberty profileTo enable SSL communication for the Liberty profile, there is a minimal set of SSLconfiguration options. It assumes most of the SSL options and only requires somekeystore configuration information.


About this task

SSL client authentication occurs during the connection handshake by using SSLcertificates. The SSL handshake is a series of messages that are exchanged over theSSL protocol to negotiate for connection-specific protection. During the handshake,the secure server requests that the client send back a certificate or certificate chainfor the authentication. To enable SSL for the Liberty profile, you add the ssl-1.0Liberty feature to the server.xml file, along with code of the keystore informationfor authentication.

Procedure1. Enable the ssl-1.0 Liberty feature in the server.xml file.

<featureManager><feature>ssl-1.0</feature>

</featureManager>

Note: If application security is required and security information is redirectedto a secure port, you must add the appSecurity-2.0 Liberty feature to theserver.xml file.

2. Add the keystore service object entry to the server.xml file. The keyStoreelement is called defaultKeyStore and contains the keystore password. Thepassword can be entered in clear text or encoded. The securityUtility encodeoption can be used to encode the password.<keyStore id="defaultKeyStore" password="yourPassword" />

An example of a SAF keyring in the minimal configuration:<keyStore id="defaultKeyStore" location="safkeyring:///WASKeyring"

type="JCERACFKS" password="password" fileBased="false"readOnly="true" />

In this configuration the keystore type is JKS. You can create this defaultkeystore using the securityUtility createSSLCertificate option. The server createsthe keystore for you if it does not exist during SSL initialization. The passwordmust be at least six characters long. The type of the keystore is JKS by default.Keystore of other types can also be specified in the minimal SSL configurationif the keystore file is already created. Only JKS keystore files are created by theserver if the keystore file does not exist. The certificate has a validity period of365 days, the CN value of the subjectDN is the host name of the machine wherethe server is running, and the signature algorithm of the certificate is SHA1 withRSA.The single keystore entry for a minimal SSL configuration can be extended toinclude the location and type as well.<keyStore id="defaultKeyStore" location="myKeyStore.p12" password="yourPassword" type="PKCS12"/>

The location parameter can be an absolute path to the keystore file. If it is anabsolute path, then the keystore file is assumed to have been already created.Keystore of other types can also be specified in the minimal SSL configurationif the keystore file is already created. When the minimal SSL configuration isused, the SSL configuration defaults are used to create the SSL context for anSSL handshake. The configuration protocol is SSL_TLS by default. The HIGHciphers, 128 bit, and higher cipher suites can be used.

Liberty profile: SSL configuration attributesSSL configurations contain attributes that you use to control the behavior of theserver SSL transport layer on a Liberty profile. This topic iterates all the settingsavailable for an SSL configuration.


SSL Feature

To enable SSL on a server, the SSL feature must be included in the server.xml file:<featureManager><feature>ssl-1.0</feature>

</featureManager>

SSL Default

You can have multiple SSL configurations configured. If more than one SSLconfiguration is configured, then the default SSL configuration must be specified inthe server.xml file using the sslDefault service configuration.

Table 18. Attribute of the sslDefault element. This table describes the attribute of thesslDefault element.

Attribute Description Default Value

sslRef The sslRef attribute specifies theSSL configuration to be used as thedefault. If this attribute is notspecified, then the value used isdefaultSSLSettings.

The default SSL Configurationname is defaultSSLConfig.

In the server.xml file, the entry is as follows:<sslDefault sslRef="mySSLSettings" />

SSL Configuration

You use the SSL configuration attributes to customize the SSL environment to suityour needs. These attributes can be set on the ssl service configuration element inthe server.xml file.

Table 19. Attributes of the SSL element. This table describes the attributes of the sslelement.


id The id attribute assigns a uniquename to the SSL configurationobject.

No default value; aunique name must bespecified.

keyStoreRef The keyStoreRef attribute namesthe keystore service object thatdefines the SSL configurationskeystore. The keystore holds thekey required to make an SSLconnection.

No default value; akeystore referencemust be specified.

trustStoreRef The trustStoreRef attributenames the keystore service objectthat defines the SSLconfigurations truststore. Thetruststore holds certificatesrequired for signing verification.

trustStoreRef is anoptional attribute. Ifthe reference ismissing, the keystorespecified bykeyStoreRef is used.

clientAuthentication The clientAuthenticationattribute determines whetherSSL client authentication isrequired.

Default value isfalse.


Table 19. Attributes of the SSL element (continued). This table describes the attributes ofthe ssl element.


clientAuthenticationSupported TheclientAuthenticationSupportedattribute determines whetherSSL client authentication issupported. The client does nothave to supply a clientcertificate. If theclientAuthentication attributeis set to true, the value of theclientAuthenticationSupportedattribute is overwritten.

Default value isfalse.

sslProtocol The sslProtocol attributedefines the SSL handshakeprotocol. The protocol can beSDK-dependent, so if youmodify the protocol make surethat the value is supported bythe SDK you are running under.

Default value isSSL_TLS.

securityLevel The securityLevel attributedetermines the cipher suitegroup to be used by the SSLhandshake. The attribute has oneof the following values:

v HIGH (128-bit ciphers andhigher)

v MEDIUM (40-bit ciphers)

v WEAK (for all ciphers withoutencryption)

v CUSTOM (if the cipher suitegroup is customized).

When you set the enableCiphersattribute with a specific list ofciphers, the system ignores thisattribute.

Default value is HIGH.

enableCiphers The enableCiphers attribute isused to specify a unique list ofcipher suites. Separate eachcipher suite in the list with aspace. If the enableCiphersattribute is set then thesecurityLevel attribute isignored.

No default value.

serverKeyAlias The serverKeyAlias attributenames the key in the keystore tobe used as the SSLconfigurations key. This attributeis only required if the keystorehas more than one key entry init. If the keystore has more thanone key entry and this attributedoes not specify a key, then theJSSE picks a key.

No default value.


Table 19. Attributes of the SSL element (continued). This table describes the attributes ofthe ssl element.


clientKeyAlias The clientKeyAlias attributenames the key in the keystore tobe used as the key for SSLconfiguration whenclientAuthentication isenabled. The attribute is onlyrequired if the keystore containsmore than one key entry.

No default value.

Note:

v The key manager is used by the SSL handshake to determine what certificatealias to use. The key manager is not configured in the server.xml file, it isretrieved from the security property ssl.KeyManagerFactory.algorithm of theSDK.

v The trust manager is used by the SSL handshake to make trust decisions. Thetrust manager is not configured in the server.xml file, it is retrieved from thesecurity property ssl.TrustManagerFactory.algorithm of the SDK.

Here is an example of how the ssl element is configured in the server.xml file:<ssl id="myDefaultSSLConfig"

keyStoreRef="defaultKeyStore"trustStoreRef="defaultTrustStore" />

<ssl id="myDefaultSSLConfig"

keyStoreRef="defaultKeyStore"trustStoreRef="defaultTrustStore"clientAuthentication="true"sslProtocol="TLS" />

<ssl id="myDefaultSSLConfig"

keyStoreRef="defaultKeyStore"serverKeyAlias="default" />

Keystore Configuration

The keystore configuration consists of the attributes required to load a keystore.These attribute can be set on the keystore service configuration in the server.xmlfile.

Table 20. Attributes of the keystore element. This table explains the attributes of keystoreelement.


id The id attribute defines a uniqueidentifier of the keystore object.

No default value, a unique namemust be specified.

Table 20. Attributes of the keystore element (continued). This table explains the attributesof keystore element.


location The location attribute specifies thekeystore file name. The value caninclude the absolute path to thefile. If the absolute path is notprovided, then the code looks forthe file in the${server.config.dir}/resources/security directory.

In the SSL minimal configuration,the location of the file is assumedto be ${server.config.dir}/resources/security/key.jks.

type The type attribute specifies thetype of the keystore. Check thatthe keystore type that you specifyis supported by the SDK you arerunning on.

Default value is jks.

password The password attribute specifies thepassword used to load the keystorefile. The password can be storedeither in clear text or encoded. Forinformation about how to encodethe password, see thesecurityUtility encode option.

Must be provided.

provider The provider attribute specifies theprovider to be used to load thekeystore. Some keystore typesrequired a provider other than theSDK default.

By default no provider is specified.

fileBased The fileBased attribute specifieswhether the keystore is file-based.

Default value is true.

Here is an example of how the keystore element is configured in the server.xmlfile:keyStore id="defaultKeyStore"

location="MyKeyStoreFile.jks"type="JKS" password="myPassword" />

Full SSL Configuration Example

Here is an example of a full SSL configuration in the server.xml file. This examplehas the following SSL configurations:v defaultSSLSettings

v mySSLSettings

By default, the SSL configuration is set to defaultSSLConfig.<featureManager><feature>ssl-1.0</feature>

</featureManager>

<!-- default SSL configuration is defaultSSLSettings -><sslDefault sslRef="defaultSSLSettings" /><ssl id="defaultSSLSettings"

<keyStore id="defaultKeyStore"location="key.jks"type="JKS" password="defaultPWD" />

<keyStore id="defaultTrustStore"location="trust.jks"type="JKS" password="defaultPWD" />

<ssl id="mySSLSettings"keyStoreRef="myKeyStore"trustStoreRef="myTrustStore"clientAuthentication="true" />

<keyStore id="LDAPKeyStore"location="${server.config.dir}/myKey.p12"type="PKCS12"password="{xor}CDo9Hgw=" />

<keyStore id="LDAPTrustStore"location="${server.config.dir}/myTrust.p12"type="PKCS12"password="{xor}CDo9Hgw=" />

Creating SSL certificates for your Liberty profile using theUtilities menu

Using the Liberty profile Utilities menu in the developer tools, you can create anSSL certificate.

Procedure1. In the Servers view, right-click your Liberty server profile, and select Utilities >

Create SSL Certificate.2. On the Create SSL Certificate page, you can create a default secure socket layer

(SSL) certificate to use with your server.a. In the Keystore password field, type a password for your SSL certificate.b. Click the Specify validity period (days) field, and specify the number of

days you want the certificate to be valid for. Minimum length of time is 365days.

c. Click the Specify subject (DN): field, and provide a value for your SSLsubject.

3. Click Finish.

Creating SSL certificates from the command promptYou can use the securityUtility command to create a default SSL certificate foruse by the Liberty profile configuration.

Procedure1. Open a command prompt, then change directory to the wlp/bin directory.2. Create an SSL certificate.

Run the following command. If you do not specify a server name or apassword, the command does not run. See “Liberty profile: securityUtilitycommand” on page 456.securityUtility createSSLCertificate --server server_name --password your_password

Results

You have created a default keystore key.jks for the specified server. The keystorefile is located under the /resources/security directory of the specified server. If adefault keystore already exists, the command does not execute successfully.


What to do next

You can configure your server to use the keystore and enable the SSL in the serverconfiguration by adding the following lines to the server configuration file:


</featureManager>

<keyStore id="defaultKeyStore" password="keystore_password" />

See “Enabling SSL communication for the Liberty profile” on page 449.

Liberty profile: securityUtility commandThe securityUtility command supports plain text encryption and SSL certificatecreation for a Liberty profile.

Syntax

The command syntax is as follows:securityUtility task [options]

where the options are different based on the value of task.

Parameters

The following tasks are available for the securityUtility command:

encodeEncodes the provided text using Base64. If no arguments are specified, thecommand enters interactive mode. Otherwise, the provided text isencoded. Text with spaces must be put in quotation marks if specified asan argument.

The arguments are:

--encoding=encoding_typeSpecifies the type of encoding to be used. Supported encodings arexor or aes. The default value is xor.

--key=encryption_keySpecifies the key to be used when encoding using AES encryption.This string is hashed to produce an encryption key that is used toencrypt and decrypt the password. The key can be provided to theserver by defining the variable wlp.password.encryption.keywhose value is the key. If this option is not provided, a default keyis used.

See also “Liberty profile: The limits to protection through passwordencryption” on page 47.

createSSLCertificateCreates a default SSL certificate for use in server configuration. Generatedkeystore file key.js is placed under /resources/security directory of theserver specified in --server name. The key algorithm is RSA and signaturealgorithm is SHA1 with RSA. For more control over the certificate creation,use keytool directly.

The arguments are:


--server=nameSpecifies the name of the Liberty profile server for keystorecreation. This option is required.

--password=passwdSpecifies the password to be used in the keystore, which must beat least six characters in length. This option is required.

--passwordEncoding=password_encoding_typeSpecifies how to encode the keystore password. Supportedencodings are xor or aes. The default value is xor.

--passwordkey=password_encryption_keySpecifies the key to be used when encoding the keystore passwordusing AES encryption. This string is hashed to produce anencryption key that is used to encrypt and decrypt the password.The key can be provided to the server by defining the variablewlp.password.encryption.key whose value is the key. If this optionis not provided, a default key is used.

--validity=daysSpecifies the number of days that the certificate is valid, whichmust be equal to or greater than 365. The default value is 365. Thisoption is optional.

--subject=DNSpecifies the Domain Name (DN) for the certificate subject andissuer. The default value is CN=localhost,O=ibm,C=us. This optionis optional.

help Prints help information for a specified task.

Usage

The following examples demonstrate correct syntax:securityUtility encode GiveMeLiberty --encoding=aessecurityUtility createSSLCertificate --server=myserver --password=mypassword --validity=365

--subject=CN=mycompany,O=myOrg,C=myCountrysecurityUtility help createSSLCertificate

Configuring your web application and server for clientcertificate authentication

You can configure your web application on the Liberty profile using SSL clientauthentication.

Before you begin

This topic assumes that you have already created the SSL certificates, for exampleas described in “Creating SSL certificates from the command prompt” on page 455.

About this task

Client certificate authentication occurs if the server-side requests that the client-sidesend a certificate. A WebSphere server can be configured for client certificateauthentication on the SSL configuration. To do this, you add the ssl-1.0 Libertyfeature to the server.xml file, along with code that tells the server the keystoreinformation for authentication.


For details of which aspects of SSL are supported, see “Liberty features” on page14.

Procedure1. Ensure that the deployment descriptor for your web application specifies client

certificate authentication as the authentication method to use.Check that the deployment descriptor includes the following element:<auth-method>CLIENT-CERT</auth-method>

Note: You can use a tool such as Rational Application Developer to create thedeployment descriptor.

2. Optional: Generate an SSL certificate using the command prompt. See “Libertyprofile: securityUtility command” on page 456.

3. Configure your server to enable SSL client authentication by adding thefollowing lines to the server.xml file:


<featureManager>

<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore"trustStoreRef="defaultTrustStore" clientAuthenticationSupported="true" />

<keyStore id="defaultKeyStore" location="key.jks" type="JKS" password="defaultPWD" /><keyStore id="defaultTrustStore" location="trust.jks" type="JKS" password="defaultPWD" />

v If you specify clientAuthentication="true", the server requests that a clientsends a certificate. However, if the client does not have a certificate, or thecertificate is not trusted by the server, the handshake does not succeed.

v If you specify clientAuthenticationSupported="true", the server requeststhat a client sends a certificate. However, if the client does not have acertificate, or the certificate is not trusted by the server, the handshake mightstill succeed.

v If you do not specify either clientAuthentication orclientAuthenticationSupported, or you specifyclientAuthentication="false" or clientAuthenticationSupported="false",the server does not request that a client send a certificate during thehandshake.

4. Add a client certificate to your browser. See the documentation of your browserfor adding client certificates.

5. Make sure the server trusts any client certificates that are used.6. Make sure any client certificates used for client authentication are mapped to a

user identity in your registry.v For the basic registry, the user identity is the common name (CN) from the

distinguished name (DN) of the certificate.v For a Lightweight Directory Access Protocol (LDAP) registry, the DN from

the client certificate must be in the LDAP registry.7. To use basic authentication, user ID and password only, if client certificate

authentication does not succeed, add the following line to your server.xml file.<webAppSecurity allowFailOverToBasicAuth="true" />

Note: If you specify allowFailOverToBasicAuth="false" or do not specifyallowFailOvertoBasicAuth, and the client certificate authentication does notsucceed, the request generates a 403 Authentication error message, and theclient is not prompted for basic authentication.


Authenticating users in the Liberty profileThe Liberty profile server uses a user registry to authenticate a user and retrieveinformation about users and groups to perform security-related operations,including authentication and authorization.

About this task

To learn about how authentication works in the Liberty profile, see “Libertyprofile: Authentication” on page 29.

The authentication tasks that you can configure might vary depending on yourrequirements. Unless you have used the quickStartSecurity element that canconfigure only one user, you have to configure the user registry at the least. Youdo not have to configure the values for JAAS, authentication Cache and SSO tasksunless you want to change the default values. Configure TAI configuration onlywhen you have an implementation of TAI interface to handle authentication.

You can complete one or more of the following authentication tasks:

Procedurev Configure authentication cache on the Liberty profilev Configure a custom JAAS login module for the Liberty profilev Configure SSO on the Liberty profilev Configure a user registry for the Liberty profilev Configure RunAS authentication in the Liberty profilev Configure TAI for the Liberty profile

Configuring a user registry for the Liberty profileYou can store user and group information for authentication in several types ofregistry. For example you can use a basic user registry, or an LDAP registry.

Procedurev Configure a basic user registry for the Liberty profilev Configure an LDAP user registry for the Liberty profile

Configuring a basic user registry for the Liberty profileYou can configure a basic user registry in the Liberty profile for authentication.

About this task

You can use a basic user registry by defining the users and groups information forauthentication on the Liberty profile server. To do this, you add theappSecurity-2.0 Liberty feature to the server.xml file, along with user informationin the basicRegistry element.

Procedure1. Add the appSecurity-2.0 Liberty feature to the server.xml file.2. Optional: To use SSL, add the ssl-1.0 Liberty feature in the server.xml file.

See “Enabling SSL communication for the Liberty profile” on page 449.3. Configure the basic registry for the server as follows:


<basicRegistry id="basic" realm="customRealm"><user name="mlee" password="p@ssw0rd" /><user name="rkumar" password="pa$$w0rd" /><user name="gjones" password="{xor}Lz4sLCgwLTs=" /><group name="students">

<member name="mlee" /><member name="rkumar" />


Notes:

v You must use unique names for your users and groups.v You should remove all trailing and leading spaces from the user and group

names.

vDistributed operating systems If you use the WebSphere Application Server

Developer Tools for Eclipse, the password is encoded for you automatically.v If you edit the server.xml file directly, you can use the securityUtility

encode command to encode the password for each user. The securityUtilitycommand-line tool is available in the $INSTALL_ROOT/bin directory. When yourun the securityUtility encode command, you either supply the passwordto encode as an input from the command line or, if no arguments arespecified, the tool prompts you for the password. The tool then outputs theencoded value. Copy the value output by the tool, and use that value for thepassword. For example, to encode the password GiveMeLiberty, run thefollowing command:securityUtility encode GiveMeLiberty

v A complete sample configuration of the basic registry is available in the${wlp.install.dir}/templates/config/basicRegistry.xml file.

Configuring an LDAP user registry with the Liberty profileYou can configure a Lightweight Directory Access Protocol (LDAP) server with theLiberty profile for authentication.

Before you begin

Ensure that your LDAP server is up and running, and that the host name and portnumber of the LDAP server are already in your known list.

About this task

You can use an existing LDAP server for application authentication on the Libertyprofile. To do this, you add the appSecurity-2.0 Liberty feature to the server.xmlfile and specify, in the server.xml file, the configuration information for connectingto the LDAP server.

Avoid trouble: You can refer to the sample LDAP configuration ldapRegistry.xmlfile in the ${wlp.install.dir}/templates/config directory, and make sure theconfiguration in your server.xml file is similar to the one in the sample file.

Procedure1. Add the appSecurity-2.0 Liberty feature to the server.xml file.2. Optional: To communicate with an SSL-enabled LDAP server, add the ssl-1.0

Liberty feature in the server.xml file.3. Optional: Copy the truststore to the server configuration directory. For example,

you can use the ${server.config.dir} variable.


For SSL communication with an LDAP server to succeed, the Signer certificatefor the LDAP server must be added to the truststore that is referenced by thesslAlias attribute of the <ldapRegistry> element. In the following examples,the Signer certificate must be added to the LdapSSLTrustStore.jks.

4. Configure the LDAP entry for the server.If you do not want SSL for the LDAP server, remove all SSL andkeystore-related lines from the following examples.You configure the LDAP server in the server.xml file or using the WebSphereApplication Server Developer Tools for Eclipse. For sample configurations ofother LDAP server, refer to the ${wlp.install.dir}/templates/config/ldapRegistry.xml file.v For IBM Directory Server:

<ldapRegistry id="ldap" realm="SampleLdapIDSRealm"host="ldapserver.mycity.mycompany.com" port="389" ignoreCase="true"baseDN="o=mycompany,c=us"userFilter="(&(uid=%v)(objectclass=ePerson))"groupFilter="(&(cn=%v)(|(objectclass=groupOfNames)

(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"userIdMap="*:uid"groupIdMap="*:cn"groupMemberIdMap="mycompany-allGroups:member;mycompany-allGroups:uniqueMember;

groupOfNames:member;groupOfUniqueNames:uniqueMember"ldapType="IBM Tivoli Directory Server"sslEnabled="true"sslRef="LDAPSSLSettings">

</ldapRegistry>

<sslDefault sslRef="LDAPSSLSettings" /><ssl id="LDAPSSLSettings" keyStoreRef="LDAPKeyStore" trustStoreRef="LDAPTrustStore" />

<keyStore id="LDAPKeyStore" location="${server.config.dir}/LdapSSLKeyStore.jks"type="JKS" password="{xor}CDo9Hgw=" />

<keyStore id="LDAPTrustStore" location="${server.config.dir}/LdapSSLTrustStore.jks"type="JKS" password="{xor}CDo9Hgw=" />

v For Microsoft Active Directory Server:<ldapRegistry id="ldap" realm="SampleLdapADRealm"

host="ldapserver.mycity.mycompany.com" port="389" ignoreCase="true"baseDN="cn=users,dc=adtest,dc=mycity,dc=mycompany,dc=com"bindDN="cn=testuser,cn=users,dc=adtest,dc=mycity,dc=mycompany,dc=com"bindPassword="testuserpwd"userFilter="(&(sAMAccountName=%v)(objectcategory=user))"groupFilter="(&(cn=%v)(objectcategory=group))"userIdMap="user:sAMAccountName"groupIdMap="*:cn"groupMemberIdMap="memberOf:member"ldapType="Microsoft Active Directory"sslEnabled="true"sslRef="LDAPSSLSettings">

</ldapRegistry>

<sslDefault sslRef="LDAPSSLSettings" /><ssl id="LDAPSSLSettings" keyStoreRef="LDAPKeyStore" trustStoreRef="LDAPTrustStore" />

<keyStore id="LDAPKeyStore" location="${server.config.dir}/LdapSSLKeyStore.jks"type="JKS" password="{xor}CDo9Hgw=" />

<keyStore id="LDAPTrustStore" location="${server.config.dir}/LdapSSLTrustStore.jks"type="JKS" password="{xor}CDo9Hgw=" />

If you use the WebSphere Application Server Developer Tools for Eclipse, thebindPassword password is encoded for you automatically. If you edit theserver.xml file directly, you can use the securityUtility encode command toencode the bindPassword password for you. The securityUtilitycommand-line tool is available in the $INSTALL_ROOT/bin directory. When yourun the securityUtility encode command, you either supply the password toencode as an input from the command line or, if no arguments are specified,the tool prompts you for the password. The tool then outputs the encodedvalue. Copy the value output by the tool, and use that value for thebindPassword password.


5. Optional: Configure certificate filter mode for theLDAP server.<ldapRegistry id="LDAP" realm="SampleLdapIDSRealm"

host="myldap.ibm.com" port="389" ignoreCase="true"baseDN="o=ibm,c=us"certificateMapMode="CERTIFICATE_FILTER"certificateFilter="uid=${SubjectCN}"userFilter="(&(uid=%v)(objectclass=ePerson))"groupFilter="(&(cn=%v)(|(objectclass=groupOfNames)

(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"userIdMap="*:uid"groupIdMap="*:cn"groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;

groupOfNames:member;groupOfUniqueNames:uniqueMember"ldapType="IBM Tivoli Directory Server" searchTimeout="8m" />

For more information about certificate map mode in the Liberty profile, see“Liberty profile: LDAP certificate map mode.”

6. Optional: Configure failover for multiple LDAP servers.<ldapRegistry id="LDAP" realm="SampleLdapIDSRealm"

host="ldapserver1.mycity.mycompany.com" port="389" ignoreCase="true"baseDN="o=ibm,c=us" ldapType="IBM Tivoli Directory Server" idsFilters="ibm_dir_server">

<failoverServers name="failoverLdapServersGroup1"><server host="ldapserver2.mycity.mycompany.com" port="389" /><server host="ldapserver3.mycity.mycompany.com" port="389" /></failoverServers><failoverServers name="failoverLdapServersGroup2"><server host="ldapserver4.mycity.mycompany.com" port="389" /></failoverServers></ldapRegistry>

<idsLdapFilterProperties id="ibm_dir_server"userFilter="(&(uid=%v)(objectclass=ePerson))"groupFilter="(&(cn=%v)(|(objectclass=groupOfNames)

(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"userIdMap="*:uid" groupIdMap="*:cn"groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;

groupOfNames:member;groupOfUniqueNames:uniqueMember"></idsLdapFilterProperties>

For more information about the ldapRegistry and failoverServers elements,see “Liberty profile: Configuration elements in the server.xml file” on page 97.

7. Optional: Configure LDAP registry federation.<ldapRegistry id="LDAP1" realm="SampleLdapIDSRealm"

host="ldapserver1.mycity.mycompany.com" port="1389" ignoreCase="true"baseDN="o=tds" ldapType="IBM Tivoli Directory Server" searchTimeout="8m">

<baseEntry baseDN="o=ldap" name="o=ldap"/></ldapRegistry>

<ldapRegistry id="LDAP2" realm="SampleLdapIDSRealm"host="ldapserver2.mycity.mycompany.com" port="1389" ignoreCase="true"baseDN="o=ibm,c=us" ldapType="IBM Tivoli Directory Server" searchTimeout="8m"></ldapRegistry>

For more information about the ldapRegistry elements, see “Liberty profile:Configuration elements in the server.xml file” on page 97.

Liberty profile: LDAP certificate map mode:

The certificate map mode is used to specify whether to map X.509 certificates intoan LDAP directory by EXACT_DN or CERTIFICATE_FILTER in the Liberty profile.

The EXTACT_DN means that the DN in the certificate must exactly match the userentry in the LDAP server, including case and spaces. To use the specified certificatefilter for the mapping, you can use the CERTIFICATE_FILTER.


Certificate filterSpecifies the filter certificate mapping property for the LDAP filter. Thefilter is used to map attributes in the client certificate to entries in theLDAP registry.

If more than one LDAP entry matches the filter specification at run time,authentication fails because the result is an ambiguous match. The syntaxor structure of this filter is:LDAP attribute=${Client certificateattribute}.

An example of a simple certificate filter is: uid=${SubjectCN}.

You can also specify multiple properties and values as part of thecertificate filter. The left side of the filter specification is an LDAP attributethat depends on the schema that your LDAP server is configured to use.The right side of the filter specification is one of the public attributes inyour client certificate. The right side must begin with a dollar sign ($) andopen bracket ({) and end with a close bracket (}). The case of the strings isimportant.

The following LDAP attributes (left side) are supported:v uid

v initials

v sAMAccountName

v displayName

v distinguishedName

v displayName

v description

The following client certificate attributes (right side) are supported:v ${SubjectCN}

v ${SubjectDN}

v ${IssuerCN}

v ${IssuerDN}

v ${SerialNumber}

An example of an LDAP configuration with certificate filter mode enabled:<ldapRegistry id="LDAP" realm="SampleLdapIDSRealm"

host="myldap.ibm.com" port="389" ignoreCase="true"baseDN="o=ibm,c=us"certificateMapMode="CERTIFICATE_FILTER"certificateFilter="uid=${SubjectCN}"userFilter="(&(uid=%v)(objectclass=ePerson))"groupFilter="(&(cn=%v)(|(objectclass=groupOfNames)

(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"userIdMap="*:uid"groupIdMap="*:cn"groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;

groupOfNames:member;groupOfUniqueNames:uniqueMember"ldapType="IBM Tivoli Directory Server" searchTimeout="8m" />

Liberty profile: Dynamic changes on securityThis topic describes some specific information on how dynamic configurationchanges impact security on the Liberty profile.


Dynamically changing the user registries

Changing the user registry can impact both the server configuration and clientsusing the server. When you change the user registry dynamically (withoutrestarting the server), the following must be considered:v If you change the user registry type or realm name, all web clients have to clear

their web single-sign on tokens.v If you change the user registry type or realm name, any values of accessId that

are specified in the authorization bindings must be updated. The accessId takesthe form of user:realmName/uniqueId or group:realmName/uniqueId. TherealmName in the accessId must match the realmName for the configuration userregistry.

Configuring the authentication cache on the Liberty profileThis topic describes how to modify the way that authenticated users are cached onthe Liberty profile.

About this task

Because the creation of a subject is relatively expensive, the Liberty profileprovides an authentication cache to store a subject after an authentication of a useris successful. The cache is initialized with a certain number of entries, determinedby the initialSize attribute, and has a maximum number of entries, determinedby the maxSize attribute. If the maximum size is reached, then the earliest entriesthat were used are removed from the cache. Also, if a user has been inactive formore than a certain time period as determined by the timeout attribute, then theentry for that user is removed from the cache. By default, the cache size isinitialized to 50 entries and a maximum of 25000 entries with a timeout of 600seconds.

You do not have to configure the values for the authCache element unless youwant to change the default values of the authentication cache.

See “Authentication cache” on page 31 for more detail.

Note:

v Any changes to the user registry configuration in server.xml file will clear theauthentication cache. However, if changes are done to an external user registrysuch as LDAP, the authentication cache is unaffected.

v You must consider the following effects of the timeout value on yourconfiguration:– Larger authentication cache timeout values can increase the security risk. For

example, you might revoke a user in the user registry or repository. However,the revoked user can log in using the credential that is cached in theauthentication cache until the cache is refreshed.

– Smaller authentication cache timeout values can affect performance. Whenthis value is smaller, the Liberty profile server accesses the user registry orrepository more frequently.

– Larger numbers of entries in the authentication cache, which is caused by anincreased number of users, increases the memory usage by the authenticationcache. Thus, the application server might slow down and affect performance.


Procedure1. Enable the appSecurity-2.0 Liberty feature in the server.xml file.

<featureManager><feature>appSecurity-2.0</feature>

</featureManager>

2. If you want to change the default options for the authentication cache, add theauthCache element to the server.xml file. In the following example, the initialsize of the authentication cache is changed to 100 entries with a maximum of50000 entries, and the timeout is changed to 15 minutes.<authCache initialSize="100" maxSize="50000" timeout="15m"/>

Note: If you want to disable the authentication cache, set the attributecachEnabled to false in the authentication element as follows:<authentication id="Basic" cacheEnabled="false" />

For more information about the authCache and authentication elements, see“Liberty profile: Configuration elements in the server.xml file” on page 97.

Configuring a JAAS custom login module for the Libertyprofile

You can configure a custom Java Authentication and Authorization Service (JAAS)login module before or after the Liberty profile server login module.

Before you begin

This topic assumes that you have a JAR file containing the JAAS custom loginmodule, which implements the javax.security.auth.spi.LoginModule interface. Thistopic also assumes that the JAAS custom login module uses hashtable, callbacks orshared state variables provided by the Liberty profile server to pass authenticationdata to the system login module.

About this task

You can use a custom login module to either make additional authenticationdecisions or add information to the Subject to make finer-grained authorizationdecisions inside your application. See “JAAS configuration” on page 31 and “JAASlogin modules” on page 32 for a more detailed overview.

Distributed operating systems You can also use the developer tools to configure acustom JAAS login module. See “Configuring JAAS on the Liberty profile by usingdeveloper tools” on page 466.

Avoid trouble: Distributed operating systems If you use the developer tools toconfigure the JAAS custom login module, refer to the sample JAAS configurationjaasConfig.xml file in the ${wlp.install.dir}/templates/config directory, andmake sure the configuration in your server.xml file is similar to the one in thesample file. See “Configuring JAAS on the Liberty profile by using developertools” on page 466.

See also “Developing JAAS custom login modules for a system loginconfiguration” on page 499.



2. Create a class com.ibm.ws.security.authentication.modules.CustomLoginModulethat implements the LoginModule interface and package it into theCustomLoginModule.jar file.

3. Create a library element that uses a fileset element indicating where theCustomLoginModule.jar file is. In this example, the library id is customLoginLib.

4. Create a jaasLoginModule element. In this example, the id is custom. Configurethe custom login module to require a successful authentication by setting thecontrolFlag attribute to REQUIRED. Set the libraryRef attribute tocustomLoginLib, the id of the library element configured in the previous step.This login module also has two options: UserRegistry is ldap and mapToUser isuser1.

5. Create a jaasLogincontextEntry element with an id and name of thesystem-defined JAAS configuration: system.WEB_INBOUND. You can also setthis JAAS configuration to system.DEFAULT, WSLogin, or your own JAASconfiguration. On the loginModuleRef attribute, add custom, the id of thejaasLoginModule element created in the previous step. Putting this id first inthe list means that it is the first JAAS login module to be called. You must alsolist the other default login modules: hashtable, userNameAndPassword,certificate, and token.See the following server.xml file as an example:<featureManager>

<feature>appSecurity-2.0</feature></featureManager>

<jaasLoginContextEntry id="system.WEB_INBOUND" name="system.WEB_INBOUND"loginModuleRef="custom, hashtable, userNameAndPassword, certificate, token" />

<jaasLoginModule id="custom"className="com.ibm.ws.security.authentication.modules.CustomLoginModule"controlFlag="REQUIRED" libraryRef="customLoginLib">

<options userRegistry="ldap" mapToUser="user1"/></jaasLoginModule>

<library id="customLoginLib"><fileset dir="${server.config.dir}" includes="CustomLoginModule.jar"/>

</library>...

Note: The option name cannot start with a period (.), config., or service.Also, the property name id or ID is not allowed.For more information about the jaasLoginContextEntry, jaasLoginModule,options, and library elements, see “Liberty profile: Configuration elements inthe server.xml file” on page 97.

Configuring JAAS on the Liberty profile by using developer tools


You can configure a JAAS configuration (system.WEB_INBOUND) with a customlogin module for the Liberty profile by editing the configuration. You do not haveto configure JAAS unless you want to customize it.

Before you begin


Avoid trouble: The developer tools creates the reference to a JAAS login moduleusing the loginModuleRef element. You must change it and use the loginModuleRef


attribute of jaasLoginContextEntry element. You can refer to the sample JAASconfiguration jaasConfig.xml file in the ${wlp.install.dir}/templates/configdirectory, and make sure the configuration in your server.xml file is similar to theone in the sample file.

Procedure1. Select JAAS Login Context Entry and click Add, then enter the login module

names.2. Select JAAS Login Module and configure your custom login module by

entering the Id and the Class name, then click the New button and select TopLevel to enter the Shared Library information.

3. Enter the ID for the shared Library in the pop-up panel and click OK.4. Configure Name and Description fields for the shared library, then click New

button and select Nested to add a Fileset reference as a nested element.5. Configure the Fileset Service Details by clicking Browse button in the Base

Directory field and select the directory where the JAR file is located. Then, clickBrowse button in the Includes pattern field to select your JAR file that containsyour custom login module implementation.

6. Optional: If your custom login module needs any options, you can right clickJAAS Login Module, select Add and then select login module options.

7. Save the configuration. You can find the following configuration saved in theserver.xml file.<jaasLoginContextEntry name="system.WEB_INBOUND" id="system.WEB_INBOUND">

<loginModuleRef>myCustom, hashtable, userNameAndPassword, certificate, token</loginModuleRef></jaasLoginContextEntry>

<jaasLoginModule className="com.ibm.ws.security.authentication.CustomLoginModule"id="myCustom" libraryRef="customLoginLib">

</jaasLoginModule>

<library id="customLoginLib" name="customLoginLib"description="Custom login module shared library">

<fileset dir="${server.config.dir}" includes="CustomLoginModule.jar"/></library>

8. Required: To make the configuration work, you must change thejaasLoginContextEntry element to include the loginModuleRef attribute. Youmust remove the loginModuleRef element and add it as an attribute of thejaasLoginContextEntry element.Here is an example of configuration using the loginModuleRef attribute.<jaasLoginContextEntry name="system.WEB_INBOUND" id="system.WEB_INBOUND"

loginModuleRef="myCustom, hashtable, userNameAndPassword, certificate, token" />

<jaasLoginModule className="com.ibm.ws.security.authentication.CustomLoginModule"id="myCustom" libraryRef="customLoginLib">

</jaasLoginModule>

<library id="customLoginLib" name="customLoginLib"description="Custom login module shared library">

<fileset dir="${server.config.dir}" includes="CustomLoginModule.jar"/></library>

Configuring LTPA on the Liberty profileThis topic describes how you can configure a Liberty profile server to use aspecific Lightweight Third Party Authentication (LTPA) keys file, user-definedpassword, and expiration time.

About this task

The LTPA is configured by default when security is enabled for a Liberty profileserver for the first time. The default location of the automatically generated LTPA


keys file is ${server.output.dir}/resources/security/ltpa.keys. The keys areencrypted with a randomly generated key and a default password of WebAS isinitially used to protect the keys. The password is required when importing thekeys into another server. Therefore, to protect the security of the LTPA keys, youmust change the password. When the keys are exchanged between the servers, thispassword must match across the servers for Single Sign On (SSO) to work.

The default expiration timeout is 120 minutes. The expiration value refers to howlong the LTPA tokens are valid before they expire.

To enable dynamic reload of the LTPA keys whencopying an LTPA keys file from another server, you can specify a file monitorinterval prior to copying the LTPA keys file. The monitor interval value refers tohow often the LTPA keys file is monitored for updates.

See LTPA concept in the Liberty profile.

Procedure1. Configure the ltpa element in the server.xml file as follows, replacing the

sample values in the example with your values.<ltpa keysFileName="yourLTPAKeysFileName.keys" keysPassword="keysPassword" expiration="120" />

2. Optional: Enable the LTPA keys file monitor bysetting the monitorInterval attribute which is the time interval on how often tocheck the lpta.keys file for key changes to be dynamically changed. Specify apositive integer followed by a unit of time, which can be hours (h), minutes(m), or seconds (s). For example,<ltpa keysFileName="yourLTPAKeysFileName.keys" keysPassword="keysPassword"

expiration="120" monitorInterval="5s" />

3. Encode the password within the configuration. You can get the encoded valueby using the securityUtility encode command.

4. Optional: Copy an existing LTPA keys file to thelocation specified in the keysFileName attribute. The default value is

${server.output.dir}/resources/security/ltpa.keys.

For more information on ltpa element, see “Liberty profile: Configurationelements in the server.xml file” on page 97.

Customizing SSO configuration using LTPA cookies for theLiberty profile

With single sign-on (SSO) configuration support, web users can authenticate oncewhen accessing Liberty profile resources such as HTML, JavaServer Pages (JSP)files, and servlets, or accessing resources in multiple Liberty profile servers thatshare the same Lightweight Third Party Authentication (LTPA) keys.

Example

When a user passes authentication on one of Liberty profile servers, authenticationinformation generated by the server is transported to the browser in a cookie. Thecookie is used to propagate the authentication information to other Liberty profileservers.


The LTPA is configured and ready for immediate use. The default cookie nameused to store the SSO token is called ltpaToken2. If you want to use a differentname for the cookie, you can customize the cookie name using the ssoCookieNameattribute of webAppSecurity element. If you customize the cookie name, make surethat all the servers that participate in SSO use the same cookie name.

See SSO concept in the Liberty profile.

The following example code sets the user to be logged out after the HTTP sessionexpires and the name of the SSO cookie as myCookieName.<webAppSecurity logoutOnHttpSessionExpire=”true” ssoCookieName=”myCookieName” />

Note: For SSO to work across servers, the Liberty profile servers must have thesame LTPA keys and shared the same user registry.

For details of all the available SSO settings, see the webAppSecurity element in“Liberty profile: Configuration elements in the server.xml file” on page 97.

Configuring RunAs authentication in the Liberty profileYou can delegate to another identity during authentication by configuring RunAsspecification for the Liberty profile.

About this task

By mapping a specified user identity and optionally password to a RunAs role,you can delegate the authentication process to a user with the RunAs role.

You must enable the appSecurity-2.0 and servlet-3.0 Libertyfeatures and have a user registry for your application to configure the RunAs role.

See also “RunAs() authentication” on page 37.

Procedure1. Enable the appSecurity-2.0 and servlet-3.0 Liberty features in the server.xml

file.2. Configure a user registry for your application.3. Specify the run-as element in the deployment descriptor of your application.

Here is an example of a web.xml that specifies subsequent calls be delegated tothe user mapped to the role of Employee:

<servlet id="Servlet_1"><servlet-name>RunAsServlet</servlet-name><display-name>RunAsServlet</display-name><description>RunAsServlet</description><servlet-class>web.RunAsServlet</servlet-class><run-as>

<role-name>Employee</role-name></run-as>

</servlet>

4. Map this role to a user. You can do this either in the ibm-application-bnd.xmi/xml or in the server.xml file. In the run-as element, you must specify a username. If you are using the ibm-application-bnd.xml file, the password is alsorequired; if you are using the server.xml file, the password is optional. If thepassword is present, it is recommended that the password is encoded. Forexample, encode the password using the securityUtility encode command inthe /bin directory of the Liberty profile.


Here is an example of using run-as element within the application-bndelement in the server.xml file, where the Employee role has been mapped tothe RunAs user of user5:


<user name="user1" /><user name="user5" /><run-as userid="user5" password="{xor}Lz4sLCgwLTs=" />


Note:

v Because the password is optional in the server.xml file, you can also use thefollowing code for a user without a password:


<user name="user1" /><user name="user5" /><run-as userid="user5" />


v If you specify the application-bnd element in the server.xml file, yourapplication must not be in the dropins folder. If you leave it in the dropinsfolder, then you must disable application monitoring by setting the followingin your server.xml file:<applicationMonitor dropinsEnabled="false" />

For more information about the run-as element, see “Liberty profile:Configuration elements in the server.xml file” on page 97.

Configuring TAI for the Liberty profileYou can configure the Liberty profile to integrate with a third-party security serviceusing Trust Association Interceptors (TAI). The TAI can be called before or aftersingle sign-on (SSO).

Before you begin

This topic assumes that you have already installed a third-party security server asa reverse proxy server. The third-party security server can act as a front-endauthentication server when the Liberty profile server applies its own authorizationpolicy onto the resulting credentials, which are passed by the proxy server.Meanwhile, you have a JAR file that contains the custom TAI class, whichimplements the com.ibm.wsspi.security.tai.TrustAssociationInterceptor interface.

Note: There is no support for monitoring changes of this JAR file.

About this task

A TAI is used to validate HTTP requests between a third-party security server anda Liberty profile server. It inspects the HTTP requests from the third-party securityserver to see if there are any security attributes. If the validation for a request issuccessful in the interceptor, the Liberty profile server authorizes the request bychecking whether the client user has the required permission to access theresources.

See also “Developing a custom TAI for the Liberty profile” on page 498 and“Customizing SSO configuration using LTPA cookies for the Liberty profile” onpage 468.


Distributed operating systems You can also use the developer tools to configure a TAIservice. See “Configuring TAI on the Liberty profile by using developer tools”

Procedure1. Enable the appSecurity-2.0 Liberty feature in the server.xml file.2. Deploy your applications to the Liberty profile server and enable all required

Liberty features, such asjsp-2.2, jdbc-4.0, and so on.3. Place the TAI implementation library simpleTAI.jar in your server directory.4. Update the server.xml file with the TAI configuration options and location of

the TAI implementation library.See the following server.xml file as an example:<featureManager>


<trustAssociation id="myTrustAssociation" invokeForUnprotectedURI="false"failOverToAppAuthType="false">

<interceptors id="simpleTAI" enabled="true"className="com.ibm.websphere.security.sample.SimpleTAI"invokeBeforeSSO="true" invokeAfterSSO="false" libraryRef="simpleTAI">

<properties hostName="machine1" application="test1"/>

</interceptors></trustAssociation>

<library id="simpleTAI"><fileset dir="${server.config.dir}" includes="simpleTAI.jar"/>

</library>...

The custom TAI is enabled in the example, but it does not performauthentication for unprotected URIs and does not allow to fallback toapplication authentication method if the TAI authentication fails. As shown inthe example, the following configuration elements are available for TAIsupport:v trustAssociation

v interceptors

v properties

Note: The property name cannot start with a period (.), config., or service.Also, the property name id or ID is not allowed.For more information about the trustAssociation, interceptors andproperties elements, see also “Liberty profile: Configuration elements in theserver.xml file” on page 97.

Configuring TAI on the Liberty profile by using developer tools


You can configure a TAI service for the Liberty profile using developer tools.

Before you begin



Avoid trouble: You can refer to the sample TAI configuration taiConfig.xml filein the ${wlp.install.dir}/templates/config directory, and make sure theconfiguration in your server.xml file is similar to the one in the sample file.

Procedure1. Select Trust Association Interceptor Service and enter an Id name.2. Select Trust Association Interceptor and configure the Id and the Class name

which is the fully qualified name of your TAI implementation class, then clickNew button and select Top Level to enter the Shared Library information.

3. Enter the ID for the shared Library in the pop-up panel and click OK.4. Configure the Name and Description fields for the shared library, then click

New button and select Nested to add a Fileset reference as a nested element.5. Configure the Fileset Service Details by clicking Browse button in the Base

Directory field and select the directory where the jar file is located. Then, clickBrowse button in the Includes pattern field to select your jar file that containsyour TAI implementation.

6. Configure Interceptor properties Details by clicking Add button to addproperties for the interceptor.

7. Save the configuration. You can find the following configuration saved in theserver.xml file.<trustAssociation id="myTrustAssociation" invokeForUnprotectedURI="false"

failOverToAppAuthType="false"><interceptors id="simpleTAI" enabled="true"

className="com.ibm.websphere.security.sample.SimpleTAI"invokeBeforeSSO="true" invokeAfterSSO="false" libraryRef="simpleTAI">

<properties hostName="machine1" application="test1"/></interceptors>

</trustAssociation>

<library id="simpleTAI"><fileset dir="${server.config.dir}" includes="simpleTAI.jar"/>

</library>

Authorizing access to resources in the Liberty profileThe purpose of authorization is to determine whether a user or group has thenecessary privileges to access a resource.

About this task

To learn about how authorization works in the Liberty profile, see “Liberty profile:Authorization” on page 40.

The following topics are covered in this section:

Procedure

Configure authorization for applications in a Liberty profile server

Configuring authorization for applications on the Libertyprofile

Configuring authorization for your application is to verify whether a user or groupbelongs to a specified role, and whether this role has the privilege to access aresource.


About this task

The Liberty profile server extracts user and group mapping information from auser registry, then checks the authorization configuration for the application todetermine whether a user or group is assigned to one of the required roles. Thenthe server reads the deployment descriptor of the application, to determinewhether the user or group has the privilege to access the resource.


For example:<featureManager>


2. Configure a user registry for authentication on the Liberty profile server.See “Authenticating users in the Liberty profile” on page 459.

3. Ensure that the deployment descriptor for your application includes securityconstraints and other security related information.

Note: You can also use a tool such as Rational Application Developer to createthe deployment descriptor.

4. Configure the authorization information such as the user and group to rolemapping.You can configure the authorization table in the following ways:v If you have an EAR file, you can add the authorization configuration

definition to the ibm-application-bnd.xml or ibm-application-bnd.xmi file.v If you have standalone WAR files, you can add the authorization table

definitions to the server.xml file under the respective application element.You can use the WebSphere Application Server Developer Tools for Eclipse todo this.

Notes:

v If you have an EAR file, the authorization configuration might already exist.In EAR files that are written to the current specification, this information isstored in an ibm-application-bnd.xml file; in older EAR files, thisinformation is stored in an ibm-application-bnd.xmi file.

v If your EAR file does not already contain an ibm-application-bnd.xm* file, itis not a straightforward task to create one and you might prefer to add theauthorization configuration to the server.xml file.

v If the authorization configuration for the EAR file is defined in anibm-application-bnd.xm* file and also in the server.xml file, then the twotables are merged. If there are any conflicts, the information from theserver.xml file is used.

v If you modify your user registry, be sure to review the authorization table fornecessary changes. For example, if you are specifying an access-id elementand change the realm name of the registry, you must also change the realmname in the access-id element.

v If you specify the application-bnd element in the server.xml file, yourapplication must not be in the dropins folder. If you leave it in the dropinsfolder, then you must disable application monitoring by setting the followingin your server.xml file:<applicationMonitor dropinsEnabled="false" />


A role can be mapped to a user, a group, or a special subject. The two types ofspecial subject are EVERYONE and ALL_AUTHENTICATED_USERS. When a role ismapped to the EVERYONE special subject, there is no security because everyone isallowed access and you are not prompted to enter credentials. When a role ismapped to the ALL_AUTHENTICATED_USERS special subject, then any user who hasbeen authenticated by the application server can access the protected resource.Here is example code for configuring the user and group to role mapping inthe server.xml file:<application type="war" id="myapp" name="myapp" location="${server.config.dir}/apps/myapp.war"><application-bnd><security-role name="user"><group name="students" /></security-role><security-role name="admin"><user name="gjones" />

<group name="administrators" /></security-role><security-role name="AllAuthenticated"><special-subject type="ALL_AUTHENTICATED_USERS" /></security-role></application-bnd></application>

In this example, the admin role is mapped to the user ID gjones and all users inthe group administrators. The AllAuthenticatedRole is mapped to the specialsubject ALL_AUTHENTICATED_USERS, meaning that any user has access as long asthey provide valid credentials for authentication.

OAuth

OAuth is an open standard for delegated authorization. The OAuth authorizationframework allows a user to grant a third-party application access to theirinformation stored with another HTTP service without sharing their accesspermissions or the full extent of their data.

In OAuth, the client, or third-party application, requests access to resourcescontrolled by the resource owner and hosted by the resource server, and is issued adifferent set of credentials than those of the resource owner. Instead of using thecredentials of the resource owner to access protected resources, the client obtainsan access token, which is a string denoting a specific scope, lifetime, and otheraccess attributes. Access tokens are issued to third-party clients by an authorizationserver with the approval of the resource owner. The client uses the access token toaccess the protected resources hosted by the resource server.

OAuth 2.0 is the latest OAuth protocol, and it is not compatible with an earlierversion with OAuth 1.0. OAuth 2.0 allows ease of use for client applicationdevelopers, while provides authorization flows for different types of clientapplications.

WebSphere Application Server supports OAuth 2.0, and plays a role as an OAuthservice provider endpoint and an OAuth protected resource enforcement endpoint.

The OAuth standard specifications supported include:v The OAuth 2.0 Authorization Frameworkv The OAuth 2.0 Authorization Framework: Bearer Token Usage


Summary of features inside WebSphere Application ServerOAuth 2.0 services

The following is a summary of features within WebSphere Application ServerOAuth 2.0 services.v WebSphere Application Server acts as an OAuth Service Provider (SP) to handle

OAuth 2.0 protocol requests.v WebSphere Application Server acts as protected resource enforcement endpoint

to authorize or deny requests for deployed web resources.v Allow multiple service providers to co-exist.v Allow administrator to revoke access tokens.v Allow client to revoke its authorization given by a user.v Optionally provide a Subject for a resource application to make an authenticated

downstream call or perform programmatic J2EE security.v Support 4 typical OAuth 2.0 flows as defined in the protocol.v Support persistent OAuth services.

OAuth 2.0 services

WebSphere Application Server OAuth services include both OAuth authorizationservice and web resource authorization decision service.

The OAuth 2.0 authorization service provides all OAuth 2.0 protocol endpointURLs, and is responsible for client authorization and token issuing.

The web resource authorization decision service is built into the Liberty profileweb authentication code. When a client accesses an OAuth protected web resource,the OAuth token is validated and mapped to a WebSphere Application Serverplatform security subject that the web request then runs under.

Defining an OAuth service provider:

An OAuth service provider is a named set of configuration options for OAuth. Theid or name of the provider is specified in the URL of inbound requests to theauthorization and token endpoints. The set of configuration options for thatprovider is used when the request is handled. This process allows one server withone endpoint servlet to effectively provide multiple OAuth configurations.

For example, the following URL is handled by using the set of OAuthconfiguration options that are defined for the OAuth provider named photoShare:https://my.company.com:8021/oauth2/endpoint/photoShare/authorize

The following URL is handled by using the set of OAuth configuration optionsthat are defined for the OAuth provider named calendarAuthz:https://my.company.com:8021/oauth2/endpoint/calendarAuthz/authorize

An OAuth service provider is defined with the oauthProvider element in theserver.xml file. You can define an OAuth service provider by editing theserver.xml file or by using the WebSphere Application Server Development Toolsfor Liberty Profile.


There are five basic server.xml configuration items you need for a minimal OAuthconfiguration:1. Add the oauth-2.0 and ssl-1.0 features.

OAuth is a secure protocol so SSL is required. On the Liberty profile, you mustsupply a keystore password for SSL by using the keyStore element. There is nodefault keystore password.

2. Set up the role mapping for the OAuth web application by using theoauthRoles element.OAuth is an HTTP-based protocol and a web application is supplied to handlethe authorization and token endpoints. The web application is built in and isstarted automatically when you specify the oauth-2.0 feature. However, youmust map the authenticated role to one or more users, groups, or specialsubjects. Another role, clientManager, is supplied for managing clientconfiguration, but it is not necessary to map that role for OAuth authorizationto function.

3. Define one or more providers with the oauthProvider element.The provider must have at least one client defined. Clients can be definedlocally with the localStore and client elements. Clients can also be defined ina relational database with the databaseStore element.

4. Define a user registry, either an LDAP registry or a basic registry.5. Set the allowFailOverToBasicAuth web application security property to true.

The following example is a sample server.xml file that defines a simple OAuthprovider with one client:<server>

<featureManager><feature>oauth-2.0</feature><feature>ssl-1.0</feature>

</featureManager>

<keyStore password="keyspass" />

<oauthRoles><authenticated><user>testuser</user>

</authenticated></oauthRoles>

<oauthProvider id="SampleProvider" filter="request-url%=ssodemo"><localStore><client name="client01" secret="{xor}LDo8LTor"

displayname="Test client number 1"redirect="http://localhost:1234/oauthclient/redirect.jsp"enabled="true" />

</localStore></oauthProvider>

<webAppSecurity allowFailOverToBasicAuth="true" />

<basicRegistry id="basic" realm="BasicRealm"><user name="testuser" password="testuserpwd" />

</basicRegistry>

</server>

OAuth full profile provider configuration equivalents:

The following tables map the Liberty profile server.xml file elements andattributes to the equivalent full profile provider parameters in the providerconfiguration file.


The following table illustrates the Liberty profile attributes and the equivalent fullprofile parameters for the oauthProvider element.

Table 21. Liberty profile oauthProvider element

Liberty profile attribute name Full profile equivalent parameter

authorizationGrantLifetime oauth20.max.authorization.grant.lifetime.seconds

authorizationCodeLifetime oauth20.code.lifetime.seconds

authorizationCodeLength oauth20.code.length

accessTokenLifetime oauth20.token.lifetime.seconds

accessTokenLength oauth20.access.token.length

issueRefreshToken oauth20.issue.refresh.token

refreshTokenLength oauth20.refresh.token.length

mediatorClassname oauth20.mediator.classnames

allowPublicClients oauth20.allow.public.clients

grantType oauth20.grant.types.allowed

authorizationFormTemplate oauth20.authorization.form.template

authorizationErrorTemplate oauth20.authorization.error.template

customLoginURL oauth20.authorization.loginURL

autoAuthorizeParam oauth20.autoauthorize.param

autoAuthorizeClient oauth20.autoauthorize.clients

clientURISubstitutions oauth20.client.uri.substitutions

filter Filter

oauthOnly oauthOnly

includeTokenInSubject includeToken

characterEncoding characterEncoding

clientTokenCacheSize oauth20.token.userClientTokenLimit

The following table illustrates the Liberty profile attributes and the equivalent fullprofile parameters for the databaseStore element.

Table 22. Liberty profile databaseStore element

Liberty profile attribute name Full profile equivalent parameter

cleanupExpiredTokenInterval oauthjdbc.CleanupInterval

Configuring auto consent:Before you begin

This task assumes that you have enabled the OAuth 2.0 feature and configured anOAuth service provider.

About this task

You can authorize an OAuth client without the approval of the resource owner byenabling the auto authorization feature of the WebSphere Application ServerOAuth service provider.


Procedure

Configure auto consent with the autoAuthorizeParam attribute and theautoAuthorizeClient subelement of the oauthProvider element in the server.xmlfile:<oauthProvider id="OAuthConfigSample" autoAuthorizeParam="autoauthz" ...>

...<autoAuthorizeClient>client01</autoAuthorizeClient><autoAuthorizeClient>client02</autoAuthorizeClient>

</oauthProvider>

Results

The client01 and client02 OAuth clients are now configured for autoauthorization.

OAuth endpoint URLs:

After OAuth 2.0 is enabled, several endpoint URLs are configured on theWebSphere Application Server so that OAuth clients can communicate with theOAuth service provider before accessing OAuth protected resources.

The following endpoint URLs are configured for the OAuth service provider:1. Authorization endpoint URL

https://<host_name>:<port_number>/oauth2/endpoint/<provider_name>/authorize

wherev host_name is the host name of the OAuth service provider.v port_number is the secure port number that is configured on the WebSphere

Application Server.v provider_name is the OAuth provider name.

2. Token endpoint URLhttps://<host_name>:<port_number>/oauth2/endpoint/<provider_name>/token



3. Authorization endpoint URL of trust association interceptor (TAI) based userauthenticationhttps://<host_name>:<port_number>/oauth2/declaritiveEndpoint/<provider_name>/authorize



By using this authorization endpoint, the applicable user authenticationincludes TAI.

Invoking OAuth 2.0 service


A registered OAuth client can invoke the WebSphere Application Server OAuthservice authorization endpoint to request an authorization code. A registeredOAuth client can also invoke the WebSphere Application Server OAuth servicetoken endpoint to request an access token. The client then can use the access tokento request protected web resources from WebSphere Application Server.

WebSphere Application Server OAuth 2.0 service supports all four flows.

Authorization code flow

Invoke authorization endpoint to request authorization code.

The OAuth client redirects the resource owner or user to the WebSphereApplication Server OAuth 2.0 Authorization Service by adding its client id, clientsecret, state, redirect URI, and the optional scopes.https://<host_name>:<port_number>/oauth2/endpoint/<provider_name>/authorize

orhttps://<host_name>:<port_number>/oauth2/declarativeEndpoint/<provider_name>/authorize

Invoke OAuth token endpoint to request access token.

The OAuth client requests an access token from the WebSphere Application ServerOAuth 2.0 token endpoint by adding authorization_code grant type,authorization code, redirect_url, and client_id as request parameters.https://<host_name>:<port_number>/oauth2/endpoint/<provider_name>/token

The following example shows the constructions of the URIs when usingauthorization code, and the use of the access token to access web resources:

String charset = "UTF-8";String param1 = "code";

if (isAuthorizationCode){String query = String.format("response_type=%s&

client_id=%s&client_secret=%s&state=%s&redirect_uri=%s&scope=%s",URLEncoder.encode(param1, charset),URLEncoder.encode(clientId, charset),URLEncoder.encode(clientSecret, charset),URLEncoder.encode(state, charset),URLEncoder.encode(redirectURI, charset),URLEncoder.encode(scope, charset));

String s = authorizationEndPoint + "?" + query;System.out.println("Visit: " + s + "\nand grant permission");System.out.print("Now enter the OAuth code you have received in redirect uri :");BufferedReader br = new BufferedReader(new InputStreamReader(System.in));String code = br.readLine();param1 = "authorization_code";query = String.format("grant_type=%s&

code=%s&client_id=%s&client_secret=%s&state=%s&redirect_uri=%s&scope=%s",URLEncoder.encode(param1, charset),URLEncoder.encode(code, charset),URLEncoder.encode(clientId, charset),URLEncoder.encode(clientSecret, charset),URLEncoder.encode(state, charset),URLEncoder.encode(redirectURI, charset),URLEncoder.encode(scope, charset));

URL url = new URL(tokenEndPoint);


HttpsURLConnection con = (HttpsURLConnection)url. openConnection();con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded;charset=" + charset);con.setDoOutput(true);con.setRequestMethod("POST");OutputStream output = null;try {

output = con.getOutputStream();output.write(query.getBytes(charset));output.flush();

} finally {if (output != null) try {

output.close();} catch (IOException logOrIgnore) {}

}con.connect();System.out.println("response message is = " + con.getResponseMessage());// read the output from the serverBufferedReader reader = null;StringBuilder stringBuilder;reader = new BufferedReader(new InputStreamReader(con.getInputStream()));stringBuilder = new StringBuilder();String line = null;try {

while ((line = reader.readLine()) != null) {stringBuilder.append(line + "\n");

}} finally {

if (reader != null) try {reader.close();

} catch (IOException logOrIgnore) {}}String tokenResponse = stringBuilder.toString();System.out.println ("response is = " + tokenResponse);JSONObject json = JSONObject.parse(tokenResponse);if (json.containsKey("access_token")) {

accessToken = (String)json.get("access_token");this.accessToken = accessToken;

}if (json.containsKey("refresh_token")) {

refreshToken = (String)json.get("refresh_token");}//sendRequestForAccessToken(query);if (accessToken != null) {

String query = String.format("access_token=%s",URLEncoder.encode(accessToken, charset));

URL urlResource = new URL(resourceEndPoint);HttpsURLConnection conn = (HttpsURLConnection) urlResource.openConnection();conn.setRequestMethod("POST");conn.setRequestProperty("Content-type", "application/x-www-form-urlencoded");conn.setDoOutput(true);output = null;try {

output = conn.getOutputStream();output.write(query.getBytes(charset));output.flush();

} finally {if (output != null) try {

output.close();} catch (IOException logOrIgnore) {}

}conn.connect();System.out.println("response to the resource request is = " + conn.getResponseMessage ());reader = null;if(conn.getResponseCode()>=200 && conn.getResponseCode() < 400) {

reader = new BufferedReader(new InputStreamReader(conn.getInputStream()));stringBuilder = new StringBuilder();String line = null;try {

while ((line = reader.readLine()) != null) {stringBuilder.append(line + "\n");

}} finally {

if (reader != null) try {reader.close();

} catch (IOException logOrIgnore) {}}System.out.println ("response message to the request resource is = " + stringBuilder.toString());

} else {


isValidResponse = false;}

}}

Implicit grant flow

The OAuth client requests an access token from the WebSphere Application ServerOAuth 2.0 authorization endpoint by adding token response_type, redirect_url,client_id, scope, and state as request parameters.https://<host_name>:<port_number>/oauth2/endpoint/<provider_name>/authorize

orhttps://<host_name>:<port_number>/oauth2/declarativeEndpoint/<provider_name>/authorize

The following example shows the construction of the URI when using implicitgrant:if (isImplicit) {param1 = "token";String query = String.format("response_type=%s&

client_id=%s&state=%s&redirect_uri=%s&scope=%s",URLEncoder.encode(param1, charset),URLEncoder.encode(clientId, charset),URLEncoder.encode(state, charset),URLEncoder.encode(redirectURI, charset),URLEncoder.encode(scope, charset));

String s = authorizationEndPoint + "?" + query;System.out.println("Visit: " + s + "\nand grant permission");System.out.print("Now enter the access token you have received in redirect uri :");BufferedReader br = new BufferedReader(new InputStreamReader(System.in));accessToken = br.readLine();if (accessToken != null) {// send Resource Request using the access token

}}

Client credential flow

The OAuth client accesses the token endpoint with the client ID and secret, andexchanges for an access token for future resource requests. In this flow, the clientaccesses the token endpoint by adding client_credentials grant type, client_id,and client_secret as request parameters.https://<host_name>:<port_number>/oauth2/endpoint/<provider_name>/token

The following example shows the construction of the URI when using clientcredential:if (isClientCredentials){param1 = "client_credentials";String query = String.format("grant_type=%s&

scope=%s&client_id=%s&client_secret=%s",URLEncoder.encode(param1, charset),URLEncoder.encode(scope, charset),URLEncoder.encode(clientId, charset),URLEncoder.encode(clientSecret, charset));

accessToken = sendRequestForAccessToken(query);if (accessToken != null) {//send Resource Request using (accessToken);

}}


Resource owner password flow

The Resource Owner Password Credentials flow passes the user ID and passwordof the resource owner to the token endpoint directly. In this flow, The OAuth clientaccesses the token endpoint by adding password grant type, client_id,client_secret, username, password, scope, and state as request parameters.https://<host_name>:<port_number>/oauth2/endpoint/<provider_name>/token

The following example shows the construction of the URI when using resourceowner password:if (isResourceOwnerCredentials) {param1 = "password";String query = String.format("grant_type=%s&

username=%s&password=%s&scope=%s&client_id=%s&client_secret=%s",URLEncoder.encode(param1, charset),URLEncoder.encode(resOwnerName, charset),URLEncoder.encode(resOwnerPassword, charset),URLEncoder.encode(scope, charset),URLEncoder.encode(clientId, charset),URLEncoder.encode(clientSecret, charset));

accessToken = sendRequestForAccessToken(query);if (accessToken != null) {//send Resource Request using (accessToken);

}}

If the access token is expired, then the refresh token can be sent to get a validaccess token. The following example shows how to send a refresh token:if(isAccessToken) {if (this.accessToken != null) {if (!sendResourceRequest(this.accessToken)) {// resource request failed...//get refresh tokenparam1 = "refresh_token";String query = String.format("grant_type=%s&

client_id=%s&client_secret=%s&refresh_token=%s&scope=%s",URLEncoder.encode(param1, charset),URLEncoder.encode(clientId, charset),URLEncoder.encode(clientSecret, charset),URLEncoder.encode(this.refreshToken, charset),URLEncoder.encode(scope, charset));

accessToken = sendRequestForAccessToken(query);if (accessToken != null) {sendResourceRequest(accessToken);

}}

}}

Customizing an OAuth provider

The WebSphere Application Server OAuth service provider has plug-in points forcustomization. You can replace the default form login page for user authentication,or develop your own user consent form to collect client authorization data.WebSphere Application Server OAuth providers also allow customized postprocessing for major events in OAuth token issuing by using mediators.

Custom mediator:


An OAuth 2.0 mediator is used as a callback during the OAuth 2.0 messageprocessing to perform customized post processing.

Write an OAuth20 mediator

To write a mediator, you must implement the interface namedcom.ibm.oauth.core.api.oauth20.mediator.OAuth20Mediator You can implementone or more mediate* methods to perform custom post processing.void init(OAuthComponentConfiguration config)

This method is called by a factory when an instance of this object is created.void mediateAuthorize(AttributeList attributeList)

This method is called by the core component after basic message validation andprocessing to allow any post custom processing by the component consumer in theprocessAuthorization method.void mediateAuthorizeException(AttributeList attributeList, OAuthException exception)

This method is called by the core component when the protocol exception happensto allow any post custom processing by the component consumer in theprocessAuthorization method.void mediateResource(AttributeList attributeList)

This method is called by the core component after basic message validation andprocessing to allow any post custom processing by the component consumer in theprocessResourceRequest method.void mediateResourceException(AttributeList attributeList, OAuthException exception)

This method is called by the core component when protocol exception happens toallow any post custom processing by the component consumer in theprocessResourceRequest method.void mediateToken(AttributeList attributeList)

This method is called by the core component after basic message validation andprocessing to allow any post custom processing by the component consumer in theprocessTokenRequest method.void mediateTokenException(AttributeList attributeList, OAuthException exception)

This method is called by the core component when protocol exception happens toallow any post custom processing by the component consumer in theprocessTokenRequest method.

Enable OAuth20 mediator for an OAuth provider

To add a customized mediator to a specific OAuth20 service provider, update theprovider definition in the server.xml file. Add the mediatorClassname attribute ofthe oauthProvider element and specify the class name for the mediator. You canalso specify multiple class names for mediators by using the mediatorClassnamesubelement of the oauthProvider element. If multiple mediators are specified, thosemediators are started in the order they are specified. You must also define alibrary element that contains the mediator class and refer to the library with thelibraryRef attribute.

The following example shows a sample custom mediator entry in the providerdefinition in the server.xml file:


<oauthProvider id="OAuthConfigSample" libraryRef="myLib"mediatorClassname="com.ibm.ws.security.oauth20.mediator.ResourceOwnerValidationMediator" ...>...

</oauthProvider>

<library id="myLib"><fileset dir="C:\mydir" includes="myLib.jar" />

</library>

The following code sample implements the credential validation by using theWebSphere Application Server user registry in the resource owner passwordcredentials flow.package com.ibm.ws.security.oauth20.mediator;

import com.ibm.oauth.core.api.attributes.AttributeList;import com.ibm.oauth.core.api.config.OAuthComponentConfiguration;import com.ibm.oauth.core.api.error.OAuthException;import com.ibm.oauth.core.api.error.oauth20.OAuth20MediatorException;import com.ibm.oauth.core.api.oauth20.mediator.OAuth20Mediator;import com.ibm.oauth.core.internal.oauth20.OAuth20Constants;import com.ibm.websphere.security.CustomRegistryException;import com.ibm.websphere.security.PasswordCheckFailedException;import com.ibm.websphere.security.UserRegistry;

import java.rmi.RemoteException;import java.util.logging.Level;import java.util.logging.Logger;

import javax.naming.InitialContext;import javax.naming.NamingException;

public class ResourceOwnerValidationMedidator implements OAuth20Mediator {private static final String CLASS = ResourceOwnerValidationMedidator.class.getName();private static final Logger LOG = Logger.getLogger(CLASS);private UserRegistry reg = null;

public void init(OAuthComponentConfiguration config) {try {InitialContext ctx = new InitialContext();reg = (UserRegistry) ctx.lookup("UserRegistry");

} catch(NamingException ne) {LOG.log(Level.SEVERE, "Cannot lookup UserRegistry", ne);

}}

public void mediateAuthorize(AttributeList attributeList)throws OAuth20MediatorException {// nothing to do here

}

public void mediateAuthorizeException(AttributeList attributeList,OAuthException exception)

throws OAuth20MediatorException {// nothing to do here

}

public void mediateResource(AttributeList attributeList)throws OAuth20MediatorException {// nothing to do here

}

public void mediateResourceException(AttributeList attributeList,OAuthException exception)

throws OAuth20MediatorException {// nothing to do here

}

public void mediateToken(AttributeList attributeList)throws OAuth20MediatorException {final String methodName = "mediateToken";LOG.entering(CLASS, methodName, attributeList);if("password".equals(attributeList.getAttributeValueByName("grant_type"))) {String username = attributeList.getAttributeValueByName("username");String password = attributeList.getAttributeValueByName("password");try {reg.checkPassword(username, password);

} catch (PasswordCheckFailedException e) {throw new OAuth20MediatorException("User doesn’t exist or the


password doesn’t match.", e);} catch (CustomRegistryException e) {throw new OAuth20MediatorException("Cannot validate resource owner.", e);

} catch (RemoteException e) {throw new OAuth20MediatorException("Cannot validate resource owner.", e);

}}LOG.exiting(CLASS, methodName);

}

public void mediateTokenException(AttributeList attributeList,OAuthException exception)

throws OAuth20MediatorException {final String methodName = "mediateTokenException";LOG.entering(CLASS, methodName, new Object[] {attributeList, exception});if("password".equals(attributeList.getAttributeValueByName("grant_type"))) {// clear sensitive dataattributeList.setAttribute("access_token",

OAuth20Constants.ATTRTYPE_RESPONSE_ATTRIBUTE,new String[0]);

attributeList.setAttribute("refresh_token",OAuth20Constants.ATTRTYPE_RESPONSE_ATTRIBUTE,new String[0]);

}LOG.exiting(CLASS, methodName);

}

}

Custom consent form template:

The OAuth authorization server provides a template to acquire user consentinformation about which OAuth clients are authorized to access the protectedresource in given scopes. The authorization request from the OAuth client shows alist of requested scopes in the template.

WebSphere Application Server allows the consent form template to be either astatic HTML page or a dynamic web page. In both cases, the template must beprovided as an unprotected web resource. The form retriever in WebSphereApplication Server integration does not perform any authentication when accessingthis template URL.

The WebSphere Application Server OAuth provider includes a simple sampleconsent form, and allows customization by using oauthFormData variable.

To customize the consent form, you must edit the oauthFormData variable by usingJavascript. The following variables are included in the form data:v authorizationUrl - the authorization URL where the form is being submittedv clientDisplayName - the display name of the clientv nonce - random generated number to prevent cross-site request forgery (CSRF)v client_id - see the OAuth 2.0 specificationv response_type - see the OAuth 2.0 specificationv redirect_uri - see the OAuth 2.0 specificationv state - see the OAuth 2.0 specificationv scope - see the OAuth 2.0 specification

The developer of a form template is responsible for rendering the template withwhat is in the oauthFormData variable with Javascript. The developer mustinterpret the scope value to be a meaningful value to a user. When a userauthorizes the request, the developer can call the submitForm(oauthFormData)method to perform the authorization The submitForm method is provided by


default. However, if developers are familiar with OAuth2 protocol, they canimplement their own function to submit the OAuth authorization request.

If globalization is wanted, you can use a dynamic page that returns globalizedcontent according to the Accept-Language header in the request. When retrievingthe template, the Accept-Language header is forwarded as well, and the templatedeveloper must decide which content to return regarding the preferred language.

Note: The clientDisplayName variable is not escaped in HTML. The templatedeveloper must sanitize the value, as the value is input by a user during clientregistration.

To use a custom consent form template page for a specific OAuth20 serviceprovider, you must update the service provider definition in the server.xml file. Inthe provider configuration, you must use the authorizationFormTemplate attributeof the oauthProvider element and add the template URL as the value. Thefollowing example shows a sample template entry in the provider configuration:<oauthProvider id="OAuthConfigSample"authorizationFormTemplate="https://acme.com:9043/oath20/template.html...>

The following example illustrates a sample consent form:<oauthProvider id="OAuthConfigSample"

authorizationLoginURL="https://acme.com:9043/oath20/login.jsp"...>

function escapeHTML(str) {var ele = document.createElement("div");ele.innerText = ele.textContent = str;return ele.innerHTML;

}<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"><html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OAuth authorization form</title><script language="javascript">function init() {var scope = oauthFormData.scope;var scopeEle = document.getElementById("oauth_scope");var ul = document.createElement("ul");if(scope) {for(var i=0; i< scope.length; i++) {var n = document.createElement("li");n.innerHTML = scope[i];ul.appendChild(n);

}}scopeEle.appendChild(ul);// set client namevar clientEle = document.getElementById("client_name");clientEle.innerHTML = escapeHTML(oauthFormData.clientDisplayName);

}

function escapeHTML(str) {var ele = document.createElement("div");ele.innerText = ele.textContent = str;return ele.innerHTML;

}</script></head><body onload="init()">

<div>Do you want to allow client<span id=client_name style="font-weight:bold">xxxxxxx</span> to access your data?</div>

<div id="oauth_scope"></div><div>

<input type="button" value="Yes" onclick="javascript:submitForm(oauthFormData);"/>


<input type="button" value="No, Thanks"/></div>

</body></html>

Custom user login form:

The WebSphere Application Server OAuth service provider includes a form loginpage for a user to submit a user name and password.

You can customize your own form login page, but it must be implemented asrequired in the form-based authentication in the servlet specification. In this form,the action must be j_security_check, and use the j_username input field to get theuser name. The action must also use the j_password input field to get the userpassword. The custom form login page must be provided as an unprotected webresource.

To use the custom form login page for a specific OAuth20 service provider, youmust update the service provider definition in the server.xml file. In the providerconfiguration, you must add the customLoginURL attribute and specify the loginpage URL as the value.

The following is an example custom login page entry in the provider definition:<oauthProvider id="OAuthConfigSample"customLoginURL="https://acme.com:9043/oath20/login.jsp"...>

SQL statements for persistent OAuth service

WebSphere Application Server supports persistent OAuth 2.0 service by persistingOAuth tokens and clients in a database. With persistent OAuth 2.0 services, anauthorized client can access OAuth 2.0 service after OAuth services are restarted.

To configure persistent OAuth 2.0 services, you must follow the following steps:1. Configure the OAuth 2.0 service provider.

To use a database store, you must specify the databaseStore subelement of theoauthProvider element. The only required attribute on the databaseStoreelement is dataSourceRef, whose value must be the id of the dataSource.The following example is a sample server.xml file for an OAuth provider thatuses a Derby database store:<server>

<featureManager><feature>oauth-2.0</feature><feature>ssl-1.0</feature><feature>jdbc-4.0</feature><feature>jndi-1.0</feature>

</featureManager>




<oauthProvider id="OAuthConfigDerby" filter="request-url%=ssodemo"oauthOnly="false">

<databaseStore dataSourceRef="OAuthFvtDataSource" /></oauthProvider>


<jdbcDriver id="DerbyEmbedded" libraryRef="DerbyLib" />

<library id="DerbyLib" fileSetRef="DerbyFileset" />

<fileset id="DerbyFileset" dir="${DERBY_JDBC_DRIVER_PATH}"includes="derby.jar" />

<dataSource id="OAuthFvtDataSource" jndiName="jdbc/OAuth2DB"jdbcDriverRef="DerbyEmbedded">

<properties.derby.embedded databaseName="D:\oauth2db"createDatabase="create" />

</dataSource>



</basicRegistry>

</server>

2. Set up a database and table to store the OAuth token and client.a. Create a database for persistent OAuth service. See the vendor

documentation for database creation. In this topic, we assume the databasename that you created for OAuth is D:\oauth2db.

b. Create two OAuth tables as defined by the following SQL statements:----- CREATE TABLES -----CREATE TABLE OAuthDBSchema.OAUTH20CACHE(LOOKUPKEY VARCHAR(256) NOT NULL,UNIQUEID VARCHAR(128) NOT NULL,COMPONENTID VARCHAR(256) NOT NULL,TYPE VARCHAR(64) NOT NULL,SUBTYPE VARCHAR(64),CREATEDAT BIGINT,LIFETIME INT,EXPIRES BIGINT,TOKENSTRING VARCHAR(2048) NOT NULL,CLIENTID VARCHAR(64) NOT NULL,USERNAME VARCHAR(64) NOT NULL,SCOPE VARCHAR(512) NOT NULL,REDIRECTURI VARCHAR(2048),STATEID VARCHAR(64) NOT NULL

);

CREATE TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG(COMPONENTID VARCHAR(256) NOT NULL,CLIENTID VARCHAR(256) NOT NULL,CLIENTSECRET VARCHAR(256),DISPLAYNAME VARCHAR(256) NOT NULL,REDIRECTURI VARCHAR(2048),ENABLED INT

);

----- ADD CONSTRAINTS -----ALTER TABLE OAuthDBSchema.OAUTH20CACHEADD CONSTRAINT PK_LOOKUPKEY PRIMARY KEY (LOOKUPKEY);

ALTER TABLE OAuthDBSchema.OAUTH20CLIENTCONFIGADD CONSTRAINT PK_COMPIDCLIENTID PRIMARY KEY (COMPONENTID,CLIENTID);

----- CREATE INDEXES -----CREATE INDEX OAUTH20CACHE_EXPIRES ON OAUTHDBSCHEMA.OAUTH20CACHE (EXPIRES ASC);

3. Configure WebSphere Application Server.Configure the WebSphere Application Server data source. You must set the datasource Java Naming and Directory Interface (JNDI) name to be jdbc/OAuth2DB.The JNDI name must match the jndiName attribute of the dataSource element inthe server.xml file. Choose a database name to match what you created in thefirst step, for example, D:\oauth2db.The configuration of DB2 or Derby for OAuth persistent services are included.You can use them as a sample template to configure other databases.

4. Add the registered OAuth clients to the database.


To persist a client in a database, you must save the client to the database. Thefollowing SQL statements add the dbclient01 and dbclient02 OAuth clients toa Derby database:CONNECT ’jdbc:derby:D:\oauth2db’;INSERT INTO OAuthDBSchema.OAUTH20CLIENTCONFIG VALUES(’OAuthConfigDerby’,’dbclient01’,’secret’,’dbclient01’,’http://localhost:9080/oauthclient/redirect.jsp’,1

),(’OAuthConfigDerby’,’dbclient02’,’secret’,’dbclient02’,’http://localhost:9080/oauthclient/redirect.jsp’,1

);DISCONNECT CURRENT;

Using Derby database for persistent OAuth service:

Derby database can be used for persistent OAuth services. For convenience andreference purposes, this topic documents the steps you need to configure Derbydatabase, either remote or local to the OAuth service, for OAuth persistent service.

Follow these steps:1. Create a database and tables.

Edit and run the following SQL statement to create an OAuth database andtable:--- Change oauth2db to the name you want for the database--- Connect to Derby, choose one connection option by uncomment--- if connecting to Derby as network server--- CONNECT ’jdbc:derby://localhost:1527/oauth2db;create=true’;

--- if connecting to embedded derby, you can change D:\oauth2db to location of database--- CONNECT ’jdbc:derby:D:\oauth2db;create=true’;

--- if creating tables in existing Derby database, remove the create=true parameter.

----- CREATE TABLES -----CREATE TABLE OAuthDBSchema.OAUTH20CACHE (LOOKUPKEY VARCHAR(256) NOT NULL,UNIQUEID VARCHAR(128) NOT NULL,COMPONENTID VARCHAR(256) NOT NULL,TYPE VARCHAR(64) NOT NULL,SUBTYPE VARCHAR(64),CREATEDAT BIGINT,LIFETIME INT,EXPIRES BIGINT,TOKENSTRING VARCHAR(2048) NOT NULL,CLIENTID VARCHAR(64) NOT NULL,USERNAME VARCHAR(64) NOT NULL,SCOPE VARCHAR(512) NOT NULL,REDIRECTURI VARCHAR(2048),STATEID VARCHAR(64) NOT NULL

);

CREATE TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG (COMPONENTID VARCHAR(256) NOT NULL,CLIENTID VARCHAR(256) NOT NULL,CLIENTSECRET VARCHAR(256),DISPLAYNAME VARCHAR(256) NOT NULL,REDIRECTURI VARCHAR(2048),ENABLED INT

);

----- ADD CONSTRAINTS -----ALTER TABLE OAuthDBSchema.OAUTH20CACHEADD CONSTRAINT PK_LOOKUPKEY PRIMARY KEY (LOOKUPKEY);



----- CREATE INDEXES -----CREATE INDEX OAUTH20CACHE_EXPIRES ON OAUTHDBSCHEMA.OAUTH20CACHE (EXPIRES ASC);

DISCONNECT CURRENT;

Run the createTables.sql file by starting ij with the following command:ij createTables.sql

2. Configure the WebSphere Application Server Liberty Profile server.The following example is a sample server.xml file for an OAuth provider thatuses a Derby database store:<server>

<featureManager><feature>oauth-2.0</feature><feature>ssl-1.0</feature><feature>jdbc-4.0</feature><feature>jndi-1.0</feature>

</featureManager>




<oauthProvider id="OAuthConfigDerby" filter="request-url%=ssodemo"oauthOnly="false">

<databaseStore dataSourceRef="OAuthDerbyDataSource" /></oauthProvider>

<jdbcDriver id="DerbyEmbedded" libraryRef="DerbyLib" />

<library id="DerbyLib" filesetRef="DerbyFileset" />

<fileset id="DerbyFileset" dir="${DERBY_JDBC_DRIVER_PATH}"includes="derby.jar" />

<dataSource id="OAuthDerbyDataSource" jndiName="jdbc/OAuth2DB"jdbcDriverRef="DerbyEmbedded">

<properties.derby.embedded databaseName="D:\oauth2db"createDatabase="create" />

</dataSource>



</basicRegistry></server>

Using IBM DB2 for persistent OAuth service:

IBM DB2 can be used for persistent OAuth services. For convenience and referencepurposes, this topic documents the steps you need to configure DB2 for OAuthpersistent service.

Follow these steps:1. Create a database and tables.

Edit and run the following SQL statement to create an OAuth database andtable:-- Change oauth2db to the name you want for the database

CREATE DATABASE oauth2db USING CODESET UTF8 TERRITORY US;CONNECT TO oauth2db;

---- CREATE TABLES ----CREATE TABLE OAuthDBSchema.OAUTH20CACHE


(LOOKUPKEY VARCHAR(256) NOT NULL,UNIQUEID VARCHAR(128) NOT NULL,COMPONENTID VARCHAR(256) NOT NULL,TYPE VARCHAR(64) NOT NULL,SUBTYPE VARCHAR(64),CREATEDAT BIGINT,LIFETIME INT,EXPIRES BIGINT,TOKENSTRING VARCHAR(2048) NOT NULL,CLIENTID VARCHAR(64) NOT NULL,USERNAME VARCHAR(64) NOT NULL,SCOPE VARCHAR(512) NOT NULL,REDIRECTURI VARCHAR(2048),STATEID VARCHAR(64) NOT NULL

);

CREATE TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG(COMPONENTID VARCHAR(256) NOT NULL,CLIENTID VARCHAR(256) NOT NULL,CLIENTSECRET VARCHAR(256),DISPLAYNAME VARCHAR(256) NOT NULL,REDIRECTURI VARCHAR(2048),ENABLED INT

);

---- ADD CONSTRAINTS ----ALTER TABLE OAuthDBSchema.OAUTH20CACHEADD CONSTRAINT PK_LOOKUPKEY PRIMARY KEY (LOOKUPKEY);


---- CREATE INDEXES ----CREATE INDEX OAUTH20CACHE_EXPIRES ON OAUTHDBSCHEMA.OAUTH20CACHE (EXPIRES ASC);

---- GRANT PRIVILEGES -------- UNCOMMENT THE FOLLOWING IF YOU USE AN ACCOUNT OTHER THAN ADMINISTRATOR FOR DB ACCESS ----

-- Change dbuser to the account you want to use to access your database-- GRANT ALL ON OAuthDBSchema.OAUTH20CACHE TO USER dbuser;-- GRANT ALL ON OAuthDBSchema.OAUTH20CLIENTCONFIG TO USER dbuser;

---- END OF GRANT PRIVILIGES ----

DISCONNECT CURRENT;

The default DB2 listening port is 50000. If you want to find it, run thefollowing command and find the value of the SVCENAME parameter. If it is anumber, then it is the port number. If it is a name, look for the name in the/etc/services file or the Windows equivalent if you are using Windows.Linux/Unix: db2 get dbm cfg | grep SVCENAMEWindows: db2 get dbm cfg | findstr SVCENAME

You can create a database and tables in DB2 by running the followingstatement:db2 -tvf createTables.sql

2. Configure the WebSphere Application Server Liberty Profile server.The following example is a sample server.xml file for an OAuth provider thatuses a DB2 store:<server><featureManager><feature>oauth-2.0</feature><feature>ssl-1.0</feature><feature>jdbc-4.0</feature><feature>jndi-1.0</feature>

</featureManager>





<oauthProvider id="DBOAuth20Provider" oauthOnly="true"filter="request-url%=AnnuityOAuthWeb/index.jsp">

<databaseStore dataSourceRef="OAUTH2DBDS" /></oauthProvider>

<jdbcDriver id="db2Universal" libraryRef="DB2JCC4LIB" />

<library apiTypeVisibility="spec,ibm-api,third-party" filesetRef="db2jcc4"id="DB2JCC4LIB" />

<fileset dir="${shared.resource.dir}/db2" id="db2jcc4"includes="db2jcc4.jar db2jcc_license_cu.jar" />

<dataStore id="OAUTH2DBDS" jdbcDriverRef="db2Universal"jndiName="jdbc/oauthProvider">

<properties.db2.jcc databaseName="OAUTH2DB" driverType="4"user="bob" password="abcdefg="portNumber="50000"serverName="db2.server.mycompany.com" />

</dataStore>



</basicRegistry></server

The following example adds a client to DB2:INSERT INTO OAuthDBSchema.OAUTH20CLIENTCONFIG(COMPONENTID,CLIENTID,CLIENTSECRET,DISPLAYNAME,REDIRECTURI,ENABLED

)VALUES(’1’,’key’,’secret’,’My Client’,’https://localhost:9443/oauth/redirect.jsp’,1

)

Configuring secure JMX connection to the Liberty profileYou can access the secured Java Management Extensions (JMX) connectors on theLiberty profile by using SSL. The secured JMX connection is enabled by the Libertyprofile feature restConnector-1.0.

About this task

The REST connector is enabled through the Liberty feature restConnector-1.0.Remote access through the REST connector is protected by a single administratorrole. In addition, SSL is required to keep the communication confidential. TherestConnector-1.0 feature already includes the ssl-1.0 feature.


The following section describes how to configure and access the REST connectoron the Liberty profile.

Procedure1. Enable the REST connector using the following code in the server.xml file.



</featureManager>

2. Configure SSL certificates in the server.xml file.3. Configure a user or group to the administrator role in the server.xml file.

v Map to the administrator role for the Liberty profile4. Access the REST connector from a JMX client application or by using the

jConsole tool provided in the Java SDK. Use -J flags to pass the systemproperties as Java options and set the class path to include the connector classfiles. The connector class files are packed in the clients/restConnector.jarfile.v Use the following properties for SSL certificates:

-J-Djavax.net.ssl.trustStore=<location of your client trust store>-J-Djavax.net.ssl.trustStorePassword=<password for the trust store>-J-Djavax.net.ssl.trustStoreType=<type of trust store>

The following example shows the jConsole tool being used with SSLconfigurations:jconsole -J-Djava.class.path=%JAVA_HOME%/lib/jconsole.jar;

%JAVA_HOME%/lib/tools.jar;%WLP_HOME%/clients/restConnector.jar

-J-Djavax.net.ssl.trustStore=key.jks-J-Djavax.net.ssl.trustStorePassword=Liberty-J-Djavax.net.ssl.trustStoreType=jks

After the jConsole starts, select Remote Process, and enter the JMX serviceURL: service:jmx:rest://<host>:<port>/IBMJMXConnectorREST. The portnumber is the HTTPS port. You must also provide the user name andpassword.

Note:

You can specify some JMX REST connection options as system properties. See“Liberty profile: JMX REST connector settings” on page 390.

Configuring web security related properties for the Liberty profileYou can configure web security related properties for the Liberty profile, such asSSO and client certificate authentication.

About this task

You can use the webAppSecurity element to configure web container applicationsecurity for the Liberty profile. Make sure you add the appSecurity-2.0,servlet-3.0 and other required Liberty features to the server.xml file of theLiberty profile.

For all available attributes in the webAppSecurity element , see “Liberty profile:Configuration elements in the server.xml file” on page 97.

You can choose to complete one or more of the following tasks according to yourrequirements.

Procedurev “Customizing SSO configuration using LTPA cookies for the Liberty profile” on

page 468v “Configuring your web application and server for client certificate

authentication” on page 457


Customizing SSO configuration using LTPA cookies for theLiberty profile

With single sign-on (SSO) configuration support, web users can authenticate oncewhen accessing Liberty profile resources such as HTML, JavaServer Pages (JSP)files, and servlets, or accessing resources in multiple Liberty profile servers thatshare the same Lightweight Third Party Authentication (LTPA) keys.

Example

When a user passes authentication on one of Liberty profile servers, authenticationinformation generated by the server is transported to the browser in a cookie. Thecookie is used to propagate the authentication information to other Liberty profileservers.

The LTPA is configured and ready for immediate use. The default cookie nameused to store the SSO token is called ltpaToken2. If you want to use a differentname for the cookie, you can customize the cookie name using the ssoCookieNameattribute of webAppSecurity element. If you customize the cookie name, make surethat all the servers that participate in SSO use the same cookie name.

See SSO concept in the Liberty profile.

The following example code sets the user to be logged out after the HTTP sessionexpires and the name of the SSO cookie as myCookieName.<webAppSecurity logoutOnHttpSessionExpire=”true” ssoCookieName=”myCookieName” />

Note: For SSO to work across servers, the Liberty profile servers must have thesame LTPA keys and shared the same user registry.

For details of all the available SSO settings, see the webAppSecurity element in“Liberty profile: Configuration elements in the server.xml file” on page 97.

Configuring your web application and server for clientcertificate authentication

You can configure your web application on the Liberty profile using SSL clientauthentication.

Before you begin

This topic assumes that you have already created the SSL certificates, for exampleas described in “Creating SSL certificates from the command prompt” on page 455.

About this task

Client certificate authentication occurs if the server-side requests that the client-sidesend a certificate. A WebSphere server can be configured for client certificateauthentication on the SSL configuration. To do this, you add the ssl-1.0 Libertyfeature to the server.xml file, along with code that tells the server the keystoreinformation for authentication.

For details of which aspects of SSL are supported, see “Liberty features” on page14.


Procedure1. Ensure that the deployment descriptor for your web application specifies client

certificate authentication as the authentication method to use.Check that the deployment descriptor includes the following element:<auth-method>CLIENT-CERT</auth-method>

Note: You can use a tool such as Rational Application Developer to create thedeployment descriptor.

2. Optional: Generate an SSL certificate using the command prompt. See “Libertyprofile: securityUtility command” on page 456.

3. Configure your server to enable SSL client authentication by adding thefollowing lines to the server.xml file:


<featureManager>

<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore"trustStoreRef="defaultTrustStore" clientAuthenticationSupported="true" />

<keyStore id="defaultKeyStore" location="key.jks" type="JKS" password="defaultPWD" /><keyStore id="defaultTrustStore" location="trust.jks" type="JKS" password="defaultPWD" />

v If you specify clientAuthentication="true", the server requests that a clientsends a certificate. However, if the client does not have a certificate, or thecertificate is not trusted by the server, the handshake does not succeed.

v If you specify clientAuthenticationSupported="true", the server requeststhat a client sends a certificate. However, if the client does not have acertificate, or the certificate is not trusted by the server, the handshake mightstill succeed.

v If you do not specify either clientAuthentication orclientAuthenticationSupported, or you specifyclientAuthentication="false" or clientAuthenticationSupported="false",the server does not request that a client send a certificate during thehandshake.

4. Add a client certificate to your browser. See the documentation of your browserfor adding client certificates.

5. Make sure the server trusts any client certificates that are used.6. Make sure any client certificates used for client authentication are mapped to a

user identity in your registry.v For the basic registry, the user identity is the common name (CN) from the

distinguished name (DN) of the certificate.v For a Lightweight Directory Access Protocol (LDAP) registry, the DN from

the client certificate must be in the LDAP registry.7. To use basic authentication, user ID and password only, if client certificate

authentication does not succeed, add the following line to your server.xml file.<webAppSecurity allowFailOverToBasicAuth="true" />

Note: If you specify allowFailOverToBasicAuth="false" or do not specifyallowFailOvertoBasicAuth, and the client certificate authentication does notsucceed, the request generates a 403 Authentication error message, and theclient is not prompted for basic authentication.

Configuring authentication aliases for the Liberty profileYou can configure an authentication data alias to use with a resource reference forauthentication on the Liberty profile.


About this task

You can use an authentication data alias by defining a user and password forauthentication in the Liberty profile. To do this, add the jdbc-4.0 Liberty feature tothe server.xml file and add at least one authData element.

Note: There is no authentication alias principal mapping module support.

Procedure1. Add the jdbc-4.0 Liberty features in the server.xml file.

<featureManager><feature>jdbc-4.0</feature>

</featureManager>

2. Configure the authData element in the server.xml file as follows. You must usea unique name for the assigned id attribute value.

<authData id="auth1" user="dbuser1" password="dbuser1pwd"/>

3. Configure the IBM deployment descriptor, for example, the ibm-web-bnd.xmlfile, of your application by using the authentication-alias element in theresource reference. The name attribute value must match the id attribute definedin the server.xml file.

<resource-ref name="jdbc/mydbresource" binding-name="jdbc/mydbresource"><authentication-alias name="auth1"/>

</resource-ref>

Setting up a Liberty profile to run in SP800-131

You can set up a Liberty profile to meet the SP800-131 requirement that isoriginated by the National Institute of Standards and Technology (NIST).

About this task

SP800-131 requires longer key lengths and stronger cryptography. The specificationalso provides a transition configuration to enable users to move to a strictenforcement of SP800-131. The transition configuration also enables users to runwith a mixture of settings from both FIPS140-2 and SP800-131. SP800-131 can berun in two modes, transition and strict. The transition mode is offered to give usera setting to move their environment to SP800-131 strict mode. In transition mode, itis optional to use the SP800-131 required certificates and to set the protocol toSP800-131

Strict enforcement of SP800-131 requirements on the Liberty profile includes thefollowing:v The use of the TLSv1.2 protocol for the Secure Sockets Layer (SSL) context.v Certificates must have a minimum length of 2048. Elliptical Curve (EC)

certificate require a minimum size of 244-bit curves.v �Certificates must be signed with a signature algorithm of SHA256, SHA384, or

SHA512. Valid signatureAlgorithms include:– SHA256withRSA– SHA384withRSA– SHA512withRSA– SHA256withECDSA– SHA384withECDSA


– SHA512withECDSAv SP800-131 approved Cipher suites.

Note: To configure a Liberty profile server to run in SP800-131 mode, users mustbe running with a level of the IBM JDK that supports SP800-131. The minimallevels of the IBM JDK include Java 6 sr 10, Java 6.0.1 sr 2, or Java 7.

For more information about the SP800-131 standard, see the National Institute ofStandards and Technology.

You can configure the Liberty profile to run in SP800-131 strict mode or transitionmode as following:

Procedurev Configure the Liberty Profile to run in SP800-131 strict mode.

1. Make sure that you are running on a level of the IBM JDK that supportsSP800-131.

2. Make sure that certificates of your server meet the criteria for SP800-131.– Certificates have a minimum length of 2048 and Ellipical Curve (EC)

certificates have a minimum size of 244-bit curve.– Certificates are signed with at least SHA256 or signed with one of the

signature algorithms listed above.3. Configure your SSL Configuration to use the TLSv1.2 protocol. See “Enabling

SSL communication for the Liberty profile” on page 449and “Liberty profile:SSL configuration attributes” on page 450 for more details.

4. The Java Secure Socket Extension (JSSE) is enabled to run in SP800-131 strictmode by setting the system property com.ibm.jsse2.sp800-131 to strict. Forexample, com.ibm.jsse2.sp800-131=strict. See “Customizing the Libertyprofile environment” on page 352 for how to set system properties in thejvm.options file.

v Configure the Liberty Profile to run in SP800-131 transition mode.1. Make sure that you are running a level of the IBM JDK that support

SP800-131.2. The JSSE is enabled to run in SP800-131 transition mode by setting the

system property com.ibm.jsse2.sp800-131 to transition. For example,com.ibm.jsse2.sp800-131=transition. See “Customizing the Liberty profileenvironment” on page 352 for how to set system properties in thejvm.options file.

Note: If you change your protocol to use TLSv1.2, make sure that your browsersupports TLSv1.2.

Developing extensions to the Liberty profile security infrastructureThe Liberty profile server provides various plug points so that you can extend thesecurity infrastructure.

About this task

The following topics are covered in this section:


http://csrc.nist.gov/publications/PubsFIPS.html

http://csrc.nist.gov/publications/PubsFIPS.html

Procedurev Follow the instructions in “Developing a custom TAI for the Liberty profile” to

develop custom trust association interceptors (TAI) to extend the securityinfrastructure of Liberty profile server.

v Follow the instructions in “Developing JAAS custom login modules for asystem login configuration” on page 499 to develop JAAS custom login modulesto extend the security infrastructure of Liberty profile server.

Developing a custom TAI for the Liberty profileYou can develop a custom trust association interceptor (TAI) class by implementingthe com.ibm.wsspi.security.tai.TrustAssociationInterceptor interface provided in theLiberty profile server.

About this task

The trust association interface is a service provider API that enables the integrationof third party security services with a Liberty profile server. When processing theweb request, the Liberty profile server calls out and passes the HttpServletRequestand HttpServletResponse to the trust association interceptors. TheHttpServletRequest calls the isTargetInterceptor method of the interceptor to seewhether the interceptor can process the request. After an appropriate trustassociation interceptor is selected, the HttpServletRequest is processed by thenegotiateValidateandEstablishTrust method of the interceptor, and the result isreturned in a TAIResult object. You can add your own logic code to each methodof the custom TAI class.

See also the Java API document for the TAI interface. The Java API documentationfor each Liberty profile API is available in a separate JAR file under the/dev/ibm-api/javadoc directory of the server image.

Avoid trouble: Distributed operating systems If you use the developer tools toconfigure the TAI, refer to the sample TAI configuration taiConfig.xml file in the${wlp.install.dir}/templates/config directory, and make sure the configurationin your server.xml file is similar to the one in the sample file. See “ConfiguringTAI on the Liberty profile by using developer tools” on page 471.

Example

Here is a sample TAI class called SimpleTAI, which also lists all available methodsfrom the TrustAssociationInterceptor interface.package com.ibm.websphere.security.sample;

import java.util.Properties;

import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpServletResponse;

import com.ibm.websphere.security.WebTrustAssociationException;import com.ibm.websphere.security.WebTrustAssociationFailedException;import com.ibm.wsspi.security.tai.TAIResult;import com.ibm.wsspi.security.tai.TrustAssociationInterceptor;

public class SimpleTAI implements TrustAssociationInterceptor {public SimpleTAI() {

super();}

/** @see com.ibm.wsspi.security.tai.TrustAssociationInterceptor#isTargetInterceptor* (javax.servlet.http.HttpServletRequest)


*/public boolean isTargetInterceptor(HttpServletRequest req)

throws WebTrustAssociationException {//Add logic to determine whether to intercept this requestreturn true;

}

/** @see com.ibm.wsspi.security.tai.TrustAssociationInterceptor#negotiateValidateandEstablishTrust* (javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse)*/public TAIResult negotiateValidateandEstablishTrust(HttpServletRequest req,

HttpServletResponse resp) throws WebTrustAssociationFailedException {// Add logic to authenticate a request and return a TAI result.String tai_user = "taiUser";return TAIResult.create(HttpServletResponse.SC_OK, tai_user);

}

/** @see com.ibm.wsspi.security.tai.TrustAssociationInterceptor#initialize(java.util.Properties)*/

public int initialize(Properties arg0)throws WebTrustAssociationFailedException {

return 0;}

/** @see com.ibm.wsspi.security.tai.TrustAssociationInterceptor#getVersion()*/

public String getVersion() {return "1.0";

}

/** @see com.ibm.wsspi.security.tai.TrustAssociationInterceptor#getType()*/

public String getType() {return this.getClass().getName();

}

/** @see com.ibm.wsspi.security.tai.TrustAssociationInterceptor#cleanup()*/

public void cleanup()

{}}

What to do next

Put the custom TAI class in a jar file, for example simpleTAI.jar, then make the jarfile available to the Liberty profile server. See “Configuring TAI for the Libertyprofile” on page 470.

Developing JAAS custom login modules for a system loginconfiguration

For a Liberty profile server, multiple Java Authentication and Authorization Service(JAAS) plug-in points exist for configuring system logins. The Liberty profile usessystem login configurations to authenticate incoming requests. You can develop acustom JAAS login module to add information to the Subject of a system loginconfiguration.

About this task

Application login configurations are called by servlet applications for obtaining aSubject that is based on specific authentication information. When you write alogin module that plugs into a Liberty profile application login or system loginconfiguration, you must develop login configuration logic that knows when


specific information is present, and how to use the information. See “JAASconfiguration” on page 31 and “JAAS login modules” on page 32 for more details.

To develop a JAAS custom login module for a system login configuration, followthe steps in the procedure:

Procedurev Understand usable callbacks and how they work.

See Programmatic login for JAAS for more information about usable callbacks.

Note: The Liberty profile only supports the following callbacks:callbacks[0] = new javax.security.auth.callback.NameCallback("Username: ");callbacks[1] = new javax.security.auth.callback.PasswordCallback("Password: ", false);callbacks[2] = new com.ibm.websphere.security.auth.callback.WSCredTokenCallbackImpl("Credential Token: ");callbacks[3] = new com.ibm.websphere.security.auth.callback.WSServletRequestCallback("HttpServletRequest: ")callbacks[4] = new com.ibm.websphere.security.auth.callback.WSServletResponseCallback("HttpServletResponse: ");callbacks[5] = new com.ibm.websphere.security.auth.callback.WSAppContextCallback("ApplicationContextCallback: ");callbacks[6] = new WSRealmNameCallbackImpl("Realm Name: ", default_realm);callbacks[7] = new WSX509CertificateChainCallback("X509Certificate[]: ");callbacks[8] = wsAuthMechOidCallback = new WSAuthMechOidCallbackImpl("AuthMechOid: ");

v Understand shared state variables and how they work.If you want to access the objects that the WebSphere Application Server fullprofile creates during a login, refer to the following shared state variables. Formore information about these variables, see the “System ProgrammingInterfaces” subtopic of Programming Interfaces

com.ibm.wsspi.security.auth.callback.Constants.WSPRINCIPAL_KEYSpecifies an implemented object of the java.security.Principal interface.This shared state variable is for read-only purposes. Do not set thisvariable in the shared state for custom login modules. The default loginmodule sets this variable.

com.ibm.wsspi.security.auth.callback.Constants.WSCREDENTIAL_KEYSpecifies the com.ibm.websphere.security.cred.WSCredential object. Thisshared state variable is for read-only purposes. Do not set this variablein the shared state for custom login modules. The default login modulewill set this variable.

com.ibm.wsspi.security.auth.callback.Constants.WSSSOTOKEN_KEYSpecifies the com.ibm.wsspi.security.token.SingleSignonToken object. Donot set this variable in the shared state for custom login modules. Thedefault login module sets this variable.

v Optional: Understand hashtables for custom JAAS login modules in the Libertyprofile. See “Hash table login module” on page 38 for more details.

v Develop a sample custom login module using callbacks and shared state.You can use the following sample to learn on how to use some of the callbacksand shared state variables.

public class CustomCallbackLoginModule implements LoginModule {

protected Map<String, ?> _sharedState;protected Subject _subject = null;protected CallbackHandler _callbackHandler;private final String customPrivateCredential = "CustomLoginModuleCredential";

/*** Initialization of login module*/

public void initialize(Subject subject, CallbackHandler callbackHandler,Map<String, ?> sharedState, Map<String, ?> options) {

_sharedState = sharedState;_subject = subject;_callbackHandler = callbackHandler;


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tsec_jaascustlogmod

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=welc_ref_adm_pi

}

public boolean login() throws LoginException {try {

AccessController.doPrivileged(new PrivilegedExceptionAction<Object>() {public Object run() throws Exception {

_subject.getPrivateCredentials().add(customPrivateCredential);return null;

}

});} catch (PrivilegedActionException e) {

throw new LoginException(e.getLocalizedMessage());}

String username = null;char passwordChar[] = null;byte[] credToken = null;HttpServletRequest request = null;HttpServletResponse response = null;Map appContext = null;String realm = null;String authMechOid = null;java.security.cert.X509Certificate[] certChain = null;

NameCallback nameCallback = null;PasswordCallback passwordCallback = null;WSCredTokenCallbackImpl wsCredTokenCallback = null;WSServletRequestCallback wsServletRequestCallback = null;WSServletResponseCallback wsServletResponseCallback = null;WSAppContextCallback wsAppContextCallback = null;WSRealmNameCallbackImpl wsRealmNameCallback = null;WSX509CertificateChainCallback wsX509CertificateCallback = null;WSAuthMechOidCallbackImpl wsAuthMechOidCallback = null;

Callback[] callbacks = new Callback[9];callbacks[0] = nameCallback = new NameCallback("Username: ");callbacks[1] = passwordCallback = new PasswordCallback("Password: ", false);callbacks[2] = wsCredTokenCallback = new WSCredTokenCallbackImpl("Credential Token: ");callbacks[3] = wsServletRequestCallback = new WSServletRequestCallback("HttpServletRequest: ");callbacks[4] = wsServletResponseCallback = new WSServletResponseCallback("HttpServletResponse: ");callbacks[5] = wsAppContextCallback = new WSAppContextCallback("ApplicationContextCallback: ");callbacks[6] = wsRealmNameCallback = new WSRealmNameCallbackImpl("Realm name:");callbacks[7] = wsX509CertificateCallback = new WSX509CertificateChainCallback("X509Certificate[]: ");callbacks[8] = wsAuthMechOidCallback = new WSAuthMechOidCallbackImpl("AuthMechOid: ");

try {_callbackHandler.handle(callbacks);

} catch (Exception e) {// handle exception

}

if (nameCallback != null)username = nameCallback.getName();

if (passwordCallback != null)passwordChar = passwordCallback.getPassword();

if (wsCredTokenCallback != null)credToken = wsCredTokenCallback.getCredToken();

if (wsServletRequestCallback != null)request = wsServletRequestCallback.getHttpServletRequest();

if (wsServletResponseCallback != null)response = wsServletResponseCallback.getHttpServletResponse();

if (wsAppContextCallback != null)appContext = wsAppContextCallback.getContext();

if (wsRealmNameCallback != null)realm = wsRealmNameCallback.getRealmName();

if (wsX509CertificateCallback != null)certChain = wsX509CertificateCallback.getX509CertificateChain();

if (wsAuthMechOidCallback != null)authMechOid = wsAuthMechOidCallback.getAuthMechOid();


_subject.getPrivateCredentials().add("username = " + username);_subject.getPrivateCredentials().add("password = " + String.valueOf(passwordChar));_subject.getPrivateCredentials().add("realm = " + realm);_subject.getPrivateCredentials().add("authMechOid = " + authMechOid.toString());

return true;}

public boolean commit() throws LoginException {return true;

}

public boolean abort() {return true;

}

public boolean logout() {return true;

}

}

v Optional: Develop a sample custom login module using hashtable login.You can use the following sample to learn on how to use hashtable login.

package com.ibm.websphere.security.sample;

import java.util.Map;

import javax.security.auth.Subject;import javax.security.auth.callback.CallbackHandler;import javax.security.auth.login.LoginException;import javax.security.auth.spi.LoginModule;

import com.ibm.wsspi.security.token.AttributeNameConstants;

/*** Custom login module that adds another PublicCredential to the subject*/

@SuppressWarnings("unchecked")public class CustomHashtableLoginModule implements LoginModule {

protected Map<String, ?> _sharedState;protected Map<String, ?> _options;

/*** Initialization of login module*/public void initialize(

Subject subject, CallbackHandler callbackHandler, Map<String, ?> sharedState, Map<String, ?> options) {_sharedState = sharedState;_options = options;

}

public boolean login() throws LoginException {try {

java.util.Hashtable<String, Object> customProperties = (java.util.Hashtable<String, Object>)_sharedState.get(AttributeNameConstants.WSCREDENTIAL_PROPERTIES_KEY);

if (customProperties == null) {customProperties = new java.util.Hashtable<String, Object>();

}

customProperties.put(AttributeNameConstants.WSCREDENTIAL_USERID, "userId");// Sample of creating custom cache keycustomProperties.put(AttributeNameConstants.WSCREDENTIAL_CACHE_KEY, "customCacheKey");

/** Sample for creating user ID and security name* customProperties.put(AttributeNameConstants.WSCREDENTIAL_UNIQUEID, "userId");* customProperties.put(AttributeNameConstants.WSCREDENTIAL_SECURITYNAME, "securityName");* customProperties.put(AttributeNameConstants.WSCREDENTIAL_REALM, "realm");* customProperties.put(AttributeNameConstants.WSCREDENTIAL_GROUPS, "groupList");*/

/** Sample for creating user ID and password* customProperties.put(AttributeNameConstants.WSCREDENTIAL_USERID, "userId");* customProperties.put(AttributeNameConstants.WSCREDENTIAL_PASSWORD, "password");*/

Map<String, java.util.Hashtable> mySharedState = (Map<String, java.util.Hashtable>) _sharedState;


mySharedState.put(AttributeNameConstants.WSCREDENTIAL_PROPERTIES_KEY, customProperties);} catch (Exception e) {

throw new LoginException("LoginException: " + e.getMessage());}

return true;}

public boolean commit() throws LoginException {return true;

}

public boolean abort() {return true;

}

public boolean logout() {return true;

}}

What to do next

Add your custom login module into the WEB_INBOUND, and DEFAULT JavaAuthentication and Authorization Service (JAAS) system login configurations ofthe server.xml file. Put the custom login module class in a JAR file, for example,customLoginModule.jar, then make the JAR file available to the Liberty profileserver. See “Configuring a JAAS custom login module for the Liberty profile” onpage 465.

Customizing an application login to perform an identityassertion using JAAS

Using the Java Authentication and Authorization Service (JAAS) login framework,you can create a JAAS login configuration that can be used to perform login to anidentity assertion on the Liberty profile.

About this task

By configuring identity assertion with trust validation, an application can use theJAAS login configuration to perform a programmatic identity assertion. SeeIdentityAssertionLoginModule for more detail.

Avoid trouble: Distributed operating systems If you use the developer tools toconfigure the JAAS custom login module, refer to the sample JAAS configurationjaasConfig.xml file in the ${wlp.install.dir}/templates/config directory, andmake sure the configuration in your server.xml file is similar to the one in thesample file. See “Configuring JAAS on the Liberty profile by using developertools” on page 466.

To customize the application login to perform an identity assertion with trustvalidation, follow these steps:

Procedure1. Delegate trust validation to a user implemented plug point.

Trust validation is accomplished by a custom login module. This custom loginmodule performs any trust validation required, then sets the trust and identityinformation in the shared state to be passed on to the identity assertion loginmodule. A map is required in the following shared state key:com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.state


If the state is missing then a WSLoginFailedException is reported by theIdentityAssertionLoginModule.The map in the shared state key must include a trust key with the followingkey name:com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.trust

If this key is set to true, then trust is established. If the key is set to false, thenno trust is established and the IdentityAssertionLoginModule creates aWSLoginFailedException.The map in the shared state key must also set one of the following resources:v An identity key. A java.security.Principal can be set in the following key:

com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.principal

v A java.security.cert.X509Certificate[]. This certificate can be set in thefollowing key:com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certficates

If both a principal and certificate are supplied, then the principal is used and awarning is reported.

2. Create a JAAS configuration for application logins. The JAAS configuration willcontain the user implemented trust validation custom login module and theIdentityAssertionLoginModule. Then to configure an application loginconfiguration, add the following code in the server.xml file:<jaasLoginContextEntry id="CustomIdentityAssertion" name="CustomIdentityAssertion"

loginModuleRef="customIdentityAssertion,identityAssertion" /><jaasLoginModule id="customIdentityAssertion"

className="com.ibm.ws.security.authentication.IdentityAssertionLoginModule"controlFlag="REQUIRED" libraryRef="customLoginLib"/>

<library id="customLoginLib"><fileset dir="${server.config.dir}" includes="IdentityAssertionLoginModule.jar"/>

</library>

This JAAS configuration is then used by the application to perform an IdentityAssertion.

3. Perform the programmable identity assertion. A program can now use theJAAS login configuration to perform a programmatic identity assertion. Theapplication program can create a login context for the JAAS configurationcreated in step 2, then login to that login context with the identity they wouldassert to. If the login is successful then that identity can be set in the currentrunning process. Here is an example of how such code would operate:NameCallback handler = new NameCallback(new MyPrincipal("Joe"));LoginContext lc = new LoginContext("customIdentityAssertion", handler);lc.login(); //assume successfulSubject s = lc.getSubject();WSSubject.setRunAsSubject(s);// From here on , the runas identity is "Joe"

Note: The MyPrincipal class is the implementation of java.security.Principalinterface in the example.

Results

Using the JAAS login framework and two user implemented login modules, youcan create a JAAS login configuration that can be used to perform login to anidentity assertion.

Developing a custom user registry for the Liberty profile


You can develop a custom user registry class by implementing thecom.ibm.websphere.security.UserRegistry interface provided in the Liberty profileserver.

About this task

The UserRegistry interface is a Service Programming Interface (SPI) that enablessupport to virtually any type of account repository. For a general view ofstand-alone custom registries, read the Stand-alone custom registries topic.

Procedure1. Implement the custom user registry. Read the Developing the UserRegistry

interface for using custom registries topic for more information.2. Convert the implementation class into an OSGi service. There are following

ways of doing that:v Convert your UserRegistry class into a Declarative Service (DS) component.v Write a new UserRegistry class that is a DS component and delegate it to

your UserRegistry class.v Register your UserRegistry class directly in the Service Registry (SR) using

the OSGi core APIs.3. Package the custom user registry as an OSGi bundle and export the

UserRegistry service.4. Create a feature manifest to include the OSGi bundle. Read the “Liberty profile:

Product extension” on page 22 topic for more information.5. Configure the server.xml file with the feature name after the feature is

installed into the user product extension location. For example:<featureManager>

...<feature>usr:customRegistrySample-1.0</feature>

</featureManager>

Securing web services

Security is a major quality of service (QoS) requirement for QoS enabled webservices. There are different approaches for providing security for web services.Two of them include transport layer security and message level security.

Securing web services at the transport layer

Transport-level security is based on a Secure Sockets Layer (SSL) or TransportLayer Security (TLS) and is used to protect HTTP message contents point to point.

Securing web services at the message level

Message-level security protects the SOAP contents that are contained within anHTTP message for a web service.

Securing web services at the message level


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=cseccustomauth

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tsec_users

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=tsec_users

Web services message level security (Web services security or WS-Security) is asecurity quality of service (QoS) for web services applications. Web servicessecurity standards and profiles describe how to provide security and protection forSOAP messages that are exchanged in a web services environment.

Web services security is provided as a Liberty feature. The Webservices security run time that is provided in the Liberty profile is based on theApache CXF open source services framework. The Web services security feature inLiberty is limited by the features and function of the Apache CXF framework. Webservices security must be explicitly enabled by enabling the wssecurity-1.0feature.

Web services security is configured by using the WS-SecurityPolicy inside theWSDL file of a web service application.

Web services security specifications and standards

The following OASIS standards are supported in the Liberty profile:v Web Services Security SOAP Message Security 1.1: https://www.oasis-open.org/

committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdfv Web Services Security Username Token Profile 1.1: http://docs.oasis-open.org/

wss/v1.1/wss-v1.1-spec-os-UsernameTokenProfile.pdfv Web Services Security X.509 Certificate Token Profile 1.1: http://docs.oasis-

open.org/wss/v1.1/wss-v1.1-spec-os-x509TokenProfile.pdfv WS-SecurityPolicy 1.3: http://docs.oasis-open.org/ws-sx/ws-securitypolicy/

v1.3/os/ws-securitypolicy-1.3-spec-os.pdf

Limitations:1. Key Derivation in Username Token Profile 1.1 is not tested or supported.2. X509PKIPathv1 and PKCS7 Token Type in X.509 Certificate Token Profile 1.1

are not tested or supported.

Web Services security default configuration

A web services security (WS-Security) configuration is complementary to theWS-Security policy at run time. The WS-Security configuration follows the CXFname and value pair style, and preserves the CXF property name. Some of theproperties have default values and some do not.

In the server.xml file, the WebSphere Application Server Liberty profile provides aserver level configuration which is applied to all services. This configuration isknown as the default WS-Security configuration.

There are two default WS-Security configurations in the server.xml file: one forclient applications and one for provider applications. No other WS-Securityconfigurations can exist in the server.xml file. If you need a custom WS-Securityconfiguration for your application that deviates from the default, the configurationmust be done programmatically.

The following examples illustrate default client and provider configurations:


https://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf

https://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf

http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-UsernameTokenProfile.pdf

http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-UsernameTokenProfile.pdf

http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-x509TokenProfile.pdf

http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-x509TokenProfile.pdf

http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.3/os/ws-securitypolicy-1.3-spec-os.pdf


<wsSecurityClient id="default"ws-security.username="user2"ws-security.password="security">

<signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Client"org.apache.ws.security.crypto.merlin.keystore.alias="x509ClientCert"org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks"/>

</wsSecurityClient>

<wsSecurityProvider id="default"ws-security.username="user2">

<encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerCert"org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks"/>

</wsSecurityProvider>

The following table illustrates the default WS-Security user properties in theLiberty profile. These same properties can be found in CXF.

Table 23. Default WS-Security user properties in the Liberty profile and CXF

Liberty profile/CXF property Default value

ws-security.username none

ws-security.password none

ws-security.signature.username none

ws-security.encryption.username none

The following table illustrates the WS-Security callback class and crypto propertiesin the Liberty profile and the equivalent CXF properties, if different.

Table 24. WS-Security callback class and crypto properties in the Liberty profile and the equivalent CXF properties

Liberty profile property CXF property Default value

ws-security.callback-handler none

<signatureProperties> ws-security.signature.properties none

<encryptionProperties> ws-security.encryption.properties none

In the WebSphere Application Server, the wss4j properties are specified asattributes of the signatureProperties or encryptionProperties elements. Thefollowing example illustrates the wss4j properties:

<signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Client"org.apache.ws.security.crypto.merlin.keystore.alias="x509ClientDefault"org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks">

</signatureProperties>

The following table illustrates the wss4j crypto properties in the Liberty profile.These same properties can be found in CXF.

Table 25. wss4j crypto properties in the Liberty profile and CXF


org.apache.ws.security.crypto.provider org.apache.ws.security.components.crypto.Merlin

org.apache.ws.security.crypto.merlin.keystore.provider

defaults to the installed provider

org.apache.ws.security.crypto.merlin.cert.provider

defaults to the keystore provider

org.apache.ws.security.crypto.merlin.x509crl.file

none


The following table illustrates the wss4j keystore properties in the Liberty profile.These same properties can be found in CXF.

Table 26. wss4j keystore properties in the Liberty profile and CXF


org.apache.ws.security.crypto.merlin.keystore.file

none

org.apache.ws.security.crypto.merlin.keystore.password

none

org.apache.ws.security.crypto.merlin.keystore.type

none

org.apache.ws.security.crypto.merlin.keystore.alias

none

org.apache.ws.security.crypto.merlin.keystore.private.password

none

The following table illustrates the wss4j truststore properties in the Liberty profile.These same properties can be found in CXF.

Table 27. wss4j truststore properties in the Liberty profile and CXF

Liberty profile property Default value

org.apache.ws.security.crypto.merlin.truststore.file

none

org.apache.ws.security.crypto.merlin.truststore.password

none

org.apache.ws.security.crypto.merlin.truststore.type

none

The following table illustrates the WS-Security miscellaneous properties in theLiberty profile. These same properties can be found in CXF.

Table 28. WS-Security miscellaneous properties in the Liberty profile and CXF


ws-security.enable.nonce.cache true

ws-security.cache.config.file none

The following table illustrates the properties that are supported only in the Libertyprofile.

Table 29. Properties that are supported only in the Liberty profile

Liberty profile property CXF property Default value

callerToken none none

Configuring additional properties

There are several extra properties that can be set to provide additionalconfiguration information to the WS-Security runtime environment. See thefollowing links for complete information regarding these properties:v http://cxf.apache.org/docs/ws-securitypolicy.htmlv http://ws.apache.org/wss4j/config.html

Any of the additional properties can be specified in the default WS-Securityconfiguration in the server.xml file.


http://cxf.apache.org/docs/ws-securitypolicy.html

http://ws.apache.org/wss4j/config.html

For example, to specify any additional properties, specify them in either thewsSecurityClient or wsSecurityProvider sections or both.

<wsSecurityProvider id="default"<signatureProperties ... /><encryptionProperties ... />ws-security.cache.config.file = "${server.config.dir}/resources/ws-security/new_cxf-ehcache.xml"


<wsSecurityClient id="default"<signatureProperties ... /><encryptionProperties ... />ws-security.username-token.always.encrypted="false"

</wsSecurityClient>

Configuring cache

WS-Security provides a default caching implementation for nonce in aUsernameToken, the created Timestamp, and security tokens. The default cacheimplementation is based on ehCache with the following default settings:maxEntriesLocalHeap="5000"timeToIdleSeconds="3600"timeToLiveSeconds="3600"overflowToDisk="true"maxElementsOnDisk="10000000"diskPersistent="false"diskExpiryThreadIntervalSeconds="120"memoryStoreEvictionPolicy="LRU"

To modify the default cache settings, you can provide an ehCache configurationXML file. Use the ws-security.cache.config.file custom property to specify a filename with customized properties to deviate from the default settings. You mustput this file somewhere in the server profile. You can find an additional samplecache setting configuration file from http://svn.apache.org/viewvc/cxf/trunk/rt/ws/security/src/main/resources/cxf-ehcache.xml?view=markup.

Authentication of web services clients with a UsernameToken

The WebSphere Application Server Liberty profile supports the OASIS WebServices Security UsernameToken Profile 1.1 specification. The specificationdescribes how a web services client supplies a UsernameToken as a means ofidentifying the requestor by using a user name, and optionally by using apassword or password-equivalent to the web services provider. The Web ServicesSecurity (WS-Security) run time in the Liberty profile that processes the policy forthe web services provider can use this identifying information to authenticate theuser.

The requirement of a UsernameToken is expressed as one of the supporting tokensin the WS-Security policy. You can add a UsernameToken requirement as arequired token in one of supporting token assertions, including SupportingTokens,SignedSupportingTokens, SignedEndorsingSupportingTokens,SignedEncryptedSupportingTokens, and EncryptedSupportingTokens.

The following example is a sample policy fragment that requires a UsernameTokenwith password text to be sent in the Security header of a SOAP message to a webservices provider:

<sp:SupportingTokens><wsp:Policy>

<sp:UsernameTokensp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient"><wsp:Policy>

<sp:WssUsernameToken11 />


http://svn.apache.org/viewvc/cxf/trunk/rt/ws/security/src/main/resources/cxf-ehcache.xml?view=markup

http://svn.apache.org/viewvc/cxf/trunk/rt/ws/security/src/main/resources/cxf-ehcache.xml?view=markup

</wsp:Policy></sp:UsernameToken>

</wsp:Policy></sp:SupportingTokens>

In addition to the requirement of providing a user name or a password, you canconfigure a policy to include a nonce and created timestamp in a UsernameToken.

The following example is a sample policy fragment that requies a UsernameTokenwith password text, nonce, and created timestamp to be sent in the Securityheader of a SOAP message to a web services provider:



<sp:WssUsernameToken11 /><sp13:Created /><sp13:Nonce />



The following example is a sample policy fragment that requires a UsernameTokenwith password digest instead of password text:



<sp:WssUsernameToken11 /><sp:HashPassword />



See the OASIS WS-Security policy 1.3 specification (http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.3/os/ws-securitypolicy-1.3-spec-os.pdf) for moreinformation about how to require nonce, created, and different password types.

Providing a user name and password in a web services client

The Web services security feature in the Liberty profile provides more than onemethod for indicating the user name and password for a client application whengenerating a UsernameToken. You can set the user name and passwordprogrammatically or in the server.xml file.

A client can generate a UsernameToken with the user name and passwordprovided in the server.xml file. The user name and password that is in theserver.xml file is considered the default configuration and is overridden by whatis provided on the RequestContext for the client's web service invocation.

The following example illustrates a sample default configuration:<wsSecurityProvider id="default"

ws-security.username="alice"ws-security.callback-handler="com.acme.PasswordCallback"


To generate a UsernameToken with the user name and password determinedprogrammatically, you can set the following CXF properties on the RequestContextfor the client's web service invocation:




ws-security.username: user namews-security.password: user password if ws-security.callback-handler is not definedws-security.callback-handler: the CallbackHandler implementation class used to obtain passwords

The following code sample illustrates how to provide a user name and passwordon the request context:Map<String, Object> requestCtx = ((BindingProvider)port).getRequestContext();requestCtx.put("ws-security.username", "bob_username");requestCtx.put("ws-security.password", "bob_password");

Consuming a UsernameToken in a web services provider

When a UsernameToken is received, WS-Security automatically uses the Libertyprofile security user registry to validate the user name and password, if thepassword is required. If the password type in the UsernameToken isPasswordDigest, you are required to provide the ws-security.callback-handlerimplementation of a password callback handler by configuring it in the server.xmlfile. This callback handler must return valid passwords for all expected user namesso that the WS-Security run time can calculate digest values for comparison withthe value in the SOAP message. After the digest value comparison completessuccessfully, the user name and password is validated against the user registry.

The following example illustrates a sample configuration in the server.xml file forpassword digest:<wsSecurityProvider id="default"

ws-security.callback-handler="com.acme.PasswordCallback"</wsSecurityProvider>

Password CallbackHandler

The password CallbackHandler is used by WS-Security to retrieve a userpassword. In the Liberty profile, this password CallbackHandler class must bepackaged as a Liberty feature. The following example illustrates a samplepassword CallbackHandler:public class PasswordCallbackHandler implements CallbackHandler {public void handle(Callback[] callbacks) throws IOException {for (int i=0;i<callbacks.length;i++) {WSPasswordCallback pwcb = (WSPasswordCallback)callbacks[i];String id = pwcb.getIdentifier();int usage = pwcb.getUsage();if (id.equals("Susan")) {if (usage == WSPasswordCallback.USERNAME_TOKEN) {pwcb.setPassword("susanuntpassword");

}}

}}

}

Refer to the Private key password CallbackHandler section of Protection of webservices with an X.509 token for more information on requirements and limitationsof a callback handler implementation.

Protecting a UsernameToken in a SOAP message

When UsernameToken is specified in a policy, the password type is password text(PasswordText) by default. When a password is sent with password text, it is sentin the message as-is. The following example is a UsernameToken with a passwordtype of PasswordText:


<UsernameToken><Username>myusername</Username><Password

Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">mypassword</Password>

</UsernameToken>

When you want to send a UsernameToken with PasswordText, you should consideradditional protections on the message, such as using HTTPS or encrypting thetoken using the EncryptedSupportingToken policy assertion. For more informationon requiring the use of the HTTPS transport in the policy, refer to Liberty Profile:Web services security HTTPS transport policy assertions.

Protection of web services with an X.509 token

The Liberty profile supports the Oasis Web Services Security X.509 CertificateToken Profile 1.1. An X.509 token can be used to provide message integrity andconfidentiality through signing and encrypting the messages.

WS-Security policy

To protect an XML message with an X.509 token, a contract that is specified in aWeb Services Description Language (WSDL) must be created first. The web servicemust have a WS-Security policy included in the WSDL file. The WS-Security policycan contain an AsymmetricBinding or SymmetricBinding assertions.

The requirement of an X.509 token is expressed as an X509Token assertion type inthe WS-Security policy. The following example illustrates a sample X509Tokenassertion:<sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient"><wsp:Policy><sp:WssX509V3Token10 />

</wsp:Policy></sp:X509Token>

In an AsymmetricBinding assertion, the initiator X509Token is used for messagesignature from the initiator (requestor) to the recipient (provider) and messageencryption from the recipient to the initiator. The recipient X509Token is used formessage signature from the recipient to the initiator and message encryption fromthe initiator to the recipient.

In a SymmetricBinding assertion, a secret key or ephemeral key that is protected foran X509Token is shared by both the initiator and the recipient, and the key is usedfor both encryption and decryption.

The following example illustrates a sample WS-Security policy with an X509Tokenin an AsymmetricBinding assertion:

<wsp:Policy wsu:Id="SampleAsymmetricX509TokensPolicy"><wsp:ExactlyOne>

<wsp:All><sp:AsymmetricBinding>

<wsp:Policy><sp:InitiatorToken>

<wsp:Policy><sp:X509Token sp:IncludeToken=

"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient"><wsp:Policy>

<sp:WssX509V3Token10 /></wsp:Policy>

</sp:X509Token></wsp:Policy>

</sp:InitiatorToken>


<sp:RecipientToken><wsp:Policy>

<sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never"><wsp:Policy>

<sp:WssX509V3Token10 /></wsp:Policy>

</sp:X509Token></wsp:Policy>

</sp:RecipientToken><sp:AlgorithmSuite>

<wsp:Policy><sp:Basic128 />

</wsp:Policy></sp:AlgorithmSuite><sp:Layout>

<wsp:Policy><sp:Strict />

</wsp:Policy></sp:Layout><sp:IncludeTimestamp /><sp:ProtectTokens /><sp:OnlySignEntireHeadersAndBody />

</wsp:Policy></sp:AsymmetricBinding><sp:Wss10>

<wsp:Policy><sp:MustSupportRefKeyIdentifier />

</wsp:Policy></sp:Wss10>

</wsp:All></wsp:ExactlyOne>

</wsp:Policy>

The following example illustrates a sample WS-Security policy with an X509Tokenin a SymmetricBinding assertion:

<wsp:Policy wsu:Id="SampleSymmetricX509TokensPolicy"><wsp:ExactlyOne>

<wsp:All><sp:SymmetricBinding>

<wsp:Policy><sp:ProtectionToken>

<wsp:Policy><sp:X509Token sp:IncludeToken=

"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never"><wsp:Policy>

<sp:WssX509V3Token11 /><sp:RequireThumbprintReference />

</wsp:Policy></sp:X509Token>

</wsp:Policy></sp:ProtectionToken><sp:Layout>

<wsp:Policy><sp:Lax />

</wsp:Policy></sp:Layout><sp:IncludeTimestamp /><sp:OnlySignEntireHeadersAndBody /><sp:SignBeforeEncrypting /><sp:AlgorithmSuite>


</wsp:Policy></sp:AlgorithmSuite>

</wsp:Policy></sp:SymmetricBinding><sp:EncryptedParts>

<sp:Body /></sp:EncryptedParts><sp:SignedParts>

<sp:Body /></sp:SignedParts>

</wsp:All></wsp:ExactlyOne>

</wsp:Policy>

Token reference and token inclusion

A token assertion can carry an sp:IncludeToken attribute that requires that thetoken be included in the message. Several token assertions support mechanisms forreferencing tokens in addition to direct references. If a token assertion containsmultiple reference assertions, then the references to that token are required to


contain all the specified reference types. For example, if a token assertion carries ansp:IncludeToken attribute with a value of ../Always and that token assertion alsocontains a nested sp:RequireIssuerSerialReference assertion, then the token mustbe included twice in the message. While such combinations are not in error, theyare best avoided for efficiency reasons.

The IncludeToken assertion is enforced in the Liberty profile, but is ignored in theWS-Security runtime environment of the full profile.

The WS-Security policy supports the following token reference mechanisms:v KeyIdentifier: <sp:RequireKeyIdentifierReference... />

v IssuerSerial: <sp:RequireIssuerSerialReference ... />

v Thumbprint: <sp:RequireThumbprintReference ... />

These references are used when generating an X.509 token on the client/generatorside, and are not enforced on the server/consumer side.

Runtime configuration

The WS-Security feature run time in Liberty provides more configuration optionsfor message protection with an X509Token than are covered by the WS-Securitypolicy. The runtime configuration is defined in the server.xml file. The runtimeconfiguration includes cryptographic properties such as signatureProperties andencryptionProperties, key, and keystores.

The following example illustrates a client configuration for an X509Token assertion:<wsSecurityClient id="default"

ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler"><signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"

org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Client"org.apache.ws.security.crypto.merlin.keystore.alias="x509ClientDefault"org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks" />

<encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"org.apache.ws.security.crypto.merlin.keystore.password="LibertyXClient"org.apache.ws.security.crypto.merlin.keystore.alias="x509DefaultCert"org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks" />

</wsSecurityContext>

The following example illustrates a server configuration for an X509Token assertion:<wsSecurityProvider id="default"

ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler"><signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"

org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks" />

<encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks" />


In the runtime configuration, the signatureProperties and encryptionPropertiesproperties are equivalent to the crypto properties in the WSS4J configuration. SeeWSS4J configuration for additional details. Many crypto properties have validdefault values so there is no need to specify them. But other properties, such askeystore and key related properties, must be specified.

Keystores files, keys, and certificates

Message signature and encryption requires the use of public certificates andprivate keys. These public certificates and private keys are stored in keystore files.Keystore files are required when you use X509Token assertions. The client-sidekeystore file contains the private key of the client, and a chain of certificates


http://ws.apache.org/wss4j/config.html

corresponding to the public key of the server. The server-side keystore file containsthe private key of the server, and a chain of certificates corresponding to the publickey of the client.

When a SOAP message is signed and encrypted, the signatureProperties andencryptionProperties properties are interpreted by the WS-Security runtimeenvironment as follows:v AsymmetricBinding assertion

The key specified by the signatureProperties property is used as the privatekey for signing the outbound message, and is also used for decrypting theinbound message.The key specified by the encryptionProperties property is used as the publickey for encrypting the outbound message, and is also used for verifying thesignature in the inbound message.

v SymmetricBinding assertionThe key specified by the encryptionProperties properties is used, while thesignatureProperties property is ignored.

Private key password CallbackHandler

To access a private key in a keystore, you must know two different passwords.One password is for the keystore where the private key is stored. The otherpassword is for the private key itself. While the password for the keystore isspecified in one of the crypto properties, either signatureProperties orencryptionProperties, the CallbackHandler is normally used by WS-Security toaccess the private key in a keystore. In the Liberty profile, this CallbackHandlerclass must be packaged as a Liberty feature and its class name specified as a thevalue for the ws-security.callback-handler custom property in the security.xml.

This CallbackHandler is required by WS-Security to access the private key in akeystore.

The following example illustrates a sample CallbackHandler:public class KeyPasswordCallbackHandler implements CallbackHandler {public void handle(Callback[] callbacks) throws IOException {for (int i=0;i<callbacks.length;i++) {WSPasswordCallback pwcb = (WSPasswordCallback)callbacks[i];String id = pwcb.getIdentifier();int usage = pwcb.getUsage();if (id.equals("Joe")) {if (usage == WSPasswordCallback.DECRYPT || usage == WSPasswordCallback.SIGNATURE) {// used to retrieve the password for the private keypwcb.setPassword("JoeKeypassword");

}}

}}

}

If the password CallbackHandler class is not provided, then the password specifiedin the crypto properties is used as that default password for the private key. Thisproperty is configured asorg.apache.ws.security.crypto.merlin.keystore.private.password.

Since there is only one ws-security.callback-handler custom property supportedin each of the wsSecurityClient and wsSecurityProvider sections of thesecurity.xml file, a single password callback handler must support all of therequired passwords for each application type (client or server) that use the default.All provider applications must use the default password callback handler. Client


applications can override the default callback handler by specifying thews-security.callback-handler custom property on the RequestContext for theweb service invocation of the client.

If you need to provide passwords for an X.509 private key and a UsernameTokenfor a single web service invocation, you cannot provide separate callback handlersfor each use. In this case, you must implement a single callback handler thathandles both kinds of passwords. As illustrated in the previous example, you mustuse the WSPasswordCallback.getUsage() method to determine which kind ofpassword that you should return. See the WSPasswordCallback API documentationfor the supported usage codes http://ws.apache.org/wss4j/apidocs/org/apache/ws/security/WSPasswordCallback.html.

Web services security HTTPS transport policy assertions

You can user assertions in the Web Services Security (WS-Security) policy definedin the WSDL to ensure that the SOAP message is protected with the HTTPS securetransport. It is recommended that HTTPS be used when using security tokens suchas UsernameTokens with clear text passwords to ensure confidentiality.

The assertions for the HTTPS transport in the WS-Security policy do not set up theHTTPS transport between the requestor and provider. They only ensure that theHTTPS transport is used when the web services application with the definedpolicy is invoked.

This topic assumes that HTTPS is set up between the web services client andprovider. The following steps are extra steps that are required.

1. WS-Security must be explicitly enabled by enabling thewssecurity-1.0 feature.

2. The attached WS-SecurityPolicy must include a TransportBinding assertion,and must match the HTTPS configuration. The following example illustrates asample TransportBinding assertion:<wsp:Policy xmlns:wsp="..." xmlns:sp="...">

<sp:TransportBinding><wsp:Policy>

<sp:TransportToken><wsp:Policy>

<sp:HttpsToken /></wsp:Policy>

</sp:TransportToken><sp:AlgorithmSuite>


</wsp:Policy></sp:AlgorithmSuite><sp:Layout>

<wsp:Policy><sp:Strict />

</wsp:Policy></sp:Layout><sp:IncludeTimestamp />

</wsp:Policy></sp:TransportBinding>

</wsp:Policy>

By completing these extra steps after the HTTPS configuration, the SOAP messageis required to be sent over HTTPS from a web services client to a web servicesprovider.


http://ws.apache.org/wss4j/apidocs/org/apache/ws/security/WSPasswordCallback.html

http://ws.apache.org/wss4j/apidocs/org/apache/ws/security/WSPasswordCallback.html

Chapter 10. Deploying applications to the Liberty profile

You can deploy web applications or OSGi applications to the Liberty profile. Youdeploy an application by either dropping the application into a previously-defined“dropins” directory, or by adding an application entry to the server configuration.

Before you begin

Distributed operating systems You can deploy applications as described in this topic, oras described in “Adding and running an application on the Liberty profile byusing developer tools” on page 519.

This topic assumes that you have not disabled dynamic updates to the runtimeconfiguration, as described in “Controlling dynamic updates” on page 374.

About this task

By default, the “dropins” directory is automatically monitored. If you drop anapplication into this directory, the application is automatically deployed on theserver. Similarly, if the application is deleted from the directory, the application isautomatically removed from the server. The “dropins” directory can be used forapplications that do not require additional configuration, such as security rolemapping. If you put your applications in the “dropins” directory, you must notinclude an entry for the application in the server configuration. Otherwise, theserver will try to load the application twice and an error might error. Forapplications that are not in the “dropins” directory, you specify the location usingan application entry in the server configuration. The location can be on the filesystem or at a URL.

Your application can be packaged as an archive file or as a directory. Forapplications in the “dropins” directory, the file name and file extension are used bythe application monitor to determine the type of application, and to generate theapplication name and the context-root for web applications. For example, if thearchive file or directory is named snoop.war, the application monitor assumes thatthe application is a web application, that the application name is “snoop”, and thatthe context-root is also snoop. For configured applications, you specify theapplication type and name, and if the application is a web application, theapplication name is also used as the context-root.

For more information about the default directory structure and the properties thatare associated with directories (for example server.config.dir), see “Libertyprofile: Directory locations and properties” on page 89.

Procedurev Deploy an application by dropping it into the dropins directory.

For example, using the default directory structure, to deploy an application youdrop it into the ${server.config.dir}/dropins directory (that is,wlp/usr/servers/server_name/dropins).The structure of your application can be as following in the /dropin directory:


– Place the archive file with its identifying suffix (ear, war, wab, and so on)directly into the /dropin directory. For example, ${server.config.dir}/dropins/myApp.war

– Extract the archive file into a directory named with the application name andthe identifying suffix. For example, ${server.config.dir}/dropins/myApp.war/WEB-INF/...

– Place the archive file or the extracted archive into a subdirectory named withthe identifying suffix. For example, ${server.config.dir}/dropins/war/myApp/WEB-INF/...

v Deploy an application by adding it to the server configuration file.Configure the application element in the server.xml configuration file. See“Liberty profile: Configuration elements in the server.xml file” on page 97. Youmust configure the following attributes for the application:

id Must be unique and is used internally by the server.

name Must be unique and depending on the application. The value of namemight be used as the context-root of the application. For moreinformation on how the context-root is set for an application, see“Deploying a web application to the Liberty profile” on page 529.

type Specifies the type of the application. The supported application types arewar, ear, wab and eba.

locationSpecifies the location of the application. It can be an absolute path or aURL which you can download the application from. It can also be thefile name of your application (including file extension if any).

If the application is available on the file system, the location can either be thefull path name or a simple file name. If the location does not include the fullpath, the application manager looks for the application in${server.config.dir}/apps and ${shared.app.dir}. If the application isavailable at a URL, the application manager downloads the application to atemporary folder inside the server work area, then starts the application.

Note: The location that you specify for a configured application should not be inthe “dropins” directory. If you drop an application into the “dropins” directory,and also specify the location in the server.xml file, you are telling the server todeploy the application twice.In the following two examples, the location is the file system. If the location is aURL, enter the URL in the location field.<application id="ImpactEBA" name="ImpactEBA" type="eba" location="D:/apps/ImpactEBA.eba"/><application id="ImpactWeb" name="ImpactWeb" type="war" location="ImpactWeb.war"/>

The second example does not include the full path. In this case, you must putthe application in one of the following locations:– ${server.config.dir}/apps (that is, server_directory/user/servers/

server_name/apps)– ${shared.app.dir} (that is, liberty_install_location/usr/shared/apps)

Note:

– You must create the server-level apps directory, whereas the shared appsdirectory is present by default. See “Liberty profile: Directory locations andproperties” on page 89 for more information about the properties associatedwith the server directories.


– The application element can be set before or after the server has started. Ifthe element is set after the server has started, the changes are picked updynamically.

v Remove an application.For applications that are included in the server configuration, remove thereference to the application from the server.xml file. The application is thenautomatically removed from the server.For applications that are deployed to the “dropins” directory, delete theapplication from the directory. The application is then automatically removedfrom the server.To uninstall all applications that are in the “dropins” directory, set theapplication monitor dropinsEnabled property to false as described in“Controlling dynamic updates” on page 374.

What to do next

For all deployed applications, you can configure whether application monitoring isenabled and how often to check for updates to applications. For the “dropins”directory, you can also configure the name and location of the directory and choosewhether to deploy the applications that are in the directory. See “Controllingdynamic updates” on page 374.

Adding and running an application on the Liberty profile by usingdeveloper tools


You can add applications to the server by right-clicking on the server in theServers view then selecting Add and Remove from the menu.

Before you begin

The Liberty profile developer tools currently support web and OSGi applications.For details on OSGi applications support, see the Blueprint and Web ApplicationBundles (WAB) feature sections in the “Liberty features” on page 14 topic. Inaddition, for details on restrictions of OSGi applications, see the wab-1.0 featurerestrictions section in the Liberty profile: Runtime environment known restrictionstopic.

This task assumes that your application is in your Eclipse workspace. If you have aprebuilt application archive file that you want to add and run, you must firstimport the file into your Eclipse workspace. Alternatively, you can use the stepsdescribed in Chapter 10, “Deploying applications to the Liberty profile,” on page517.

About this task

When you add an application to the server, the workbench tries to determinewhich features are required by the application and enables them in the serverconfiguration for you if they are not already enabled.

Procedure1. In the Servers view, right-click the server and select Add and Remove.

Chapter 10. Deploying applications to the Liberty profile 519

2. In the Add and Remove wizard, under the Available list, select theapplications you want to add then click Add. Or click Add All to add allavailable applications to the server.

3. Alternatively, you can right-click on an application in the Project Explorer viewand select Run As > Run on Server, or Debug As > Debug on Server. Thisadds the application to the server (if not already added), starts the server (if notalready started) and runs the application.

Results

Tip: If you are using Run on Server or Debug on Server and the server is alreadystarted, the browser might try to load the application before the server has finishedloading it. If this happens, wait for the message in the console view that displaysthe application has been started and then refresh the browser if necessary.

Publishing your application by using developer toolsDistributed operating systems

Publishing involves copying files (projects, resource files, and serverconfigurations) to the correct location for the server to find and use them. In thetest environments, these files might already be in the correct location. In somecases, temporary copies of the server configurations might be created. You caneither publish your application automatically or manually.

About this task

Automatically publishing to a server

Procedure1. If the Automatically publish when starting servers check box on the Server

preferences page (Window > Preferences > Server > Launching) is selected,the workbench checks to see if your project and files on the server aresynchronized. If they are not, the project and the files are automaticallyupdated when the server is either started or restarted.

2. In the workbench, you have several options to choose for the Publishingsettings. You can set these Publishing settings by going into the Servers view,right-click the server and select Open. The Server editor opens. In the Overviewpage of the server editor, under the Publishing settings, you are going to findthe following settings:a. Never publish automatically: Specifies the workbench should never publish

files to the server.b. Automatically publish when resources change: Specifies the workbench to

issue a publish after changes on a file that is associated to the server aresaved and a full time interval has passed in the Publishing interval setting.In the workbench, the default setting is the Automatically publish whenresources change option is enabled with a value set in the publishinginterval.

c. Automatically publish after a build event: Specifies the workbench to issuea publish after changes on a file that requires a build and is associated tothe server are saved, and a full time interval has passed in the Publishinginterval setting.

d. Publishing interval (in seconds): Specifies the number of seconds requiredbefore the workbench calls a publish to happen on the server. However, if


you make a subsequent change to the files before this time interval hascompleted, the publish is delayed as the timer is reset. The workbenchmakes a publish to the server only after the full time interval has passed. Ifyou set the publishing interval to 0 seconds, an immediate publish shouldhappen after changes on a file are saved.

Manually publishing to a serverAbout this task

If you do not want to wait for the automatic publishing interval to pass or theNever publish automatically option is enabled, at anytime you can manuallyrequest the workbench to issue a publish command to the server. Each manualpublish command causes a single publishing request to the server. To publish yourapplication manually you can complete one of the following actions in the Serversview:

Procedurev Select the server and then click the Publish to the server icon located on the

toolbar.v Right-click the server and then select Publish.

Publishing settings for a WebSphere Application Server V8.5Liberty profilePublishing involves copying files such as application, resource files, anddeployment descriptor files to the correct location for the server to find and usethem. You can choose whether you want to publish your application on the serveror run your application within the development environment without copying theapplication into the directories of the server.

About this task

Run applications directly from the workspace

The Run applications directly from the workspace publishing option requests theserver to run your application from the workspace.

This publishing option should publish faster when an application contains a singleroot, as opposed to containing multiple roots, because the server expects thestructure of an application to have only a single root. As a result, the workbenchmight require additional processing time to publish an application with multipleroots. To determine whether the structure of your application contains a single ormultiple roots, use the Project Structure Validator. For details, see Creating andconfiguring Java EE projects using wizards.


http://publib.boulder.ibm.com/infocenter/radhelp/v8/index.jsp?topic=/com.ibm.javaee.doc/ae/tcreatajavaeeprojwiz.html

http://publib.boulder.ibm.com/infocenter/radhelp/v8/index.jsp?topic=/com.ibm.javaee.doc/ae/tcreatajavaeeprojwiz.html

CAUTION:When you are using Run applications directly from the the workspacepublishing option, the server can lose track of your application under thefollowing scenarios:

v If you delete your workspace, the server can no longer find your application.As a result, if you did not put your application under source controlmanagement and the workspace is deleted, you can lose your application fromyour file system.

v If you delete an application from the workspace without removing it from theserver, the server can no longer find your application. As a result, you mightencounter errors when starting the server because the server tries to start themissing application from the workspace.

Procedure1. In the Servers view, double-click your WebSphere Application Server V8.5

Liberty profile to open the server editor.2. Click the Overview tab.3. Select Run applications directly from the workspace.4. Save and close the editor.

Packaging a Liberty profile server from the command promptFrom the command prompt you can create a compressed file containing a Libertyprofile runtime environment, the files in the shared resources directory, a specificserver, and the applications that are embedded in the server. You can also chooseto exclude the runtime binaries from the compressed file.

About this task

The Liberty server is lightweight, therefore you can easily package a serverinstallation in a compressed file. You can then store this package, distribute it tocolleagues, use it to deploy the installation to a different location or to anothermachine, or even embed the installation in a product distribution.

Note: Distributed operating systems The resulting file is created by using UTF-8encoding for entry names, so you must use a tool capable of opening the file byusing UTF-8 encoding for entry names. The jar command in a Java SDK uses thisformat.

Procedure

To package a Liberty profile server from the command prompt, complete thefollowing steps:1. Open a command prompt, then change directory to the wlp/bin directory.2. Stop the server.3. Package the server.

Run the following command. If you do not specify a server name,defaultServer is used. If you do not specify the --archive parameter, the valueof server_name is used for package_file_name, and the compressed file is createdin the ${server.output.dir} directory.

vDistributed operating systems


server package server_name --archive=package_file_name.zip --include=all

where package_file_name.zip is a file name that you choose. This file namecan include a full path name. If the full path is omitted, a compressed filecalled package_file_name.zip is created in the ${server.output.dir} directory.

You can also use the --include option with this command. For example, the--include=all option packages the runtime binaries and the relevant files inthe ${WLP_USER_DIR} directory; the --include=usr option packages onlyrelevant files in the ${WLP_USER_DIR} directory, effectively excluding the runtimebinaries from the compressed file.

Using JNDI binding for constants from the server configuration filesYou can bind constants into the default JNDI namespace from the serverconfiguration files using the jndiEntry element on the Liberty profile.

About this task

The default JNDI namespace is available in the Liberty profile to provide bindingsto miscellaneous objects required by applications. Any data sources declared in theserver configuration files are available in the default JNDI namespace. Additionally,you can bind Java strings and primitive data types in the configuration file intoJNDI namespace. These constants are then made available to an application at runtime, providing a simple and portable way to pass configuration values into theapplication.

See Naming for more information about JNDI.

The following steps show how to bind the constants and use them in yourapplication.

Procedure1. To add a constant into the default JNDI namespace, the jndi-1.0 Liberty

feature must be specified in the server.xml file of the Liberty profile server.<featureManager>

<feature>jndi-1.0</feature></featureManager>

2. To bind constants into the JNDI namespace, add jndiEntry elements into theserver.xml file by specifying the jndiName and value attributes.<jndiEntry jndiName="schoolOfAthens/defaultAdminUserName" value=’"plato"’ /><jndiEntry jndiName="schoolOfAthens/defaultAdminPassword" value=’"republic"’ />

3. To look up the constants from an application using a JNDI context, use thefollowing code:

Object jndiConstant = new InitialContext().lookup("schoolOfAthens/defaultAdminUserName");String defaultAdmin = (String) jndiConstant;

Note:

v The lookup() method returns an object to the application. The type of theobject is determined by interpreting the value stored in the jndiEntryelement as a Java literal string or primitive data type. If the parsing fails, theexact value is provided as an unmodified string.

v The jndiEntry element supports the integer, floating-point, boolean,character, and string literals as described in the Java Language Specification,Java SE 7 Edition, section 3.10. String and character literals might contain


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=cnam_naming

http://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10


unicode escaped sequences (section 3.3), and the octal and character escapesequences (section 3.10.6). The null literal (section 3.10.7) and class literals(section 15.8.2) are not supported.

See the following examples of Java literals:v The string "Hello, world" followed by a newline:

<jndiEntry jndiName="a" value=’"Hello, world.\n"’ />

v The integer with a binary value 1010101:<jndiEntry jndiName="b" value="0b1010101" />

v The single character 'X':<jndiEntry jndiName="c" value="’X’" />

v The double-precision floating point number 1.0:<jndiEntry jndiName="d" value="1.0D" />

See “Liberty profile: Configuration elements in the server.xml file” on page 97for more information about jndiEntry element.

Deploying OSGi applications to the Liberty profileYou can deploy OSGi applications to the Liberty profile by enabling a list of serverfeatures in the server.xml file.

About this task

By providing a list of OSGi-specific server features, Liberty profile provides OSGisupport for your applications. These features are as follows:v blueprint-1.0

v osgi.jpa-1.0

v wab-1.0

For a full list of server features in the Liberty profile, see “Liberty features” onpage 14.

Sharing common OSGi bundles for the Liberty profileYou can share common OSGi bundles by placing them in a directory andconfiguring the server.xml file for your server, so that those common OSGibundles are available to your OSGi applications.

Procedurev Create a directory in your file system and place all the common OSGi bundles

into the directory.v Add the following lines into the server.xml file.

<bundleRepository><fileset dir="directory_path" include="*.jar"/>

</bundleRepository>

Where directory_path is the path to the directory that contains the common OSGibundles.

v Define a dependency on the common bundle using import phrase in themanifest.mf file of your OSGi application.



http://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10.6





Deploying data access applications to the Liberty profileDeploying a data access application includes more than installing your webapplication archive (WAR) or enterprise archive (EAR) file onto a Liberty profile.Deployment can include tasks for configuring the data access resources of theserver and overall runtime environment.

About this task

This following topics are covered in this section:

Procedurev Configure a data source and JDBC driver for database connectivity in a Liberty

profilev Deploy an JDBC application to the Liberty profilev Optional: Configure connection pooling in the Liberty profilev Optional: Develop an application-defined data source on the Liberty profilev Optional: Configure transaction recovery for data sources on the Liberty profilev Migrating data access applications to the Liberty profile

Deploying an existing JDBC application to the Liberty profileYou can take an existing application that uses Java Database Connectivity (JDBC)and a data source, and deploy the application to a server.

About this task

You can take an existing JDBC application and deploy it to the Liberty profile. Todo this, you add the jdbc-4.0 Liberty feature to the server.xml file. You must alsoadd code that tells the server the JDBC driver location and specifies properties thatthe JDBC driver uses to connect to the database.

This example uses the ImpactWeb sample application. This application includes aservlet called WorkingServlet. In this example, you extend the servlet with codethat tests that the JDBC application is working as expected.

Procedure1. Create a server.2. Add the jdbc-4.0 and the servlet-3.0 Liberty features to the server.xml file.3. Add code to the server.xml file to specify the database type and the data

source location.For example:<jdbcDriver id="DerbyEmbedded" libraryRef="DerbyLib"/><library id="DerbyLib"><fileset dir="C:/myDerbyLocation/lib" includes="derby.jar"/>

</library><dataSource id="ds1" jndiName="jdbc/exampleDS" jdbcDriverRef="DerbyEmbedded"><properties.derby.embeddeddatabaseName="C:/myDerbyLocation/data/exampleDB"createDatabase="create"

/></dataSource>

For information about other options for coding data source definitions, see“Using Ref tags in configuration files” on page 373.

4. Optional: Enable JDBC tracing.


5. Modify the WorkingServlet.java servlet.For example, add the following code:@Resource(name = "jdbc/exampleDS")DataSource ds1;Connection con = ds1.getConnection();Statement stmt = null;try {stmt = con.createStatement();// create a tablestmt.executeUpdate("create table cities

(name varchar(50) not null primary key, population int, county varchar(30))");// insert a test recordstmt.executeUpdate("insert into cities values (’myHomeCity’, 106769, ’myHomeCounty’)");// select a recordResultSet result = stmt.executeQuery("select county from cities where name=’myHomeCity’");result.next();// display the county information for the city.System.out.println("The county for myHomeCity is " + result.getString(1));

}catch (SQLException e) {e.printStackTrace();

}finally {try {// drop the table to clean up and to be able to rerun the test.stmt.executeUpdate("drop table cities");

}catch (SQLException e) {e.printStackTrace();

}con.close();

}

6. Add the application to the server.7. If it is not already running, start the server.8. Optional: Test that the JDBC application is working as expected.

For example, run the modified WorkingServlet.java servlet. You should see thefollowing console output:[AUDIT ] CWWKZ0001I: The application ImpactWeb has started successfully.[AUDIT ] CWWKD0000I: The dataSource ds1 is available as jdbc/exampleDB.[AUDIT ] CWWKD0000I: The jdbcDriver DerbyEmbedded is available.The county for myHomeCity is myHomeCounty

Enabling JDBC Tracing for the Liberty profileJDBC tracing for the Liberty profile is enabled either through a driver-specificcustom trace setting, or using the application server supplemental JDBC tracingoption.

About this task

There are two ways of using driver-specific custom trace facilities:v Using the Java built-in logging mechanism, java.util.logging, if the driver

supports it.v Configuring a custom trace setting as a vendor property.

If your JDBC driver does not provide its own custom tracing or logging facilities,or the facilities it provides are minimal, you can use supplemental JDBC tracingfrom the application server.

If you enable tracing by using either a custom vendor property or supplementalJDBC tracing, you must add the logwriter name to the trace specification in thebootstrap.properties file. You can use any of the following logwriters:

DB2 com.ibm.ws.db2.logwriter

Derby com.ibm.ws.derby.logwriter


Informix JCC (uses the same driver as DB2)com.ibm.ws.db2.logwriter

Informix JDBCcom.ibm.ws.informix.logwriter

Microsoft SQL Server JDBC Drivercom.ibm.ws.sqlserver.logwriter

DataDirect Connect for JDBC for Microsoft SQL Servercom.ibm.ws.sqlserver.logwriter

Sybasecom.ibm.ws.sybase.logwriter

Other databases (for example solidDB and MySQL)com.ibm.ws.database.logwriter

Because changes to trace enablement involve altering the bootstrap.propertiesfile, you must restart the server for the changes to take effect.

The following examples illustrate the use of the various JDBC trace methods.

Procedurev Use java.util.logging.

If the driver you are using supports java.util.logging, you can enable it byappending the driver's trace level to com.ibm.ws.logging.trace.specificationin the bootstrap.properties file. See the JDBC vendor documentation for levelsand other trace information specific to your driver.Here is an example for Microsoft SQL Server JDBC Driver:– Example code for the bootstrap.properties file:

com.ibm.ws.logging.trace.specification=*=audit=enabled:com.microsoft.sqlserver.jdbc=FINE

Here is an example for Oracle JDBC:– Example code for the bootstrap.properties file:

com.ibm.ws.logging.trace.specification=*=audit=enabled:oracle=FINE

– For Oracle, you must also enable the tracing using the system propertyoracle.jdbc.Trace, using one of the following two options:- In the bootstrap.properties file, add the setting oracle.jdbc.Trace=true

- In a Java program, add the settingSystem.setProperty("oracle.jdbc.Trace","true");

v Use custom trace settings.If the driver you are using has custom trace settings, you set them as JDBCdriver vendor properties in the server.xml file. You also add the logwriter nameto the trace specification in the bootstrap.properties file.Here is an example for DB2 JCC, using the custom property traceLevel:– Example code for the server.xml file:

<dataSource id="db2" jndiName="jdbc/db2" jdbcDriverRef="DB2Driver" ><properties.db2.jcc databaseName="myDB" traceLevel="-1"/>

</dataSource>

– Example code for the bootstrap.properties file:com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.db2.logwriter=all=enabled

Here is an example for Derby Network Client:– Example code for the server.xml file:

<dataSource id="derbyNC" jndiName="jdbc/derbyNC" jdbcDriverRef="DerbyNC" ><properties.derby.client databaseName="myDB" createDatabase="create" traceLevel="1"/>

</dataSource>


– Example code for the bootstrap.properties file:com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.derby.logwriter=all=enabled

Here is an example for Informix JCC. This database uses the DB2 drivers for JCCconnectivity.– Example code for the server.xml file:

<dataSource id="informixJCC" jndiName="jdbc/informixJCC" jdbcDriverRef="InformixDriverJCC" ><properties.informix.jcc databaseName="myDB" traceLevel="-1"/>

</dataSource>

– Example code for the bootstrap.properties file:com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.db2.logwriter=all=enabled

v Use supplemental JDBC tracing.If your JDBC driver does not provide suitable tracing or logging facilities, youcan use supplemental JDBC tracing from the application server. The applicationserver automatically determines whether to enable supplemental JDBC tracing,based on the JDBC driver being used. To override this, set the data sourceproperty supplementalJDBCTrace to true or false.1. Enable supplemental tracing.

Here is an example for enabling supplemental tracing with the embeddedDerby database. Supplemental JDBC tracing is enabled by default for thisdatabase, so you only need to set the logwriter in the bootstrap.propertiesfile:– Example code for the bootstrap.properties file:

com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.derby.logwriter=all=enabled

Here is an example for enabling supplemental tracing with Informix JDBC.Supplemental JDBC tracing is enabled by default for this database.– Example code for the bootstrap.properties file:

com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.informix.logwriter=all=enabled

Here is an example for enabling supplemental tracing, andjava.util.logging, with Microsoft SQL Server JDBC Driver:– Example code for the bootstrap.properties file:

com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.sqlserver.logwriter=all=enabled:com.microsoft.sqlserver.jdbc=all

Here is an example for enabling supplemental tracing with DataDirectConnect for JDBC for Microsoft SQL Server:– Example code for the bootstrap.properties file:

com.ibm.ws.logging.trace.specification=*=audit=enabled:com.microsoft.sqlserver.jdbc=all

Here is an example for enabling supplemental tracing with solidDB.Supplemental JDBC tracing is enabled by default for this database.– Example code for the server.xml file:

<dataSource id="soliddb" jndiName="jdbc/soliddb" jdbcDriverRef="solidDBDriver"><properties databaseName="dba" URL="jdbc:solid://localhost:2315/dba/dba" />

</dataSource>

– Example code for the bootstrap.properties file:com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.database.logwriter=all=enabled

Here is an example for enabling supplemental tracing with Sybase.Supplemental JDBC tracing is enabled by default for this database.– Example code for the bootstrap.properties file:

com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.sybase.logwriter=all=enabled

Here is an example for enabling supplemental tracing with other databases:– Example code for the bootstrap.properties file:

com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.database.logwriter=all=enabled

2. Disable supplemental tracing


To disable supplemental JDBC tracing, either set the supplementalJDBCTracedata source property to false in the server.xml file, or remove the logwritername from the com.ibm.ws.logging.trace.specification property in thebootstrap.properties file:– Example code for the server.xml file for solidDB:

<dataSource id="soliddb" jndiName="jdbc/soliddb"jdbcDriverRef="solidDBDriver" supplementalJDBCTrace="false">

<properties databaseName="dba" URL="jdbc:solid://localhost:2315/dba/dba" /></dataSource>

– Example code for the bootstrap.properties file for solidDB:com.ibm.ws.logging.trace.specification=*=audit=enabled

Deploying a web application to the Liberty profileBy deploying a helloworld.war application, you can learn how serverconfigurations change in the Liberty profile.

Before you begin

The helloworld.war application uses a simple servlet to display a message on yourbrowser. You can create any other messages to be displayed. The coding of theapplication is not described within the Liberty profile documents.

About this task

When you deploy a web application to the Liberty profile when the server is upand running, all configurations related to the application are automatically enabledin the server.xml file. However, you can also configure the server.xml filemanually by completing the following steps.

This example uses the helloworld.war application and can be accessed viahttp://localhost:9090/helloworld. In this example, we create a Liberty profileserver instance and change its default HTTP port to 9090, then deploy theapplication on it.

Procedure1. Create a server named hwserver using the command server create hwserver.2. Create a directory apps for application deployment under the newly created

server directory. The directory should be like /usr/servers/hwserver/apps.3. Copy the helloworld.war application into the apps directory created.4. Change the default HTTP port of the server hwserver to 9090 by adding the

following line into the server.xml file.<httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9090" />

5. Configure the application by updating the server.xml as follows:<server description="Hello World Server">

<featureManager><feature>servlet-3.0</feature>

</featureManager>

<httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="9090" />

<application context-root="helloworld" type="war" id="helloworld"location="helloworld.war" name="helloworld"/>

</server>


Where context-root specifies the entry point of the deployed application. Theentry point of a deployed application is determined in the followingprecedence:v context-root in the server.xml filev application.xml, if an EAR applicationv ibm-web-ext.xml, if a web applicationv name of the application in the server.xml file, if a web applicationv Manifest.MF, if a WAB applicationv Directory name or the file name relative to the "dropins" directory of the

Liberty profile6. Start the server in foreground using the command server run hwserver.7. Test the application at http://localhost:9090/helloworld.8. Optional: Stop the server if you don't need it.

Deploying a JPA application to the Liberty profileTo enable the Liberty profile to support an application that uses the JavaPersistence API (JPA), you add the jpa-2.0 feature to the server.xml file. You alsoneed to define persistence contexts and persistence units, and configure access tothe entity manager and entity manager factory.

Before you begin

This task assumes that you have created a Liberty profile server, on which youwant to deploy an application that uses JPA. See “Creating a Liberty profile servermanually” on page 95.

About this task

The jpa-2.0 feature provides support for applications that useapplication-managed and container-managed JPA written to the JPA 2.0specification. The support is built on top of Apache OpenJPA with extensions tosupport the container-managed programming model.

Procedurev Add the jpa-2.0 feature to the server.xml file.v Add persistence context and persistence unit definitions to the web.xml file.

For example:<persistence-context-ref>

<persistence-context-ref-name>example/em</persistence-context-ref-name><persistence-unit-name>ExamplePersistenceUnit</persistence-unit-name>

</persistence-context-ref>

<persistence-unit-ref><persistence-unit-ref-name>example/emf</persistence-unit-ref-name><persistence-unit-name>ExamplePersistenceUnit</persistence-unit-name>

</persistence-unit-ref>

v Configure access to the entity manager.For example:Context ctx = new InitialContext();UserTransaction tran = (UserTransaction) ctx.lookup("java:comp/UserTransaction");tran.begin();EntityManager em = (EntityManager) ctx.lookup(java:comp/env/example/em");Thing thing = new Thing();em.persist(thing);tran.commit();

v Configure access to the entity manager factory.


For example:Context ctx = new InitialContext();EntityManagerFactory emf = (EntityManager) ctx.lookup(java:comp/env/example/emf");EntityManager em = emf.createEntityManager();EntityTransaction tx = em.getTransaction();tx.begin();Thing thing = new Thing();em.persist(thing);tx.commit();int id = thing.getId();em.close();

Deploying web services applications to the Liberty profileBy configuring Liberty features in the server.xml file, you can deploy web servicesapplications to the Liberty profile.

Deploying JAX-RS applications to the Liberty profileYou can use Java API for RESTful Web Services (JAX-RS) to develop services thatfollow Representational State Transfer (REST) principles. RESTful services arebased on manipulating resources. Resources can contain static or dynamicallyupdated data. By identifying the resources in your application, you can make theservice more useful and easier to develop. Liberty profile provides a Libertyfeature jaxrs-1.0 to support JAX-RS programming model.

Liberty profile: JAX-RSThis topic provides an overview of Java API for RESTful Web Services (JAX-RS) inthe Liberty profile.

Implementing JAX-RS web applicationsYou can use JAX-RS to develop services that follow Representational StateTransfer (REST) principles. Using JAX-RS, development of RESTful servicesis simplified.

For more information, see the WebSphere Application Server full profiletopic Implementing JAX-RS web applications.

Note: The following sections, and any subtopics are not relevant to theLiberty profile:v Configure the development environment

Additionally:v In Defining the URI patterns for resources in RESTful applications, the

context root value in the Liberty profile is either the name of the webmodule, or the user-defined context root found in the EAR file.

v In Assembling JAX-RS web applications, the content in the "About thistask" section is not relevant to the Liberty profile.

Using XML content in JAX-RS application requests and responsesXML is a common media format that RESTful services consume andproduce. To deserialize and serialize XML, you can represent requests andresponses by Java Architecture for XML Binding (JAXB) annotated objects.

For more information, see the WebSphere Application Server full profiletopic Using XML content in JAX-RS application requests and responses.



http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_implejaxrsapps

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_defresource_uri

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_assemble

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_xmlcontent

Using Atom content in JAX-RS application requests and responsesYou can use the Atom Syndication Format (Atom) to format web feeds,which communicate news and updates of episodic information aboutwebsites. Using Atom content in JAX-RS applications, you can takeadvantage of web content syndication that provides the samedecentralized, dynamic mechanisms for adding new metadata and contentsupported by RSS, but does so in a way that helps protect coreinteroperability between implementations.

For more information, see the WebSphere Application Server full profiletopic Using Atom content in JAX-RS application requests and responses.


Using custom entity formatsEven though the JAX-RS runtime environment includes several entityproviders for handling serialization from and deserialization to Java types,it does not support all possible media types. You can develop a customentity provider to handle binding Java types to message bodies.

For more information, see the WebSphere Application Server full profiletopic Using custom entity formats.


Using content negotiation to serve multiple content types in JAX-RS applicationsOne of the advantages of RESTful applications is the ability to returndifferent representations of resources. With Representational State Transfer(REST), clients and servers can exchange resources of the same media typeor use differing media types. Content negotiation enables clients andservers to agree on the content format that is used to exchange data.

For more information, see the WebSphere Application Server full profiletopic Using content negotiation to serve multiple content types in JAX-RSapplications .


Using JAX-RS context objects to obtain more information about requestsJAX-RS provides different types of context to resource classes andproviders. You can use context objects to access request information suchas discovering the HTTP headers that are sent as part of the request.Context objects also provide convenience methods for evaluating a requestand building an appropriate response.

For more information, see the WebSphere Application Server full profiletopic Using JAX-RS context objects to obtain more information aboutrequests.



http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_atomcontent

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_customentityformats

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_contentnegotiation

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_contentnegotiation

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_contextobjects

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_contextobjects

Using handlers to enhance request and response processingYou can implement handlers on the server-side of a JAX-RS application toenhance request and response processing.

For more information, see the WebSphere Application Server full profiletopic Using handlers to enhance request and response processing


Using multipart content in JAX-RS application requests and responsesUsing multipart messages, servers and clients can transmit multiplemessages using a single message. Multipart messages are useful when boththe client and server need to send multiple requests but want to save thecost of sending and receiving entire HTTP request and responses for eachpart.

For more information, see the WebSphere Application Server full profiletopic Using multipart content in JAX-RS application requests andresponses.


Using multipart/form-data content in JAX-RS application requests andresponses

A frequently used content type for submitting files through an HTML formis multipart/form-data. The JAX-RS implementation from IBM greatlysimplifies the processing of such data by automatically splitting the partsand automatically decoding them. If such automatic processing is notwanted, the resource can instead receive the parts in an object soprocessing of the parts is under the complete control of the resourcemethod.

For more information, see the WebSphere Application Server full profiletopic Using multipart/form-data content in JAX-RS application requestsand responses.


Implementing secure JAX-RS applicationsThe JAX-RS runtime environment from IBM is driven by a servlet derivedfrom the Apache Wink project. Within the WebSphere Application Serverenvironment, the lifecycle of servlets is managed in the web container.Therefore, the security services offered by the web container are applicableto REST resources that are deployed in WebSphere Application Server.

For more information, see the WebSphere Application Server full profiletopic Implementing secure JAX-RS applications.

Note: The following sections, and any subtopics are not relevant to theLiberty profile:v Configure the development environmentv Secure JAX-RS resources using annotations


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_handlers

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_multipartcontent

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_multipartcontent

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_multipart_formdata

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_multipart_formdata

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_impl_securejaxrs

v (optional) Secure JAX-RS clients using SSLv Administer the secure JAX-RS application

Additionally:v In Securing JAX-RS applications within the web container, the reference

to the directory structure for the AddressBookApp deployment descriptoris not relevant to the Liberty profile. After you install theAddressBookApp application in the Liberty profile, the WEB-INF\web.xmlfile of the web application looks like the example provided in the link.

v In the Liberty profile, the default context root is the name of the WARfile. For more information about options when configuring context roots,see “Deploying a web application to the Liberty profile” on page 529.

Using WADL to generate service documentationWeb Application Description Language (WADL) is a description languagefor HTTP-based applications. It is currently a World Wide Web Consortium(W3C) Member Submission. WADL can be used by programs to giveinformation about the service in a machine-processable method. Forinstance, you can use an XSLT document to transform the WADLdocumentation by using a custom XSLT and an XSLT processor.

For more information, see the WebSphere Application Server full profiletopic Using WADL to generate service documentation.


Using the Apache Wink REST client inside server applications to issue requestsYou can use the Apache Wink REST client as a client that can be run tosend requests to your JAX-RS application.

For more information, see the WebSphere Application Server full profiletopic Using the Apache Wink REST client inside server applications toissue requests.

Note: Any reference to thin client, unmanaged client, or administrativeconsole are not relevant to the Liberty profile.

Note: If you use the jaxrs-1.1 feature, you must specify the servlet-3.0 orjsp-2.2 features separately.

Deploying a messaging application to the Liberty profile

To deploy messaging applications that use the Java Messaging Service (JMS), youadd the wasJMSServer-1.0 and wasJMSClient-1.1 features to the server.xml file.You must also define the connection factory and destination properties.

Before you begin

Ensure that you have created a Liberty profile server on which you want to deploythe messaging application that uses JMS. For more information, see “Creating aLiberty profile server manually” on page 95.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_impl_securejaxrs_webcont

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_wink_wadl

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_impl_client

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twbs_jaxrs_impl_client

About this task

The wasJMSServer-1.0 feature provides support for applications that use JavaMessaging Service 1.1 specifications.

Procedurev Add the wasJMSServer-1.0 and wasJMSClient-1.1 features to the server.xml file.

<featureManager><feature>wasJMSServer-1.0</feature><feature>wasJMSClient-1.1</feature>

</featureManager>

v Add the destination definitions to the server.xml file.<messagingEngine id="defaultME"><queue id="QUEUE1"> </queue>

</messagingEngine>

v Add the connection factory definitions to the server.xml file.For Point-to-Point domain:

<jmsQueueConnectionFactory jndiName="jndi_JMS_BASE_QCF"><properties.jms.QueueConnectionFactory providerEndPoint="localhost:7276:BootStrapBasicMessaging" />

</jmsQueueConnectionFactory>

<jmsQueue jndiName="jndi_INPUT_Q"><properties.jms.Queue queueName="QUEUE1" />

</jmsQueue>

For Publish-Subscribe domain:<jmsTopicConnectionFactory jndiName="eis/tcf"><properties.jms.TopicConnectionFactory clientID="defaultID" /></jmsTopicConnectionFactory>

<jmsTopic jndiName="eis/topic1"><properties.jms.Topic topicName="value1" />

</jmsTopic>

v Add the jmsComms-1.0 feature to enable the JMS messaging engine to accept theremote incoming messaging connections from TCP/IP (with and without SSL).<jmsCommsEndpoint id="InboundJmsCommsEndpoint"host="*"jmsPort="7276"jmsSSLPort="9100">

</jmsCommsEndpoint>


Chapter 11. Monitoring the Liberty profile

You can use the monitor-1.0 feature to monitor the server runtime environment.

About this task

To enable monitoring for your Liberty profile, you add monitor-1.0 Liberty featurein the server.xml file.

The monitor-1.0 feature provides monitoring support for user runtimecomponents.v JVMv Web applicationsv Thread pool

v JAX-WS endpoints

v Session management

For more details, see “Liberty features” on page 14.

Procedure1. Add the monitor-1.0 feature and the monitoring starts.2. Monitoring data is reported as standard MXBeans.3. You can use JConsole to connect to JVM and look at the performance data by

clicking each attribute of the MXBean.The MXBeans for monitoring are as following:v WebSphere:type=JvmStats

v WebSphere:type=ServletStats,name=*

v WebSphere:type=ThreadPoolStats,name=Default Executor

v org.apache.cxf:type=WebServiceStats,service=*,port=*

v WebSphere:type=SessionStats,name=*

4. Optional: The same data is available with traditional PMI Mbean (Perf MBean).

Liberty profile: JVM monitoringThis topic provides an overview of the JvmStats MXBean for JVM monitoring inthe Liberty profile.

Each Liberty profile instance has one JvmStats MXBean.

The ObjectName for identifying JVM MXBean is:WebSphere:type=JvmStats

Available Instances = 1

This MXBean is responsible for reporting performance of JVM. Following attributesare available for JVM.

Heap Information


v Amount of free heap available (in Bytes)v Total used memory by JVM for from heap (in Bytes)v Heap size (in Bytes)

.

CPU Information

v Percentage of CPU consumed by this JVM

.

Garbage Collection (GC) Information

v Number of times that GC happened since JVM startedv Total time taken by GC activity

.

General Information

v Time in milliseconds since JVM has started.

.

Counter definitions (Attributes to MXBean)

v Heap: Heap size used for current JVM.v FreeMemory: Free heap available for current JVM.v UsedHeap: Used heap for current JVM.v ProcessCPU: Percentage of CPU used by JVM process.v GcCount: Number of times GC has happened since JVM starts.v GcTime: Total accumulated value of GC time.v UpTime: Time in milliseconds, since JVM has started.

.

Management InterfaceThe management interface of JVM monitoring iscom.ibm.websphere.monitor.jmx.JvmMXBean. You can use the managementinterface to obtain a proxy object. See “Liberty profile: Examples ofaccessing MBean attributes and operations” on page 396.

For more information about the management interface, see the Java APIdocument for the Liberty profile. The Java API documentation for eachLiberty profile API is available in a separate JAR file under the/dev/ibm-api/javadoc directory of the server image.

Liberty profile: Web application monitoringThis topic provides an overview of servlet MXBean for web application monitoringof the Liberty profile.

Performance data is available for each Servlet in the Web Application. Each servlethas its own MXBean.

The ObjectName for identifying each servlet MXBean is:WebSphere:type=ServletStats,name=<AppName>.<ServletName>

For example:WebSphere:type=ServletStats,name=snoop.Alpine Snoop ServletWebSphere:type=ServletStats,name=MyApp.MyServlet


This MXBean is responsible for reporting ServletStats for each servlet. Followingkey data is available for ServletStats MXBean:v Request Countv Response Timev Servlet Namev Application Name


v AppName: Name of the application.v ServletName: Name of the servlet.v RequestCount: Number of hits to this servlet.v ResponseTime: Average response time (nano-seconds).v Description: Description of counter.v RequestCountDetails: RequestCount details including last time stamp.v ResponseTimeDetails: ResponseTime details including number of

snapshot taken, min, max values and so on.

.

Management InterfaceThe management interface of web application monitoring iscom.ibm.websphere.webcontainer.ServletStatsMXBean. You can use themanagement interface to obtain a proxy object. See “Liberty profile:Examples of accessing MBean attributes and operations” on page 396.


Liberty profile: ThreadPool monitoringThis topic provides an overview of ThreadPool MXBean for thread pool monitoringin the Liberty profile.

All Web Requests executes in the thread pool, named Default Executor threadpool. You can monitor the usage of Default Executor thread pool usingThreadPoolMXBean.

The ObjectName for identifying MXBean for thread pool is :WebSphere:type=ThreadPoolStats,name=Default Executor

Key Performance data available for ThreadPool are:v Threads in the pool which represents the pool size.v Active threads which are serving requests.

Attributes for ThreadPool

v ActiveThread

v PoolSize

v PoolName (Only supports Default Executor thread pool)

.

Chapter 11. Monitoring the Liberty profile 539

Management InterfaceThe management interface of ThreadPool monitoring iscom.ibm.websphere.monitor.jmx.ThreadPoolMXBean. You can use themanagement interface to obtain a proxy object. See “Liberty profile:Examples of accessing MBean attributes and operations” on page 396.


Liberty profile: JAX-WS monitoring

This topic provides an overview of the endpoint MXBean for JAX-WS monitoringof the Liberty profile.

Performance data is available for each endpoint and operation in the JAX-WSapplication. Each web service endpoint has its own MXBean.

The ObjectName for identifying each endpoint MXBean might be in one of thefollowing formats:

org.apache.cxf:bus.id=<bus.name>,type=Performance.Counter.Server,service="<NameSpace><ServiceName>",port="<PortName>"org.apache.cxf:bus.id=<bus.name>,type=Performance.Counter.Client,service="<NameSpace><ServiceName>",port="<PortName>"

For example:org.apache.cxf:bus.id=JaxWsLibertyDemo-Server-Bus,type=Performance.Counter.Server,

service="{http://jaxws.samples/}SimpleEchoService",port="SimpleEchoPort“org.apache.cxf:bus.id=JaxWsLibertyDemo-Server-Bus,type=Performance.Counter.Client,

service="{http://jaxws.samples/}SimpleEchoService",port="SimpleEchoPort"

This MXBean is responsible for reporting the web service status of each endpointand operation.


v AvgResponseTime: Average response time (millisecond).v MaxResponseTime: Maximum response time (millisecond).v MinResponseTime: Minimum response time (millisecond).v NumInvocations: Number of invocations to this endpoint or operation.v NumChekedApplicationFaults: Number of checked application faults.v NumLogicalRuntimFaluts: Number of logical runtime faults.v NumRuntimeFaults: Number of runtime faults.v NumUnCheckedApplicationFaults: Number of unchecked application

faults.v TotalHandlingTime: Total response handling time (millisecond)..

.

Management InterfaceThe management interface for web service application monitoring isorg.apache.cxf.management.counters.ResponseTimeCounterMBean. You canuse the management interface to obtain a proxy object. See “Liberty profile:Examples of accessing MBean attributes and operations” on page 396.


For more information about theorg.apache.cxf.management.counters.ResponseTimeCounterMBean, see theApache CXF Javadoc.

Liberty profile: Sessions monitoring

You can use the Session MXBean for Session monitoring of the Liberty profile.

Performance data of sessions for each application is made available.

Sessions associated with a single web application have their own MXBean (that is,one sessionStats MXBean for each web application).

The ObjectName for identifying each Session MXBean is:WebSphere:type=SessionStats,name=*

For example:WebSphere:type=SessionStats,name=default_host/trade_liteWebSphere:type=SessionStats,name=default_host/moneybank

This MXBean is responsible for reporting Session Stats for each webapplication.Following key data are available for Session MXBean:v Create Countv Live Countv Active Countv InvalidatedCountv InvalidatedCountbyTimeout

Counter definitions (the attributes of the MXBean)

v Create Count: Total number of Sesisons created.v Live Count: Total number of Live Session.v Active Count: Total number of Active Sessions.v InvalidatedCount: Totall number of sessions which were invalidated.v InvalidatedCountbyTimeout: Total number of sessions invalidated via

timeout.

.

Chapter 11. Monitoring the Liberty profile 541

http://cxf.apache.org/javadoc/latest/

Chapter 12. Tuning the Liberty profile

This topic describes the tunable parameters and attributes of the Liberty profile.

About this task

The Liberty profile supports different attributes in the server.xml file to influenceapplication performance. You can use these parameters and attributes to achievebetter performance.

Procedurev Tune the JVM.

Tuning the JVM is a most important tuning step whether you configure adevelopment or production environment. When you tune the JVM for theLiberty profile, use the jvm.options file in the ${server.config.dir} directory.You can specify each of the JVM arguments that you want to use, one option perline. See “Customizing the Liberty profile environment” on page 352 for moreinformation. An example of jvm.options file is as follows:-Xms50m-Xmx256m

For a development environment, you might be interested in faster server startup,so consider setting the minimum heap size to a small value, and the maximumheap size to whatever value is needed for your application. For a productionenvironment, setting the minimum heap size and maximum heap size to thesame value can provide the best performance by avoiding heap expansion andcontraction.

v Tune transport channel services.The transport channel services manage client connections, I/O processing forHTTP, thread pools, and connection pools. For applications on the Libertyprofile, the following attributes are available for different elements that can beused to improve runtime performance, scalability, or both. For each of theseattributes, see “Liberty profile: Configuration elements in the server.xml file” onpage 97.

maxKeepAliveRequests of httpOptionsThis option specifies the maximum number of persistent requests thatare allowed on a single HTTP connection if persistent connections areenabled. A value of -1 means unlimited. This option supports lowlatency or high throughput applications, and SSL connections for use insituations where building up a new connection can be costly. Here is anexample of how you code this option in the server.xml file:<httpOptions maxKeepAliveRequests="-1" />

coreThreads of executorThis option specifies the core number of threads to associate with theexecutor of the thread pool. The number of threads associated with theexecutor will quickly grow to this number. If this value is less than 0, adefault value is used. This default value is calculated based on thenumber of hardware threads on the system.

Tip: Start your tuning with coreThreads="5" for each hardware threador logical processor. For example, for a two-core SMT-4 machine, whichrepresents eight logical processors, use coreThreads="40" as a starting


point.Here is an example of how you code this option in the server.xml file:<executor name="LargeThreadPool" id="default" coreThreads="40" maxThreads="80"

keepAlive="60s" stealPolicy="STRICT" rejectedWorkPolicy="CALLER_RUNS" />

maxPoolSize of connectionManagerThis option specifies the maximum number of physical connections forthe connection pool. The default value is 50. The optimal setting heredepends on the application characteristics. For an application in whichevery thread obtains a connection to the database, you might start witha 1:1 mapping to the coreThreads attribute. Here is an example of howyou code this option in the server.xml file:<connectionManager ... maxPoolSize="40" />

purgePolicy of connectionManagerThis option specifies which connections to destroy when a staleconnection is detected in a pool. The default value is the entire pool. Itmight be better to purge only the failing connection. Here is an exampleof how you code this option in the server.xml file:<connectionManager ... purgePolicy="FailingConnectionOnly" />

numConnectionsPerThreadLocal of connectionManagerThis option specifies the number of database connections to cache foreach executor thread. This setting can provide a major improvement onlarge multi-core (8+) machines by reserving the specified number ofdatabase connections for each thread.

Using thread local storage for connections can increase performance forapplications on multi-threaded systems. When settingnumConnectionsPerThreadLocal to 1 or more, these connections perthread are stored in thread local storage. When usingnumConnectionsPerThreadLocal, consider two other values:– The number of application threads– The connection pool maximum connections

For best performance, if you have n applications threads, set maximumpool connections to at least n times the value ofnumConnectionsPerThreadLocal attribute. For example, if you use 20application threads, set the maximum pool connections to 20 or more; Ifyou set the value of numConnectionPerThreadLocal attribute as 2 andthere are 20 application threads, set the maximum pool connection to 40or more. Here is an example of how you code this option in theserver.xml file:<connectionManager ... numConnectionsPerThreadLocal="1" />

statementCacheSize of dataSourceThis option specifies the maximum number of cached preparedstatements per connection. To set this option, complete the followingprerequisite:– Review the application code (or an SQL trace gathered from the

database or database driver) for all unique prepared statements.– Ensure the cache size is larger than the number of statements.

Here is an example of how you code this option in the server.xml file:<dataSource ... statementCacheSize="60" >

isolationLevel of dataSourceThe data source isolation level specifies the degree of data integrity andconcurrency, which in turns controls the level of database locking. Four


different options are available as following in order of best performing(least integrity) to worst performing (best integrity).

TRANSACTION_READ_UNCOMMITTEDDirty reads, non-repeatable reads, and phantom reads can occur.

TRANSACTION_READ_COMMITTEDDirty reads are prevented; non-repeatable reads and phantomreads can occur.

TRANSACTION_REPEATABLE_READDirty reads and non-repeatable reads are prevented; phantomreads can occur.

TRANSACTION_SERIALIZABLEDirty reads, non-repeatable reads, and phantom reads areprevented.

Here is an example of how you code this option in the server.xml file:<dataSource ... isolationLevel="TRANSACTION_READ_COMMITTED">

Chapter 12. Tuning the Liberty profile 545

Chapter 13. Liberty profile: Troubleshooting tips

Tips for troubleshooting the Liberty profile.

To help you identify and resolve problems, the product has a unified loggingcomponent. See “Liberty profile: Trace and logging” on page 552. You can also usethe IBM Support Assistant Data Collector (ISADC) command tool in the${wlp.install.dir}/bin directory to quickly collect diagnostic files, such as logfiles, configuration files or to run traces.

If you receive an exception message, information about the message is available in“Liberty profile: Messages” on page 571.


Distributed operating systems Details of the main known restrictions that apply whenusing the Liberty profile are provided in the following two topics:v “Liberty profile: Runtime environment known restrictions” on page 566.v “Liberty profile: Developer Tools known restrictions” on page 570.

Here is a set of tips to help you troubleshoot commonly experienced problems:v Troubleshooting JDKsv “Troubleshooting security”v “Troubleshooting LDAP” on page 549v “Troubleshooting SSL” on page 550

v “Troubleshooting JAX-WS” on page 551v

vDistributed operating systems “Applying fix packs and interim fixes to an archive

install” on page 552

Check that your JDKs are at a supported level

If you experience problems that are not readily explained, check that the JDKs youare using are compliant with Java Version 6 or later, and are at a current servicelevel. See “Minimum supported Java levels” on page 566.

Troubleshooting security

This section describes some common security problems and solutions you canchoose.

SESN0008E: A user authenticated as anonymous has attempted to access asession owned by user:LdapRegistry/cn=steven,o=myCompany,c=US.

This error happens when an unauthenticated user tries to access a sessioncreated by an authenticated user. Session security that is enabled by defaultprevents unauthorized access of the sessions. Only the user who created asession can access it. See session security for more information.

This error can happen when you use a JSP (login.jsp for example) foryour form-login and the SSO token sent by the browser is expired. Because


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=ttrb_isadcstart

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=rpersecg

the SSO token is expired, the user is prompted to log in again using thelogin.jsp page configured for the form-login. The jsp page, by default,tries to get a session. This session was originally created by the user whosetoken is expired. However, the token is expired and the user is notauthenticated, no credentials are established when accessing this sessionthat results in this error.To avoid this error, restart the browser that starts a new session, orconfigure the login.jsp file to not create the session by default. If youchoose to update the login.jsp file, set <%@ page session="false" %>.

CWWKS9104A: Authorization failed for user {0} while invoking {1} on {2}. Theuser is not granted access to any of the required roles: {3}.

This error occurs when you do not have authorization to the roles requiredby the application. Make sure that the user or the group it belongs to ismapped to at least one of the roles that are mentioned in the errormessage. A user-to-role mapping defined in the ibm-application-bnd.xmi/xml file takes precedence over a mapping defined in the server.xml file.Check both resources to ensure that the correct mapping is defined. See“Configuring authorization for applications on the Liberty profile” on page472.

CWWKZ0013E: It is not possible to start two applications called {0} followed byunexpected security behavior and error messages such as CWWKS9104A.

This error occurs when you specify your application in both theserver.xml by using theapplication element and in the dropins folder. Asa result, the application is attempted to be installed twice and the securityconfiguration in the server.xml file might or might not take effect. To fixthis, you must remove your application from the dropins folder and copyit to another directory. If you have to leave it in the dropins folder, youmust disable the application monitoring by using the following code inyour server.xml file:<applicationMonitor dropinsEnabled="false"/>

An unauthenticated user was able to access my servlet or JSP.A user with a principal of UNAUTHENTICATED (or the unauthenticated SAFuser on z/OS) is created when authentication fails or when your servlet orJSP is unprotected. An unauthenticated user can access your servlet or JSPif you do not define any security constraints or if you map the EVERYONEspecial subject to the role required by your application. Review theuser-to-role mappings in the ibm-application-bnd.xmi/xml and server.xmlfiles. Take one of the following options:v If your servlet or JSP is unprotected, add security constraints to the

deployment descriptor of your application. See “Liberty profile:Authentication” on page 29.

v If you do not want any unauthenticated user to access your application,remove the EVERYONE special subject from the mapping for that role. See“Configuring authorization for applications on the Liberty profile” onpage 472.

v If a certain user cannot be authorized to your servlet or JSP, review whois mapped to that role by examining the ibm-application-bnd.xmi/xmland server.xml files. You can map a role to a user, group, or specialsubject. If your role is mapped to the EVERYONE special subject, any useris granted access. If your role is mapped to the ALL_AUTHENTICATEDspecial subject, any authenticated user is granted access. Remove thesespecial subjects if you want to further limit who can access your servletor JSP. Finally, check what group the user belongs to. Although the usermight not have explicit access, the group might be mapped to the role.


In this case, remove the user from the authorized group or remove thegroup from role mapping. See “Configuring authorization forapplications on the Liberty profile” on page 472.

Single sign-on (SSO) does not work.If SSO does not work, make sure that the different Liberty profile serversthat use the same LTPA keys, password, and ssoCookieName attribute ofwebAppSecurity element have the same Universal Time (UTC) and sharethe same user registry. Also, if the token expires or if the cookie is sentfrom a web browser after changing the user registry in a manner that isinconsistent, like modifying the realm or removing the user the cookierepresents, the SSO fails and the user is prompted to enter the credentialinformation again. See “Customizing SSO configuration using LTPAcookies for the Liberty profile” on page 468.

Debugging security public APIs.WSSecurityHelper and RegistryHelper are loaded even if security is notenabled, for example, if a security feature - appSecurity-1.0,appSecurity-2.0 or zosSecurity-1.0 - is not specified. If security is notenabled, then WSSecurityHelper.isServerSecurityEnabled() andWSSecurityHelper.isGlobalSecurityEnabled() methods both return false,and RegistryHelper.getUserRegistry() method returns null.

Other security public API classes might not be loaded if security is notenabled. If you try to access these classes and call a method on one ofthese classes, you might get a java.lang.NoClassDefFoundError exception.

To avoid getting java.lang.NoClassDefFoundError exceptions, you mustfirst test to see whether security is enabled by calling theWSSecurityHelper.isServerSecurityEnabled() orWSSecurityHelper.isGlobalSecurityEnabled() class, and then call othersecurity public API classes only when security is enabled. See “Libertyprofile: Security public APIs” on page 43 for examples of this codingtechnique.

Note: This behavior is different from the full profile. In full profile, allclasses are always loaded regardless of whether security is enabled or not.

Troubleshooting LDAP

This section describes some common LDAP problems and solutions you canchoose.

FFDC1015I: An FFDC Incident has been created:"javax.naming.ServiceUnavailableException: myldapserver.mycompany.com:636;socket closed com.ibm.ws.security.registry.ldap.internal.LdapRegistry 298

This message in messages.log indicates that the configured LDAP servercannot be reached. Check your LDAP server to verify that it is runningand that its IP address can be accessed from the Liberty profile server.

The javax.naming.CommunicationException: simple bind failed:myldapserver.mycompany.com:636 [Root exception isjavax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.g: PKIX path buildingfailed: java.security.cert.CertPathBuilderException: unable to find validcertification path to requested target]

If you enable SSL on your LDAP server without copying the signer of theLDAP server into the truststore referenced in the LDAPSSLSettings element,

Chapter 13. Liberty profile: Troubleshooting tips 549

a connection with the LDAP server fails with an SSL handshake error.Make sure that you copy the signer of the LDAP server into yourtruststore.

The javax.naming.CommunicationException: myldapserver.mycompany.com:389[Root exception is java.net.BindException: Address already in use: connect]

This message might appear in the FFDC logs and indicates that the usablesockets on the local server are exhausted, which can result in a failurewhen connecting to your LDAP server. Make sure that the socket is notused and try again.

CWWKS1100A: Authentication did not succeed for user ID xxxxx. An invaliduser ID or password was specified

This FFDC exception might happen on the server even though the usermentioned in the message above is a valid user on the LDAP server underheavy load. With the LDAP configuration, you can add thereuseConnection=false property or disable it by using the developer tools.To fix the problem, set this property to the default value of true.

Troubleshooting SSL

This section describes some common SSL problems and solutions you can choose.

CWWKS9105E: Could not determine the SSL port for automatic redirection.This error occurs when you try to access an application that redirects to anSSL port and the SSL port is not available. The port might not be availablebecause of a missing SSL configuration or some error in the SSLconfiguration definition. Check the SSL configuration in the server.xml fileto make sure that it exists and is correct. See “Securing communicationswith the Liberty profile” on page 65.

FFDC1015I: An FFDC Incident has been created:"java.lang.IllegalArgumentException: Unknown, incomplete configuration:missing id field com.ibm.ws.config.internal.cm.ManagedServiceFactoryTrackeraSyncReadNupdate. Exception thrown while trying to read configuration andupdate ManagedServiceFactory. Exception = java.lang.IllegalArgumentException:Unknown, incomplete configuration: missing id field" atffdc_12.04.18_16.09.42.0.log

This error occurs when a keystore element exists in the configurationwithout an ID field. If you use a minimal SSL configuration, set the IDfield to defaultKeyStore.

You might get an exception if using a LDAP user registry withsslEnabled and a sslRef value is not specified.

For example, a configuration has sslEnable set to true but there is not asslRef value, as shown in the following example:<ltldapRegistry id="ldap" realm="SampleLdapIDSRealm"host="ccwin12.austin.ibm.com" port="636" ignoreCase="true"baseDN="o=ibm,c=us"bindDN="cn=root"bindPassword="rootpwd"ldapType="IBM Tivoli Directory Server"idsFilters="ibm_dir_server"sslEnabled="true"searchTimeout="8m" />

You must enter a sslRef value. If you are using a minimal SSLconfiguration that is similar to the following:


<ltkeyStore id="defaultKeyStore" location="key.jks"password="mypassword" />

the sslRef field should be set to defaultSSLConfig.

If a custom SSL configuration is configured, the name of that configurationshould be placed in the sslRef field.

Troubleshooting JAX-WS

This section describes some common JAX-WS problems and solutions you canchoose.

The org.apache.cxf.bus.extension.ExtensionException occurred when deployingweb services application on the Liberty Profile.

If your application has CXF libraries and configurations embedded alreadyand you want to deploy the application to the Liberty Profile, you mustmake sure that the jaxws-2.2 server feature is disabled by removing thefeature from the server.xml file.

The java.lang.NoClassDefFoundError exception occurred when running IBMfastpath with the Oracle JVM.

To use IBM fastpath Java Architecture for XML Binding (JAXB), you canconfigure the com.ibm.xml.xlxp.jaxb.opti.level custom property tocontrol whether optimization methods are enabled for JAXB unmarshalling(deserialization) and marshalling (serialization). If you are experiencing thejava.lang.NoClassDefFoundError exception when running IBM fastpathJAXB with the Oracle JVM, you can change the value ofcom.ibm.xml.xlxp.jaxb.opti.level property to 0 to turn off theoptimization. For example, you can use the-Dcom.ibm.xml.xlxp.jaxb.opti.level=0 property in the command line, oradd the following line to the jvm.options file:# Turn off the JAXB optimization-Dcom.ibm.xml.xlxp.jaxb.opti.level=0

See more information of the com.ibm.xml.xlxp.jaxb.opti.level propertyon the Java virtual machine custom properties page.

The java.lang.NoClassDefFoundError : com.ibm.CORBA.iiop.ORB exceptionoccurred when running the full profile thin client with the Oracle JVM.

This error occurs when you try to run the full profile thin client with theOracle JVM and the jaxws-2.2 feature is already enabled on the Libertyprofile. To resolve this problem, you can use the-Dcom.ibm.websphere.thinclient=true property when running the fullprofile thin client as follows:

java -Dcom.ibm.websphere.thinclient=true-cp <classpath_entries_including_tWAS_thinclient_jar> <WebServicesClientEntryClass> <any_more_parameters>

See the similar information of the com.ibm.websphere.thinclient propertyon the PM39777: ADMINISTRATIVE THIN CLIENT USING SOAPCONNECTOR AND SUN JDK DOES NOT WORK page.

An Empty file returned when retrieving binary files from an MTOM service to aMTOM client.

This scenario happens when a MTOM client sent binary files successfullyto an MTOM service, but an empty file is returned when retrieving thesame binary files back from the MTOM service.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=xrun_jvm

http://www-01.ibm.com/support/docview.wss?uid=swg1PM39777

http://www-01.ibm.com/support/docview.wss?uid=swg1PM39777

As a workaround, you can create a new DataHandler and initialize theDataHandler by filling the content of the binary file. For example, use aFileDataStore object to read from I/O and return the newly createdDataHandler back, and then pass the DataHandler to other web services....File f = new File("received_image");if (f.exists()) {f.delete();}

FileOutputStream fos = new FileOutputStream(f);img_in.writeTo(fos);

FileDataSource fos_out = new FileDataSource(f);DataHandler img_out = new DataHandler(fos_out);return img_out;...

The javax.xml.ws.soap.SOAPFaultException: Unmarshalling Error occurred whenusing XMLGregorianCalendar in xsd:gMonth format with the Oracle JVM.

This error occurs when you use the XMLGregorianCalendar class to storegMonth format constants as part of your SOAP request on client side andthe jaxws-2.2 feature is enabled on the Liberty profile with the OracleJVM. The root cause is that the Oracle JVM supports the new standardformat --MM for the xsd:gMonth type while the latest JAXB RI (ReferenceImplementation) only supports the format of --MM--.

To resolve this problem, you can change the Oracle JVM to the IBM JVMfor both the client side and the server side applications.

The java.io.FileNotFoundException occurred when resolving WSDL filesspecified by the wsdlLocation attribute.

This error occurs when you specify the WSDL file as in the codewsdlLocation = "file:/WEB-INF/wsdl/a.wsdl" and the WSDL file ispackaged within your application. If you want to refer to the WSDL filethat is packaged in your application, you must use relative URIs for thewsdlLocation attribute defined in the @WebService, @WebServiceProvider,@WebServiceClient or @WebServieRef annotation.

The relative URI for the wsdlLocation attribute must be one of thefollowing values:v wsdlLocation = "/WEB-INF/wsdl/a.wsdl"

v wsdlLocation = "WEB-INF/wsdl/a.wsdl"


Applying fix packs and interim fixes to an archive install

If you installed your Liberty profile runtime environment from an archive file,rather than by using Installation Manager, you must take special measures whenyou apply service updates. For more information, see “Applying a fix pack to aLiberty profile archive installation” on page 84 and “Applying an interim fix to aLiberty profile archive installation” on page 86.

Liberty profile: Trace and loggingThe product has a unified logging component. It provides base implementations oftrace and FFDC services, for runtime code and for your code, to gather debuginformation.

The trace and FFDC implementations both apply an initial configuration duringstatic initialization. You can modify this default initial configuration by specifying


properties in the server configuration files (see “Administering the Liberty profilemanually” on page 351) or bootstrap.properties file (see “Specifying Libertyprofile bootstrap properties” on page 95).

Messages are written to stdout as well as to the defined trace destination. OSGilogging output is intercepted and output through the trace support. There is alsointerception of java.util.logging output.

Trace configuration

The logging service can be controlled through the server configuration.Occasionally you need to set logging properties so they can take effect before theserver configuration files are processed; in this case you set them in thebootstrap.properties file instead of the server configuration. You do not usuallyneed to do this to get logging from your own code, which is loaded after serverconfiguration processing, but you might need to do this to analyze problems inearly server start or configuration processing.

Logging properties can be set in either bootstrap.properties or server.xml file.You use attributes in the server.xml file, or use equivalent properties in thebootstrap.properties file. Any settings in the bootstrap.properties file are usedfrom the time the server reads the bootstrap.properties file until the time theserver.xml file is processed. If the logging properties in the bootstrap.propertiesfile are not replaced or reset in the server.xml file, the property values in thebootstrap.properties file will continue to be used.

If you set logging attributes in the server.xml file, you might want to set thecorresponding logging properties in the bootstrap.properties file to the samevalue to avoid changes in configuration between startup time and runtime.

Note: If no logging properties are set in the bootstrap.properties file, the serverwill start the logging system using the default logging settings.

Table 30. Logging properties for the Liberty profile. Column 1 contains attributes that can beset in the server.xml file. Column 2 contains equivalent properties that can be used in thebootstrap.properties file. Column 3 provides description of each logging property.

Attribute Equivalent property Description

logDirectory com.ibm.ws.logging.log.directory

This attribute sets the directory for alllog files, including FFDC.

maxFileSize com.ibm.ws.logging.max.file.size

The maximum size (in MB) that a logfile can reach before being rolled. TheLiberty profile runtime only doessize-based log rolling. To disable thisattribute, set the value to 0. Themaximum file size is approximate.

maxFiles com.ibm.ws.logging.max.files

If an enforced maximum file sizeexists, this setting is used todetermine how many of each log fileare kept. This setting also applies tothe number of exception logs thatsummarize exceptions occurred onany given day). So if this number is10, you might have 10 message logs,10 trace logs, and 10 exceptionsummaries in the ffdc/ directory.


Table 30. Logging properties for the Liberty profile (continued). Column 1 containsattributes that can be set in the server.xml file. Column 2 contains equivalent propertiesthat can be used in the bootstrap.properties file. Column 3 provides description of eachlogging property.

Attribute Equivalent property Description

consoleLogLevel com.ibm.ws.logging.console.log.level

This filter controls the granularity ofmessages that go to the console.logfile. The valid values are INFO,AUDIT, WARNING, ERROR, andOFF. By default, the level is AUDIT.

messageFileName com.ibm.ws.logging.message.file.name

The message log has a default nameof messagel.log. This file alwaysexists, and contains INFO and other(AUDIT, WARNING, ERROR,FAILURE) messages in addition toSystem.out and System.err. This logalso contains time stamps and theissuing thread ID.

traceFileName com.ibm.ws.logging.trace.file.name

The trace.log file is only created ifadditional or detailed trace isenabled. stdout is recognized as aspecial value, and causes trace to bedirected to the original standard outstream.

traceSpecification com.ibm.ws.logging.trace.specification

The trace string is used to selectivelyenable trace. The default is *=info.

traceFormat com.ibm.ws.logging.trace.format

This attribute controls the format ofthe trace log. The default format forthe Liberty profile is ENHANCED.You can also use BASIC andADVANCED formats as in the fullprofile.

You can set logging properties in the server configuration file by selecting Loggingand Tracing in the Server Configuration view in the developer tools, or by addinga logging element to the server configuration file as follows:<logging traceSpecification="*=audit:com.myco.mypackage.*=debug"/>

For the full logging configuration reference, including the detailed format of thetraceSpecification property, see the logging element in “Liberty profile:Configuration elements in the server.xml file” on page 97.

Note: On all platforms, logs are written in the default system encoding.

v Windows On Windows systems, there are two types of encoding: OEM codepage, which is used for console output, and ANSI code page, which is used toread and write files. The console.log file uses the OEM code page, and all otherlogs use the ANSI code page.

vDistributed operating systems On all other platforms, all log files use the default

encoding.

Liberty profile: Timed operations and JDBC calls


You can use timed operations to generate a logged warning when certain JDBCcalls are operating slowly.

Overview

Distributed operating systems Timed operations help WebSphere Application Serveradministrators see, by way of a logged warning, when certain JDBC calls in theirapplication server are operating more slowly than expected.

Timed operations are disabled by default and are enabled by adding thetimedoperations-1.0 feature to the server.xml file.

The system looks for abnormal patterns in the execution times of several types ofJDBC calls, keeps track of multiple recent execution times, and computes the meanand standard deviation for each timed operation. Specific messages are logged sothat administrators know what is slow when an abnormal pattern is detected. Thetimed operation feature uses an exponentially weighted moving average, where themost recent durations have more weight than older durations. When computingthe moving average, a certain number of durations are excluded in order to avoida high variance during the warm-up period. The timed operations feature does notlog a warning if a single duration is too slow, but instead uses the Western Electricrules to decide if a warning should be logged. A warning is logged in thefollowing cases:v The most recent duration is either above or below the zone delimited by three

standard deviations from the moving average.v Two out of three consecutive durations fall beyond the zone delimited by two

standard deviations, either below or above the moving average.v Four out of five consecutive durations fall beyond the zone delimited by one

standard deviation, either below or above the moving average.v Eight consecutive durations are below or above the moving average.

This design allows the system to tolerate minor variances, such as variances fromperiodic garbage collection.

Periodically, the system generates a report to the logs that contains the ten longestJDBC timed operations. The frequency and enablement of this report isconfigurable in the server.xml file, with a default of once per day (24 hours).

To disable the generation of this report to the logs, add the following line to theserver.xml file:<timedOperation enableReport="false"/>

To change the frequency of the report to once every 12 hours, add the followingline to server.xml:<timedOperation reportFrequency="12"/>

You can also use the server dump command to get a full report of all timedoperations, grouped by type, and sorted within each group by expected duration.

The following example shows a sample logged message:[12/13/12 7:42:19:957 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W:The duration of 206ms for the timed operation websphere.datasource.execute:jdbc/exampleDS:insert into citiesvalues (’myHomeCity’, 106769, ’myHomeCounty’) unexpected based on the following data:[12/13/12 7:42:19:958 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W:Recent durations for this timed operation:[12/13/12 7:42:19:958 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: 206ms


[12/13/12 7:42:19:958 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: 206ms[12/13/12 7:42:19:958 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: 205ms[12/13/12 7:42:19:958 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: 204ms[12/13/12 7:42:19:958 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: 194ms[12/13/12 7:42:19:959 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: 181ms[12/13/12 7:42:19:959 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: 112ms[12/13/12 7:42:19:959 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: 111ms[12/13/12 7:42:19:959 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: Current mean: 151ms[12/13/12 7:42:19:959 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: Standard deviation: 45ms[12/13/12 7:42:19:959 CST] 00000028 com.ibm.ws.timedoperations.internal.TimedOperationImpl W TRAS0090W: This data shows thatthe most recent duration is above the zone delimited by 3 standard deviations from the moving average.

The following example shows a sample automatically generated report in the log:[12/13/12 7:42:29:509 CST] 0000001d com.ibm.wsspi.timedoperations.TimedOperationService I TRAS0094I:The following timed operations took the longest to run since the last report was generated:[12/13/12 7:42:29:509 CST] 0000001d com.ibm.wsspi.timedoperations.TimedOperationService I TRAS0095I:The longest timed operations for websphere.datasource.execute:[12/13/12 7:42:29:509 CST] 0000001d com.ibm.wsspi.timedoperations.TimedOperationService I TRAS0096I: Expected duration 194msfor websphere.datasource.execute:jdbc/exampleDS:insert into cities values (’myHomeCity’, 106769, ’myHomeCounty’)[12/13/12 7:42:29:509 CST] 0000001d com.ibm.wsspi.timedoperations.TimedOperationService I TRAS0096I: Expected duration 190msfor websphere.datasource.execute:jdbc/exampleDS:select county from cities where name=’myHomeCity’[12/13/12 7:42:29:509 CST] 0000001d com.ibm.wsspi.timedoperations.TimedOperationService I TRAS0096I: Expected duration 182msfor websphere.datasource.execute:jdbc/exampleDS:drop table cities[12/13/12 7:42:29:509 CST] 0000001d com.ibm.wsspi.timedoperations.TimedOperationService I TRAS0096I: with expected duration 151msfor websphere.datasource.execute:jdbc/exampleDS:insert into cities values (’myHomeCity’, 106769, ’myHomeCounty’)

Liberty profile: High Performance Extensible Logging (HPEL)

High Performance Extensible Logging (HPEL) is a log and trace facility that isprovided as a part of the product.

Overview

Note: The basic log and trace facility is enabled by default. To use HPEL you mustenable it.

Distributed operating systems HPEL provides a convenient mechanism for storing andaccessing log, trace, System.err, and System.out information produced by theapplication server or your applications. It is an alternative to the basic log andtrace facility, which provides the JVM logs and diagnostic trace files commonlynamed messages.log and trace.log.

HPEL log and trace storage

HPEL provides a log data repository, a trace data repository, and a text log file. Seethe following figure to understand how applications and the application serverstore log and trace information.


Log data repository

Trace datarepository

Text log

trace.log

console.log

messages.log

Application code Application code

com.xyz.abc.def( logger )

Log/Trace Service

Log/Trace data handler

Log/Trace service

Log/Trace handler

com.xyz.abc.ghi( logger )

root ( logger )

Tr SPI

com.xyz.abc( logger )

Legend

default logging framework

HPEL logging framework

com.ibm.ws( logger )

Service broker

HPEL

Default

WebSphere Application Server

Applications

HPEL log data repository

The log data repository is a storage facility for log records. Log data istypically intended to be reviewed by administrators. This includes anyinformation applications or the server write to System.out, System.err,OSGi logging service at level LOG_INFO or higher (including LOG_INFO,LOG_WARNING, and LOG_ERROR), or java.util.logging at level Detail orhigher (including Detail, Config, Info, Audit, Warning, Severe, Fatal, andany custom levels at level Detail or higher).

HPEL trace data repository

The trace data repository is a storage facility for trace records. Trace data istypically intended for use by application programmers or by theWebSphere Application Server support team. This includes any informationapplications or the server write to the OSGi logging service at levelLOG_DEBUG or java.util.logging at levels below level Detail (includingFine, Finer, Finest, and any custom levels below level Detail).

HPEL text log

The text log file is a plain text file for log and trace records. The text logfile is provided for convenience, primarily so that log content can be readwithout having to run the LogViewer command-line tool to convert the logdata repository content to plain text.


The text log file does not contain any content that is not also stored ineither the log data repository or trace data repository. You can disable thetext log to enhance server performance. The text log can be configured torecord trace content for debugging convenience.

Note: Writing trace to the text log is expensive from a performanceperspective.

Log and trace performance

Distributed operating systems HPEL has been designed and tested to significantlyoutperform the existing basic log and trace facility. One result is that theapplication server can run with trace enabled while causing less impact toperformance than tracing the same components using basic logging. Another resultis that applications that frequently write to the logs can run faster when usingHPEL. A number of factors contribute to the overall performance of HPEL loggingand tracing.

Log and trace events are each stored in only one place

Log events, System.out, and System.err are stored in the log datarepository. Trace events are stored in the trace data repository. If the textlog file is disabled, HPEL will only write log and trace content to theserepositories. Storing each type of event in one place ensures thatperformance is not wasted on redundant data storage.

Log events, and optionally trace events, are written to the text log filewhen it is enabled. Since this data is always also stored in the log data andtrace data repositories, the text log file content is redundant. The text log isconvenient for users who do not want to run the LogViewer command-linetool to see their logs and trace; but you can disable the text log if thisconvenience is not needed.

Data is not formatted unless it is needed

Formatting data for a user to read uses processor time. Rather than formatlog event and trace event data at run time, HPEL log and trace data isstored more rapidly in a proprietary binary representation. This improvesthe performance of the log and trace facility. By deferring log and traceformatting until the LogViewer is run, sections of the log or trace that arenever viewed are never formatted.

You can enable the text log file, which stores the log data and trace data inan already readable text format.

Note: Disable the text log when performance of your server is a keyconcern, or if the text log is not wanted.

Log and trace data is buffered before being written to disk

Writing large blocks of data to a disk is more efficient than writing thesame amount of data in small blocks. HPEL provides the capability tobuffer log and trace data before writing it to disk. By default, log and tracedata is stored in an 8 KB buffer before being written to disk. If the buffer isfilled within 10 seconds, the buffer is written to disk. If the buffer is notfilled within that time it is automatically written to disk to ensure that thelogs have the most current information.


Administration of log and trace

HPEL has been designed to be easy to configure and understand. For example,administrators can easily configure how much disk space to dedicate to logs ortrace, or how long to retain log and trace records, and leave the management oflog and trace content up to the server. As another example all log, trace,System.out, and System.err content can be accessed using one easy-to-usecommand (LogViewer), avoiding any possible confusion over which file to accessfor certain content.

Reading from the log data and trace data repositories

The log data and trace data repositories are stored in a WebSphereApplication Server proprietary format and cannot be read using text fileeditors such as Notepad or VI. You can copy the log data and trace datarepositories in to a plain text format using the LogViewer command.

HPEL LogViewer command

The HPEL LogViewer is an easy-to-use, command-line tool provided forHPEL users to work with the log data and trace data repositories. TheLogViewer provides filtering and formatting options that make findingimportant content in the log data and trace data repositories easy. Forexample, a user might filter any errors or warnings, then filter all log andtrace entries that occurred within 10 seconds of a key error message on thesame thread.

Filtering using log and trace record extension content

HPEL provides the capability for developers to add custom extensions tolog and trace records using a log record context API(com.ibm.websphere.logging.hpel.LogRecordContext). You can use theLogViewer command-line tool to filter records based on the content of logand trace record extensions.

Development resources

HPEL has been designed to make working with log and trace content more flexibleand effective than the basic logging facility. Log and trace content can be easilyfiltered to show only the records that are of interest. You can use the command line(see the description of the HPEL LogViewer command), or developers can createpowerful log handling programs using the HPEL API.

Reading the log data and trace dataDevelopers can use the com.ibm.websphere.logging.hpel API to read thelog data and trace data repositories

HPEL API

An API has been provided to make it easy for developers to develop toolsto consume content from the HPEL log and trace repositories. For example,a developer might write a Java program to search the log and trace contentto find any messages with message IDs that match a known list ofimportant message IDs. This API is in the com.ibm.websphere.logging.hpelpackage. Refer to the API documentation for details on the HPEL logreading API.

Log and trace record extensibility

As with other log and trace record fields, developers can access the recordextensions using the HPEL API. This is useful when writing tools to read


from log and trace repositories. Developers can also make use of the logrecord context API to access extensions in custom log handlers, filters, andformatters at run time.

LogViewer command-line tool

Use the LogViewer command to query the contents of the High PerformanceExtensible Logging (HPEL) log and trace repositories. You can also use theLogViewer command to view new log and trace repository entries as the serverwrites content to them.

LogViewer

The High Performance Extensible Logging (HPEL) facility writes to the log andtrace repositories in a binary format. You can view, query and filter the repositoryusing the LogViewer command. The LogViewer command provides options forquickly converting HPEL logs into a text file in various formats, including basic,advanced, and Common Base Event format. The command also provides optionsto make getting the data you need from the logs easier; for example, allowing youto filter what log records you want by level, logger name, or date and time.

Use the following command to view the full contents of your log and tracerepositories:

v Windows (Windows) logViewer.bat

Optional parameters

[Liberty profile] servernameSpecifies the name of the server whose log and trace data repositories youwant the logViewer command to use. This parameter is not needed in caseswhere there is only one Liberty profile server created nor in cases where youspecify the path to the log and trace data repository root using the-repositoryDir parameter.

-repositoryDir directory_nameSpecifies the path to the repository directory. In the case where you want toquery both the log and trace data together, provide the path to the parentdirectory, which contains both the log data and tracedata directories. If you usethe default repository location, profile_root/logs/application_server/, and runthis tool from the profile bin directory, then this argument is optional. The toolchecks the default location if one is not provided. If multiple applicationservers exist in this profile with HPEL repositories, you are prompted to selectwhich server log and trace repository you want to view.

-outLog file_nameSpecifies the file name you want the text output written to. If you do notprovide this information, the text output is displayed on the console.

-format basic | advanced | cbe-1.0.1Specifies the output format. Supported formats include basic, advanced, andthe CBE-1.0.1 format. If you do not provide this information, the output is inbasic format.

-monitor [integer]Specifies that you want the logViewer to continuously monitor the repositoryand output new log record entries as they are created. You can provide an


optional integer argument after this parameter to specify how often you wantthe LogViewer tool to query the repository for new records. By default thelogViewer queries the repository for new records every 5 seconds. When usedwith other filtering options, only those new records that match the filtercriteria are displayed.

-helpUse this parameter to have the LogViewer tool list the full set of options thatare available.

-startDate date_timeYou can filter the results that are displayed from the repository by date andtime. Use the startDate parameter to filter out log entries that occurred afterthe date or date time provided as an argument. Provide either a date or dateand time, entered in the MM/dd/yy format or the MM/dd/yy H:m:s:S:zformat, where z represents timezone.

-stopDate date_timeUse this parameter to filter out log entries that occurred before the specifieddate or date time. Provide the argument in the same format as the -startDateoption.

-level level_nameSpecifies that you want the tool to only display those log events which matchthe level name you provide as an argument. Valid values for the level nameare FINEST, FINER, FINE, DETAIL, CONFIG, INFO, AUDIT, WARNING,SEVERE, FATAL.

-minLevel level_nameSpecifies that you want the tool to only display records which are at or abovethe specified level. Valid values for the level name are FINEST, FINER, FINE,DETAIL, CONFIG, INFO, AUDIT, WARNING, SEVERE, FATAL.

-maxLevel level_nameSpecifies that you want the tool to only display records that are at or below thespecified level. Valid values for the level name are FINEST, FINER, FINE,DETAIL, CONFIG, INFO, AUDIT, WARNING, SEVERE, FATAL.

-includeLoggers logger_nameWhen this option is used, only log events from the specified loggers areincluded in the LogViewer output. Separate multiple entries with a comma.The * symbol can be used as a wild card to include all loggers below a parentlogger. When used in combination with the -excludedLoggers option, the morespecific match determines if the log event is included or excluded.

-excludeLoggers logger_nameUse this option to exclude log events from the specified loggers in theLogViewer output. Separate multiple entries with a comma. The * symbol canbe used as a wildcard to include all loggers below a parent logger. When usedin combination with the -includeLoggers option, the more specific matchdetermines if the log event is included or excluded.

-thread thread_idUse this option to restrict LogViewer output to only those log events from aspecific thread. Any log messages that were not created by the thread IDprovided as an argument to this option are not displayed. Specify the threadID in hex format.

-extractToNewRepository directory_nameThis option redirects log and trace records from a binary repository to a newbinary repository at the location that you specify. You can use this option with


other filtering options to get a subset of log and trace records into the newrepository. This option uses the directory path where the new repository mustbe written as an argument. Therefore, the directory must be empty. If thedirectory does not exist, the directory is created. However, errors that occurduring the directory creation might create extraneous directories.

-listInstancesUse this option to list the IDs of available server process instances that areavailable to use with the -instance option. After running LogViewer with the-listInstances option, you can then use the -instance option to invokeLogViewer with one of the server process instance IDs as an argument. Sincethis option does not process any log or trace records, all other options areignored when you specify this option.

-instance instance_idUse this option to retrieve the log and trace data for a given server processinstance by providing the server instance ID. Run LogViewer, along with the-listInstances option, before you use this option to obtain a valid instance ID.This option is required when viewing logs and trace from an environment thatcontains subprocesses, such as the z/OS operating system.

If this option is combined with -latestInstance, -instance is ignored.

-latestInstanceUse this option to retrieve the log and trace data from the most recent serverinstance. If this option is used with the -instance option, the -instance option isignored.

-message match_stringUse this option to retrieve only log or trace data with a message field thatmatches the requested text.

-includeExtensions name[=value][,name[=value]]*Use this option to retrieve the log and trace data with an extension name thatmatches the requested name, and an extension value that matches therequested value. You can also use this option to retrieve the log and trace datawith an extension name that matches the requested name, and an extensionvalue that matches any value, if you omit the =value part of the option.

Any extension name shown in the advanced format can be used. Note that'source', 'class', and 'method' are not stored in the log/trace repositories asextensions, and so cannot be filtered on with this option.

Separate multiple name=value arguments with a comma. Specify '==' (twoequals signs) in place of '=' (one equals sign) in cases where the name or valuemust contain an equal sign. Specify ',,' (two commas) in place of ',' (onecomma) in cases where the name or value must contain a comma.

-encoding character_setSpecifies the character set that the LogViewer command will use for textoutput.

Filtering considerations

Be aware of LogViewer filtering optimizations. The LogViewer tool is able to filterlog and trace data most efficiently when used with the following filter options:v startDatev stopDatev thread


v levelv minLevelv maxLevel

Example usage

See the following examples of LogViewer commands used with full profile serverson UNIX-based systems. The examples show how to run LogViewer from theprofile bin directory where the repositoryDir parameter is not required.v Write all records in the default repository between July 19th, 2009 and August

2nd, 2009 to a file called /tmp/promo.logs.logViewer.sh -outLog /tmp/promo.logs -startDate 07/19/2009 -stopDate 08/02/2009

v Display new records whose specified level is WARNING or higher using theadvanced format as the server writes them to the log repository.

logViewer.sh -monitor -minLevel WARNING -format advanced

v Write only those log messages that were written to the error stream of a specificrepository to a file called logged_errors.txt.

logViewer.sh -repositoryDir /apps/server1/logs -includeLoggers SystemErr -outLog logged_errors.txt

v View events from the default repository that occurred before September 14th,2009 4:28 PM eastern daylight time.

logViewer.sh -stopDate "09/14/2009 16:28:00:000 EDT"

v Write events from the default repository that contain a 'thread' extension withvalue 'WebContainer : 6'

logViewer.sh -includeExtensions thread="WebContainer : 6" -format advanced

v Write events from the default repository that were a part of the request withrequestID a856cb2c-79ed-4d62-a3cf-a9908b2db07b.

logViewer.sh -includeExtensions requestID=a856cb2c-79ed-4d62-a3cf-a9908b2db07b

v Write events from the default repository that were created on a thread servicingthe PlantsByWebSphere application.

logViewer.sh -includeExtensions appName=PlantsByWebSphere

Configuring HPEL in the Liberty Profile

You can configure the High Performance Extensible Logging (HPEL) log and traceframework. Use this information as a guide for configuring HPEL in your Libertyprofile.

About this task

HPEL provides faster log and trace handling capabilities and more flexible ways touse log and trace content than the default Liberty log and trace framework.

A server configuration consists of a bootstrap.properties file, a server.xml file,and any (optional) files that are included with those files. Thebootstrap.properties file specifies properties that need to be available before themain configuration is processed, and are kept to a minimum. The server.xml file isthe primary configuration file for the server.

The server.xml file and its associated files use a simple xml format that is suitablefor most text editors. A richer editing experience is provided by the eclipse serveradapter for liberty (WAS4D+ adapter), which uses a generated schema to providedrop-down lists of available choices, auto-completion, and other editing tools.


The bootstrap.properties file specifies whether the server should use HPEL as thelog and trace framework, or the default log and trace framework.

You can configure HPEL through the server configuration or thebootstrap.properties file.v Server configuration: To get logging from your own code, which is loaded after

server configuration processing, use the server configuration to configure HPEL.v bootstrap.properties file: You might need to set logging properties to take

effect before the server configuration files are processed. For example, if youneed to analyze problems that occur early in server start or configurationprocessing. In this case, you can configure HPEL in the bootstrap.propertiesfile.

You can set Logging properties in either the bootstrap.properties or theserver.xml file. Use attributes in the server.xml file, or use equivalent propertiesin the bootstrap.properties file. Any settings in the bootstrap.properties file areused from the time the server reads the bootstrap.properties file until the time theserver.xml file is processed. If the logging properties in the bootstrap.propertiesfile are not replaced or reset in the server.xml file, the property values in thebootstrap.properties file will continue to be used.

When HPEL is enabled, the maxFileSize, maxFiles, messageFileName,traceFileName, and traceFormat logging element attributes are ignored (sinceHPEL runs without trace.log and messages.log files). The traceSpecificationand consoleLogLevel attributes continue to be used to set the trace specificationand the level for the console log. The logDirectory attribute is ignored in caseswhere the HPEL dataDirectory attribute is explicitly provided -- otherwise thelogDirectory controls the placement of HPEL files.

If you set logging or HPEL attributes in the server.xml file, you can avoid changesin configuration between startup time and runtime by setting the correspondingproperties in the bootstrap.properties file to the same value. Note that if no loggingor HPEL properties are set in the bootstrap.properties file, the server uses thedefault logging and HPEL settings.

Procedurev Enable HPEL for the server by updating the bootstrap.propertiesfile. In the

bootstrap.properties file, add the following text on a line by itself:websphere.log.provider=websphere-binaryLogging_1.0.1

v Configure the HPEL settings. Use the following parameters to configure HPEL.All subelements listed are subelements of the logging element in the server.xmlfile. The following table lists the HPEL attributes that are configurable in theserver.xml file and the equivalent properties that can be set in thebootstrap.properties file:


Table 31. HPEL attributes that are configurable in server.xml and the equivalent properties that can be set inbootstrap.properties

Loggingsubelement Attribute Equivalent bootstrap.properties property

binaryLog dataDirectory

purgeMaxSize

purgeMinTime

fileSwitchTime

bufferingEnabled

outOfSpaceAction

com.ibm.hpel.log.dataDirectory

com.ibm.hpel.log.purgeMaxSize

com.ibm.hpel.log.purgeMinTime

com.ibm.hpel.log.fileSwitchTime

com.ibm.hpel.log.bufferingEnabled

com.ibm.hpel.log.outOfSpaceAction

binaryTrace dataDirectory

memoryBufferSize

purgeMaxSize

purgeMinTime

fileSwitchTime

bufferingEnabled

outOfSpaceAction

com.ibm.hpel.trace.dataDirectory

com.ibm.hpel.trace.memoryBufferSize

com.ibm.hpel.trace.purgeMaxSize

com.ibm.hpel.trace.purgeMinTime

com.ibm.hpel.trace.fileSwitchTime

com.ibm.hpel.trace.bufferingEnabled

com.ibm.hpel.trace.outOfSpaceAction

textLog dataDirectory

outputFormat

traceIncluded

purgeMaxSize

purgeMinTime

fileSwitchTime

bufferingEnabled

outOfSpaceAction

com.ibm.hpel.text.dataDirectory

com.ibm.hpel.text.outputFormat

com.ibm.hpel.text.traceIncluded

com.ibm.hpel.text.purgeMaxSize

com.ibm.hpel.text.purgeMinTime

com.ibm.hpel.text.fileSwitchTime

com.ibm.hpel.text.bufferingEnabled

com.ibm.hpel.text.outOfSpaceAction

The following example shows a bootstrap.properties file configured to enableHPEL:websphere.log.provider=websphere-binaryLogging_1.0.1

The following example shows a server.xml file with the HPEL subelements. Thelog content is set to expire after 96 hours, the trace content is set to retain amaximum of 1024MB, and the text log is set for advanced format:<server description="new server">

<logging><binaryLog purgeMinTime="96"/><binaryTrace purgeMaxSize="1024"/><textLog outputFormat="Advanced"/>

</logging>

</server>

For the full logging configuration reference, see the logging, binaryLog,binaryTrace, and textLog elements in the “Liberty profile: Configurationelements in the server.xml file” on page 97.


Results

After you restart the server, the HPEL log and trace framework will be enabledand configured.

Liberty profile: Runtime environment known restrictionsThere are some known restrictions that apply when working with the Libertyprofile runtime environment.


See also “Liberty profile: Developer Tools known restrictions” on page 570.

Minimum supported Java levels

The minimum supported level for the JDK from Oracle is Java 6 update 26. For theJava SDK from IBM, the minimum supported level is 6.0 (J9 2.6) SR 1.

On distributed platforms, 32-bit or 64-bit Java is supported.

For Windows and Linux systems, you can use either the JDK from Oracle or theJDK from IBM. If you are developing applications on Windows or Linux, and youplan to deploy those applications to a server running on the WebSphereApplication Server full profile, you should use the JDK from IBM. For HP systemsand Mac OS, use the JDK from Oracle.

The JDK from IBM is available in many IBM products. For example, WebSphereApplication Server Version 7 includes the Java 6 JDK from IBM.

The installation directory name and path cannot includenon-ASCII characters

Recent JVMs do not fully support use of non-ASCII characters with the -jar and-javaagent commands. You should use only ASCII characters in your installationdirectory names and paths.

Changing the JDBC data source at run time might result in JPAfailures

If the database dictionary type is not specified through properties, it is detectedand calculated by OpenJPA when the first entity manager is created and thedatabase connection is made. This database dictionary type is used for all entitymanagers that are subsequently created. If the JDBC data source is changed whilean application is running, the entity manager factory does not detect this changeand continues to use the old dictionary for operations against the new data source.This can result in failures if the database is changed to a different vendor.

When you change a database to a different vendor, restart the application.

Modifying the dataSource, jdbcDriver, connectionManager, andJDBC vendor properties at run time might result in JPA failures

If you update the configuration of dataSource, jdbcDriver, connectionManager orany of the JDBC vendor properties lists (for example, properties.db2.jcc orproperties.oracle) while the server is running, you might see J2CA8040E failures.


These failures state that multiple dataSource elements cannot be associated with asingle connectionManager. These failures are generated even if your configurationassociates only one connectionManager with the dataSource element.

When you make updates to the configuration of any of these JDBC resources,restart the server.

An application that relies on a result being returned bygetRealPath must be deployed as an expanded application, notas a WAR file

The Java EE specification states that the getRealPath() method returns a nullvalue if the content is being made available from a web archive (WAR) file. Whenyou deploy a WAR file to the Liberty profile, the profile does not automaticallyextract the archive file into a directory structure. Therefore the application mightfail to start. If your application relies on a result being returned by getRealPath(),you must deploy the application as an expanded web application, not as a WARfile. For example, you can manually extract the WAR file and copy the expandedapplication to the dropins directory.

WebSphere Application Server full profile scripts do not workwith the Liberty profile

You cannot use any of the scripts under the bin directory of the WebSphereApplication Server full profile to administer the Liberty profile.

Fileset restrictions

The following restrictions apply to Filesets:v Filesets do not recursively explore subdirectories of the base directory. For

example, the following instructions are not supported:<fileset id="testFileset" dir="\temp" includes="**\a.jar"/><fileset id="testFileset" dir="\temp" includes="a\a.jar"/><fileset id="testFileset" dir="\temp" includes="*\a.jar"/><fileset id="testFileset" dir="\temp" includes="a\b\a.jar"/>

v If you use symbolic links with Filesets, you must add a forward slash ("/") atthe end of the dir attribute value. For example:<fileset dir="${ihc.home}/" includes="*.jar"/>

Overriding classes from the Java SDK

Some Java EE 6 technologies supported by the Liberty profile require newerversions of APIs that are provided by Java SE 6. JAX-WS, JAXB and thejavax.annotation.Resource annotation are all examples where a Java 6 SDKcontains older classes than those required by Java EE 6. When compiling yourapplication code against these APIs using Java SDK version 6, you need to useclasses that are provided by the Liberty profile rather than the Java SDK. You musttake one of the following actions:v If you are using javac to build from the command line, compile your code by

using the javac -endorseddirs option and the JAR files in the${wlp.install.dir}/dev/specs directory.

v If you are using Apache Ant to build, compile your code by using the<compilerarg> child element of the javac task and the JAR files in the${wlp.install.dir}/dev/specs directory. In the build script, specify the-endorseddirs option and the ${wlp.install.dir}/dev/specs directory asseparate <compilerarg> elements. For example:


<javac srcdir="src" destdir="classes"/><compilerarg value="-endorseddirs"/><compilerarg value="${wlp.install.dir}/dev/specs"/>

</javac>

v If you are using Apache Maven to build, compile your code by using theendorseddirs element of the Maven compiler plug-in and the JAR files in the${wlp.install.dir}/dev/specs directory. For example:<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><configuration><source>1.6</source><target>1.6</target><compilerArguments><endorseddirs>${wlp.install.dir}/dev/specs</endorseddirs>

</compilerArguments></configuration>

</plugin>

Windows

When you unpublish a shared library, it cannot be deleted untilthe server is stopped

When you unpublish a shared library from a server, the library JAR file is notimmediately released from the server. Therefore the operating system does notknow that the file is no longer in use, and does not let you delete the file. Whenyou next stop the server, the library JAR file is released and you can delete the file.

java:global lookups restrictions

Resources defined in applications with java:global lookups can only be used toaccess names declared by applications deployed in the current server.

appSecurity-2.0 feature restrictions

For the appSecurity-2.0 feature, the following restrictions apply:

v For EJB applications, security elements defined in the IBMextension files are not supported; these include:– ibm-ejb-jar-ext.xmi/xml

– ibm-ejb-jar-bnd.xmi/xml

v The getCallerIdentity API is not supported for Singleton session beans.

beanvalidation-1.0 feature restrictions

For the beanvalidation-1.0 feature, the following restriction applies:v There is no support for bean validation inside OSGi applications.

cdi-1.0 feature restrictions

The supported entry point into CDI is through an expression language lookup ofan @Named CDI style bean, with other CDI beans injected into it. The followingCDI Integration points are not available or have limited availability:v Support for Enterprise Java Beans in WAR modules only.v Limited support for those Enterprise Java Beans. No CDI interceptors or

decorators are supported.


v You can look up Enterprise Java Beans though the Expression Language using@Named or they can be injected into a CDI managed bean.

v @Inject into EE components

ejblite-3.1 feature restrictions

For the ejblite-3.1 feature, the following restrictions apply:

v Bindings and extension files are ignored.v ejblocal namespace lookups are not handled, and ejb-ref bindings must be

specified using java:global, java:app, or java:module names.

v Session beans are only bound to the java:global, java:app, orjava:module contexts. Session beans are not bound to the ejblocal namespace.ejb-ref binding names must use java:global, java:app, or java:module names.

The stateful bean passivation directory is not configurable. Files are passivated tothe server work area.

jaxb-2.2 feature restriction

For the jaxb-2.2 feature, the following restriction applies:v If your application has already been started before enabling the jaxb-2.2 server

feature, you must restart the server with the --clean option. Otherwise, theapplication might still bind to the JAXB implementation that is cached from thelast server startup.

jaxrs-1.1 feature restriction

For the jaxrs-1.1 feature, Liberty profile does not support JAX-RS third-partyAPIs in the developer tools as in the full profile.

jaxws-2.2 feature restrictions

For the jaxws-2.2 feature, the following restrictions apply:v If your application has already been started before enabling the jaxws-2.2

feature, you must restart the server with the --clean option. Otherwise, theapplication might still bind to an incorrect JAXB version that is cached from thelast server startup.

v You cannot use annotation injections for JAX-WS handlers that areassociated with target EJB Beans.

v The following IBM extension files are not supported:– ibm-webservices-ext.xmi

– ibm-webservices-bnd.xmi

– ibm-webservicesclient-ext.xmi

– ibm-webservicesclient-bnd.xmi

– ws-security.xml

v The following Apache Axis2 specific configurations or classes are not supported:


– Provider<String>

– Provider<OMElement>

– org.apache.axis2.jaxws.Constants.SOAP_HTTP_BINDING

jpa-2.0 feature restrictions

For the jpa-2.0 feature, the following restriction applies:v There is no support for dynamic removal at run time.

jsf-2.0 feature restrictions

For the jsf-2.0 feature, the following restriction applies:v There is no support for dynamic removal at run time.

jsp-2.2 feature restrictions

For the jsp-2.2 feature, the following restriction applies:v There is no support for the useInMemory configuration option to only store the

translated JSP file in memory.

monitor-1.0 feature restriction

For the monitor-1.0 feature, the following restriction applies:v When the feature is removed from the server.xml file, you must restart the

server to make the JAX-WS applications work.

Liberty profile: Developer Tools known restrictions


There are few known restrictions that apply when working with the WebSphereApplication Server Developer Tools for Eclipse.

See also “Liberty profile: Runtime environment known restrictions” on page 566.

EJB 3.1 restrictions

Support for EJB 3.1 functionality is restricted to a subset of the EJB 3.1 litespecification. See “ejblite-3.1 feature restrictions” on page 569.

Projects that are required by web fragment projects are notautomatically added to the Java build path

If you have a web application project that contains one or more web fragmentprojects, and the web application project has references in its deployment assemblypage to projects that are required by the web fragment projects, then thosedependent projects (such as the JPA and Utility projects) are not automaticallyadded to the Java build path of the web fragment projects.

Manually add the dependent projects to the Java build path of the web fragmentprojects in order for them to compile.


For more information about limitations, see Known problems and limitations forWebSphere Application Server Developer Tools for Eclipse, Version 9.0 Beta

Liberty profile: MessagesWhen you use the Liberty profile, you might encounter system messages. Eachmessage has a unique message identifier, and includes an explanation of theproblem, and details of any action that you can take to resolve the problem.

Liberty profile system messages are logged from various sources, includingapplication server components and applications. For the Liberty profile, themessage identifier is 10 characters in length and has the following form:CWXXX9999X

where:CWXXX

Is a five-character alphabetic message prefix that identifies the Libertyprofile component.

9999 Is a four-character numeric identifier used to identify the specific messagefor that component.

X Is an optional alphabetic indicator that identifies the message type:I=Informational, W=Warning, E=Error.

Table 32. Alphabetic message prefixes for Liberty profile messages

Liberty profile messageprefix Range Liberty profile component

CWLIB 0001-0100 Transactions

CWLIB 0101-0200 z/OS Transaction Extensions

CWWKB z/OS Native integration

CWWKB 0001-0050 z/OS Command Processing

CWWKB 0051-0100 z/OS Native code only

CWWKB 0101-0150 z/OS Core

CWWKB 0151-0200 z/OS WLM services

CWWKC 0000-0250 Annotation scanning

CWWKE Core kernel and kernel services

CWWKE 0001-0099 Boot/Launcher

CWWKE 0100-0199 Service utilities

CWWKE 0200-0299 Location service

CWWKE 0300-0399 File installation service

CWWKE 0400-0499 FileMonitor service

CWWKE 0500-0599 Extensible Class Scanner

CWWKF Feature manager

CWWKG Configuration manager

CWWKJ Light touch administration

CWWKL 0001-0100 Class loading service

CWWKM 0001-0050 Artifact API messages(container factory)

CWWKM 0051-0100 Overlay Messages (allimplementations)


http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.rad.nav.doc/r_wdt_problems_limitations.html

http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.rad.nav.doc/r_wdt_problems_limitations.html

Table 32. Alphabetic message prefixes for Liberty profile messages (continued)


CWWKM 0101-0150 Artifact API Zipimplementation

CWWKM 0151-0200 Artifact API Fileimplementation

CWWKM 0401-0450 Adaptable APIImplementation messages(adaptable module factory /adapter service)

CWWKM 1001-1100 Loose archive API (used bythe Eclipse-based toolsoption that runs anapplication directly from theEclipse workspace(TheEclipse platform supports a"virtual" application archive,where a set of files thatappear to be in the samearchive file are actuallyspread out across the Eclipseworkspace. Liberty calls thisa “loose archive”, and thetools option that uses theloose archive API is calledRun this application directlyfrom the workspace)).

CWWKM 2000-2999 Ant and Maven plug-in

CWWKN 0001-0100 JNDI default namespace

CWWKO CFW components

CWWKO 0000-0199 CFW

CWWKO 0200-0399 TCP

CWWKO 0400-0599 UDP

CWWKO 0600-0799 bytebuffer

CWWKO 0800-0899 SSL channel

CWWKO 0900-0999 SSL

CWWKS Security

CWWKS 0000 series Security: General messages

CWWKS 0000-0099 Security

CWWKS 0900-0999 Security quickStart

CWWKS 1000 series Security: Authenticationservices

CWWKS 1000-1099 Authentication

CWWKS 1100-1199 JAAS authentication

CWWKS 1200-1299 TAI authentication

CWWKS 2000 series Security: Authorization services

CWWKS 2000-2099 Authorization

CWWKS 2100-2199 Built-in authorization


Table 32. Alphabetic message prefixes for Liberty profile messages (continued)


CWWKS 2900-2999 SAF authorization

CWWKS 3000 series Security: Registry services

CWWKS 3000-3099 Registry

CWWKS 3100-3199 Basic registry

CWWKS 3200-3299 LDAP registry

CWWKS 3300-3399 FileBased (VMM) registry

CWWKS 3800-3899 Custom registry

CWWKS 3900-3999 SAF registry

CWWKS 4000 series Security: Token services

CWWKS 4000-4099 Token services

CWWKS 4100-4199 LTPA

CWWKS 4200-4299 Kerberos

CWWKS 4300-4399 SPNEGO

CWWKS 9000 series Security: Collaborators

CWWKS 9100-9199 Web Collaborator (commoncode)

CWWKS 9200-9299 Web ApplicationCollaborator

CWWKS 9300-9399 Web AdministrationCollaborator

CWWKT HTTP transport/dispatcher

CWWKW0000-0099 JAX-WS common

CWWKW0100-0199 JAX-WS for webContainer

CWWKW0200-0299 JAX-WS security

CWWKW0300-0399 JAX-WS for Java EE common

CWWKX JMX

CWWKX 0001-0100 JMX Security

CWWKX 0101-0200 JMX REST Connector

CWWKX 0201-0300 JMX REST Client

CWWKZ Applications

CWWKZ 0001-0100 Application manager

CWWKZ 0101-0200 WARs

CWWKZ 0201-0300 WABs

CWWKZ 0301-0400 EBAs


Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing 2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM websites are provided forconvenience only and do not in any manner serve as an endorsement of thosewebsites. The materials at those websites are not part of the materials for this IBMproduct and use of those websites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM CorporationSoftware Interoperability Coordinator, Department 49XA3605 Highway 52 NRochester, MN 55901U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this information and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs.

If you are viewing this information softcopy, the photographs and colorillustrations may not appear.


TrademarksIBM, the IBM logo, ibm.com®, Rational, and WebSphere are trademarks orregistered trademarks of International Business Machines Corporation in theUnited States, other countries, or both. If these and other IBM trademarked termsare marked on their first occurrence in this information with a trademark symbol(® or ™), these symbols indicate U.S. registered or common law trademarks ownedby IBM at the time this information was published. Such trademarks may also beregistered or common law trademarks in other countries. A current list of IBMtrademarks is available on the web at Copyright and trademark information(www.ibm.com/legal/copytrade.shtml).

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Oracle and/or its affiliates.

Linux is a registered trademark of Linus Torvalds in the United States, othercountries, or both.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

This product includes software developed by the Eclipse Project(http://www.eclipse.org/).

Notices 577

http://www.ibm.com/legal/copytrade.shtml

Sending your comments to IBM

If you especially like or dislike anything about this book, please use one of themethods listed below to send your comments to IBM.

Feel free to comment on what you regard as specific errors or omissions, and onthe accuracy, organization, subject matter, or completeness of this book.

Please limit your comments to the information in this book and the way in whichthe information is presented.

To make comments about the functions of IBM products or systems, talk to yourIBM representative or to your IBM authorized remarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use ordistribute your comments in any way it believes appropriate, without incurringany obligation to you.

You can send your comments to IBM in any of the following ways:v By mail, to this address:

User Technologies Department (MP095)IBM United Kingdom LaboratoriesHursley ParkWINCHESTER,HampshireSO21 2JNUnited Kingdom

v By fax:– From outside the U.K., after your international access code use 44-1962-816151– From within the U.K., use 01962-816151

v Electronically, use the appropriate network ID:– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL– IBMLink: HURSLEY(IDRCF)– Internet: [email protected]

Whichever method you use, ensure that you include:v The publication title and order numberv The topic to which your comment appliesv Your name and address/telephone number/fax number/network ID.


mailto:[email protected]

��

ibmwebsphereapplication server v8.5.next beta · starting and stopping a server by using developer...

Documents