Liberty V85next Beta

IBM WebSphere Application Server
Version 8 Release 5
IBM WebSphere Application Server
V8.5.Next Beta
Note
Before 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 any
way 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 Contract
with IBM Corp.
Contents
Chapter 1. IBM WebSphere Application
Server Developer Tools for Eclipse,
Version 9.0 Beta overview . . . . . . . 2
Chapter 2. The Liberty profile . . . . . 5
Liberty profile: Architecture . . . . . . . . . 5
Programming model support . . . . . . . . 8
Liberty profile externals support . . . . . . 11
Liberty profile: Server configuration . . . . . . 12
Liberty profile: Feature management . . . . . . 13
Liberty features . . . . . . . . . . . . 14
Liberty profile: Shared libraries . . . . . . . . 21
Liberty profile: Product extension . . . . . . . 22
Liberty profile: Security . . . . . . . . . . 25
Liberty profile: Quick overview of security . . . 29
Liberty profile: Authentication . . . . . . . 29
Liberty profile: Authorization . . . . . . . 40
Liberty profile: Security public APIs . . . . . 43
Configuration differences between the full profile
and Liberty profile: security . . . . . . . . 46
Liberty profile: The limits to protection through
password encryption . . . . . . . . . . 47
Liberty profile: Messaging . . . . . . . . . 48
Liberty profile: High Performance Extensible
Logging (HPEL) . . . . . . . . . . . . . 51
LogViewer command-line tool . . . . . . . 55
MongoDB databases . . . . . . . . . . . 58
Chapter 3. End-to-end paths for the
Liberty profile. . . . . . . . . . . . 59
Enabling JMS messaging for the Liberty profile . . 59
Enabling JMS messaging for a single Liberty
profile server . . . . . . . . . . . . . 59
Enabling JMS messaging between two Liberty
profile servers . . . . . . . . . . . . 62
Chapter 4. Migrating applications to the
Liberty profile. . . . . . . . . . . . 67
Migrating data access applications to the Liberty
profile . . . . . . . . . . . . . . . . 67
and Liberty profile: dataSource and jdbcDriver
elements . . . . . . . . . . . . . . 67
and Liberty profile: connectionManager element . 68
Migrating a DB2 data source to the Liberty
profile . . . . . . . . . . . . . . . 69
Migrating a Derby embedded data source to the
Liberty profile . . . . . . . . . . . . 71
Chapter 5. Installing the Liberty profile 73
Installing the Liberty profile developer tools and
(optionally) the Liberty profile . . . . . . . . 73
Installing the developer tools from a remote
repository . . . . . . . . . . . . . . 74
Installing the developer tools from downloaded
installation files . . . . . . . . . . . . 76
Configuring the developer tools installation . . 77
Installing Maven Integration for Eclipse . . . . 79
System requirements for WebSphere Application
Server Developer Tools for Eclipse. . . . . . 80
Installing the Liberty profile by extracting an
archive file . . . . . . . . . . . . . . 83
Applying a fix pack to a Liberty profile archive
installation . . . . . . . . . . . . . . 84
Removing a fix pack from a Liberty profile
archive installation . . . . . . . . . . . 86
Applying an interim fix to a Liberty profile archive
installation . . . . . . . . . . . . . . 86
Removing an interim fix from a Liberty profile
archive install . . . . . . . . . . . . 87
Chapter 6. Setting up the Liberty profile 89
Liberty profile: Directory locations and properties 89
Verifying the integrity of Liberty profile installation 91
Liberty profile: productInfo command . . . . 92
Creating a Liberty profile server by using developer
tools. . . . . . . . . . . . . . . . . 93
Creating a Liberty profile server manually . . . . 95
Specifying Liberty profile bootstrap properties. . . 95
Chapter 7. Administering the Liberty
profile . . . . . . . . . . . . . . . 97
Liberty profile: Configuration elements in the
server.xml file . . . . . . . . . . . . . 97
activationSpec . . . . . . . . . . . . 101
activedLdapFilterProperties. . . . . . . . 101
administrator-role . . . . . . . . . . . 102
application . . . . . . . . . . . . . 103
application-bnd. . . . . . . . . . . . 104
applicationMonitor . . . . . . . . . . 106
authCache . . . . . . . . . . . . . 107
authData . . . . . . . . . . . . . . 108
authenticated . . . . . . . . . . . . 109
authentication . . . . . . . . . . . . 110
automaticLibraries. . . . . . . . . . . 110
baseEntry. . . . . . . . . . . . . . 110
basicRegistry . . . . . . . . . . . . 111
binaryLog . . . . . . . . . . . . . 112
binaryTrace . . . . . . . . . . . . . 114
bundleRepository . . . . . . . . . . . 116
channelfw . . . . . . . . . . . . . 116
classloader . . . . . . . . . . . . . 117
client . . . . . . . . . . . . . . . 119
clientManager . . . . . . . . . . . . 120
config . . . . . . . . . . . . . . . 121
connectionManager . . . . . . . . . . 123
contextService . . . . . . . . . . . . 125
Copyright IBM Corp. 2011, 2013 iii
customLdapFilterProperties. . . . . . . . 126
databaseStore . . . . . . . . . . . . 127
dataSource . . . . . . . . . . . . . 128
disk . . . . . . . . . . . . . . . 132
domino50LdapFilterProperties. . . . . . . 134
edirectoryLdapFilterProperties. . . . . . . 135
ejbContainer. . . . . . . . . . . . . 135
executor . . . . . . . . . . . . . . 136
featureManager. . . . . . . . . . . . 138
federatedRepository . . . . . . . . . . 139
fileset . . . . . . . . . . . . . . . 141
fileTransfer . . . . . . . . . . . . . 142
group . . . . . . . . . . . . . . . 143
groupDisplayNameMapping . . . . . . . 143
groupSecurityNameMapping . . . . . . . 144
hostAuthInfo . . . . . . . . . . . . 145
httpClassification . . . . . . . . . . . 147
httpDispatcher . . . . . . . . . . . . 148
httpEncoding . . . . . . . . . . . . 149
httpEndpoint . . . . . . . . . . . . 158
httpOptions . . . . . . . . . . . . . 160
httpSession . . . . . . . . . . . . . 162
httpSessionDatabase . . . . . . . . . . 167
idsLdapFilterProperties . . . . . . . . . 172
include . . . . . . . . . . . . . . 173
iplanetLdapFilterProperties . . . . . . . . 174
jaasLoginContextEntry . . . . . . . . . 175
jaasLoginModule . . . . . . . . . . . 176
jdbcDriver . . . . . . . . . . . . . 178
jmsCommsEndpoint . . . . . . . . . . 178
jmsCommsOutbound. . . . . . . . . . 180
jmsConnectionFactory . . . . . . . . . 181
jmsQueue . . . . . . . . . . . . . 181
jmsQueueConnectionFactory . . . . . . . 181
jmsTopic . . . . . . . . . . . . . . 181
jmsTopicConnectionFactory. . . . . . . . 181
jndiEntry . . . . . . . . . . . . . . 181
jpa . . . . . . . . . . . . . . . . 182
jspEngine. . . . . . . . . . . . . . 183
keyStore . . . . . . . . . . . . . . 185
ldapRegistry. . . . . . . . . . . . . 186
library. . . . . . . . . . . . . . . 192
localStore. . . . . . . . . . . . . . 194
logging . . . . . . . . . . . . . . 195
ltpa. . . . . . . . . . . . . . . . 197
managedExecutorService . . . . . . . . 198
managedServer . . . . . . . . . . . . 199
managementRepository . . . . . . . . . 199
managementRepositoryConnection . . . . . 200
member . . . . . . . . . . . . . . 201
messagingEngine . . . . . . . . . . . 202
messagingSecurity. . . . . . . . . . . 207
mimeTypes . . . . . . . . . . . . . 208
mongo . . . . . . . . . . . . . . 208
mongoDB . . . . . . . . . . . . . 212
monitor . . . . . . . . . . . . . . 213
nativeTransactionManager . . . . . . . . 213
netscapeLdapFilterProperties . . . . . . . 214
oauthProvider . . . . . . . . . . . . 215
oauthRoles . . . . . . . . . . . . . 220
permission . . . . . . . . . . . . . 221
pluginConfiguration . . . . . . . . . . 221
properties . . . . . . . . . . . . . 223
properties.datadirect.sqlserver . . . . . . . 223
properties.db2.i.native . . . . . . . . . 231
properties.db2.i.toolbox . . . . . . . . . 238
properties.db2.jcc . . . . . . . . . . . 250
properties.derby.client . . . . . . . . . 262
properties.derby.embedded . . . . . . . . 265
properties.informix . . . . . . . . . . 267
properties.informix.jcc . . . . . . . . . 275
properties.jms.ActivationSpec . . . . . . . 282
properties.jms.ConnectionFactory. . . . . . 284
properties.jms.Queue . . . . . . . . . . 286
properties.jms.QueueConnectionFactory . . . 288
properties.jms.Topic . . . . . . . . . . 290
properties.jms.TopicConnectionFactory . . . . 292
properties.microsoft.sqlserver . . . . . . . 294
properties.oracle . . . . . . . . . . . 298
properties.sybase . . . . . . . . . . . 300
quickStartSecurity . . . . . . . . . . . 302
realm . . . . . . . . . . . . . . . 302
remoteAccess . . . . . . . . . . . . 305
role. . . . . . . . . . . . . . . . 306
safAuthorization . . . . . . . . . . . 307
safCredentials . . . . . . . . . . . . 308
safRegistry . . . . . . . . . . . . . 308
safRoleMapper . . . . . . . . . . . . 309
securewayLdapFilterProperties . . . . . . 309
serverCommand . . . . . . . . . . . 310
ssl . . . . . . . . . . . . . . . . 311
sslDefault. . . . . . . . . . . . . . 311
sslOptions . . . . . . . . . . . . . 312
supportedEntityType . . . . . . . . . . 312
syncToOSThread . . . . . . . . . . . 313
tcpOptions . . . . . . . . . . . . . 313
textLog . . . . . . . . . . . . . . 314
transaction . . . . . . . . . . . . . 316
trustAssociation . . . . . . . . . . . 319
uniqueGroupIdMapping. . . . . . . . . 321
uniqueUserIdMapping . . . . . . . . . 322
user . . . . . . . . . . . . . . . 323
userDisplayNameMapping . . . . . . . . 323
userSecurityNameMapping. . . . . . . . 323
variable . . . . . . . . . . . . . . 324
virtualHost . . . . . . . . . . . . . 324
webAppSecurity . . . . . . . . . . . 325
webContainer . . . . . . . . . . . . 329
wimRegistry. . . . . . . . . . . . . 336
wlmClassification . . . . . . . . . . . 337
wsSecurityClient . . . . . . . . . . . 337
wsSecurityProvider . . . . . . . . . . 340
Administering the Liberty profile by using
developer tools . . . . . . . . . . . . . 344
Editing the Liberty profile configuration by
using developer tools. . . . . . . . . . 344
Starting and stopping a server by using
developer tools . . . . . . . . . . . . 345
Defining a utility project as a shared library . . 345
Exploring the runtime environment by using
developer tools . . . . . . . . . . . . 348
iv IBM WebSphere Application Server: V8.5.Next Beta
Displaying the server configuration in a merged
view . . . . . . . . . . . . . . . 348
Viewing the schema documentation for the
server configuration . . . . . . . . . . 349
Generating a Liberty profile server dump using
developer tools . . . . . . . . . . . . 349
Packaging a Liberty profile server by using
developer tools . . . . . . . . . . . . 350
Adding a data source by using developer tools 350
Administering the Liberty profile manually . . . 351
Customizing the Liberty profile environment 352
Administering the Liberty profile from the
command prompt . . . . . . . . . . . 353
Adding and removing Liberty features . . . . 368
Using include elements, variables, and Ref tags
in configuration files . . . . . . . . . . 370
Controlling dynamic updates . . . . . . . 374
Configuring class loaders and libraries for Java
EE applications . . . . . . . . . . . . 376
Configuring a web server plug-in for the Liberty
profile . . . . . . . . . . . . . . . 381
Configuring session persistence for the Liberty
profile . . . . . . . . . . . . . . . 384
Connecting to the Liberty profile by using JMX 386
Establishing a JMX MBean Liberty server
connection . . . . . . . . . . . . . 398
Configuring HPEL in the Liberty Profile . . . 399
Setting up the server-management environment
for the Liberty profile . . . . . . . . . 401
Administering data access applications on the
Liberty profile . . . . . . . . . . . . 407
Administering web applications on the Liberty
profile . . . . . . . . . . . . . . . 418
Chapter 8. Extending the Liberty
profile . . . . . . . . . . . . . . 419
Developing a Liberty feature for the Liberty profile 419
Developing a Liberty feature manually . . . . 419
Creating a Liberty feature by using developer
tools . . . . . . . . . . . . . . . 425
Developing an OSGi bundle with simple
activation. . . . . . . . . . . . . . 429
Composing advanced features by using OSGi
Declarative Services . . . . . . . . . . 434
Liberty profile: Resource location symbols . . . 441
Monitoring local files for changes . . . . . 442
Configuring tracing and logging for features in
the Liberty profile . . . . . . . . . . . 443
Chapter 9. Securing the Liberty profile
and its applications. . . . . . . . . 445
Getting started with security in the Liberty profile 445
Liberty profile: Quick overview of security . . 447
Setting up BasicRegistry and role mapping on
Securing communications with the Liberty profile 449
Enabling SSL communication for the Liberty
profile . . . . . . . . . . . . . . . 449
Creating SSL certificates for your Liberty profile
using the Utilities menu . . . . . . . . . 455
Creating SSL certificates from the command
prompt . . . . . . . . . . . . . . 455
Configuring your web application and server
for client certificate authentication . . . . . 457
Authenticating users in the Liberty profile. . . . 459
Configuring a user registry for the Liberty
profile . . . . . . . . . . . . . . . 459
Configuring the authentication cache on the
Liberty profile . . . . . . . . . . . . 464
Configuring a JAAS custom login module for
Configuring LTPA on the Liberty profile . . . 467
Customizing SSO configuration using LTPA
cookies for the Liberty profile . . . . . . . 468
Configuring RunAs authentication in the
Liberty profile . . . . . . . . . . . . 469
Configuring TAI for the Liberty profile . . . . 470
Authorizing access to resources in the Liberty
profile . . . . . . . . . . . . . . . . 472
Configuring authorization for applications on
OAuth. . . . . . . . . . . . . . . 474
Configuring secure JMX connection to the Liberty
profile . . . . . . . . . . . . . . . . 492
Configuring web security related properties for the
Liberty profile . . . . . . . . . . . . . 493
Customizing SSO configuration using LTPA
cookies for the Liberty profile . . . . . . . 494
Configuring your web application and server
for client certificate authentication . . . . . 494
Configuring authentication aliases for the Liberty
profile . . . . . . . . . . . . . . . . 495
Setting up a Liberty profile to run in SP800-131 496
Developing extensions to the Liberty profile
security infrastructure . . . . . . . . . . 497
Developing a custom TAI for the Liberty profile 498
Developing JAAS custom login modules for a
system login configuration . . . . . . . . 499
Customizing an application login to perform an
identity assertion using JAAS . . . . . . . 503
Developing a custom user registry for the
Liberty profile . . . . . . . . . . . . 504
Securing web services . . . . . . . . . . 505
Securing web services at the message level . . 505
Web services security HTTPS transport policy
assertions. . . . . . . . . . . . . . 516
Chapter 10. Deploying applications to
the Liberty profile . . . . . . . . . 517
Adding and running an application on the Liberty
profile by using developer tools . . . . . . . 519
Publishing your application by using developer
tools . . . . . . . . . . . . . . . 520
Packaging a Liberty profile server from the
command prompt . . . . . . . . . . . . 522
Using JNDI binding for constants from the server
configuration files . . . . . . . . . . . . 523
Deploying OSGi applications to the Liberty profile 524
Sharing common OSGi bundles for the Liberty
profile . . . . . . . . . . . . . . . 524
Contents v
Deploying data access applications to the Liberty
profile . . . . . . . . . . . . . . . . 525
Deploying an existing JDBC application to the
Liberty profile . . . . . . . . . . . . 525
Enabling JDBC Tracing for the Liberty profile 526
Deploying a web application to the Liberty profile 529
Deploying a JPA application to the Liberty profile 530
Deploying web services applications to the Liberty
profile . . . . . . . . . . . . . . . . 531
Deploying JAX-RS applications to the Liberty
profile . . . . . . . . . . . . . . . 531
Deploying a messaging application to the Liberty
profile . . . . . . . . . . . . . . . . 534
Chapter 11. Monitoring the Liberty
profile . . . . . . . . . . . . . . 537
Liberty profile: JVM monitoring . . . . . . . 537
Liberty profile: Web application monitoring . . . 538
Liberty profile: ThreadPool monitoring . . . . . 539
Liberty profile: JAX-WS monitoring . . . . . . 540
Liberty profile: Sessions monitoring . . . . . . 541
Chapter 12. Tuning the Liberty profile 543
Chapter 13. Liberty profile:
Troubleshooting tips . . . . . . . . 547
Liberty profile: Trace and logging . . . . . . 552
Liberty profile: Timed operations and JDBC calls 554
Liberty profile: High Performance Extensible
Logging (HPEL) . . . . . . . . . . . . 556
LogViewer command-line tool . . . . . . . 560
Configuring HPEL in the Liberty Profile . . . 563
Liberty profile: Runtime environment known
restrictions . . . . . . . . . . . . . . 566
Liberty profile: Developer Tools known restrictions 570
Liberty profile: Messages . . . . . . . . . 571
Notices . . . . . . . . . . . . . . 575
Trademarks . . . . . . . . . . . . . . 577
Sending your comments to IBM . . . 579
vi IBM WebSphere Application Server: V8.5.Next Beta
Chapter 1. IBM WebSphere Application Server Developer
Tools for Eclipse, Version 9.0 Beta overview
Distributed operating systems
IBM
WebSphere
Application Server Developer Tools for Eclipse is a lightweight

set 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 Version
8.5.Next Beta Liberty Profile, the WebSphere Application Server Developer Tools
for Eclipse V9.0 Beta provides a fast and lightweight environment for the rapid
development and testing of Java EE web profile, Web 2.0, mobile, and OSGi
applications.
For more information about IBM WebSphere Application Server Developer Tools
for Eclipse, see:
v What's new in Version 9.0 Beta
v Supported programming models on page 2
v Supported server tasks on page 3
v Advanced support on page 3
v Getting started on page 3
v 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 WebSphere
Application Server Developer Tools for Eclipse and indicates the application servers that
they are supported on.
Programming
model
WebSphere
Application
Server V8.5
Next Beta
Liberty
Profile
WebSphere
Application
Server V8.5
Liberty
Profile
WebSphere
Application
Server V8.5
WebSphere
Application
Server V8.0
WebSphere
Application
Server V7.0
Develop Java
EE
applications
Yes Yes Yes Yes Yes
Develop EJB
applications
Yes
Note: The
tools for
developing
EJB
applications
support EJB
3.0 and 3.1.
No Yes Yes Yes
Develop CDI
applications
Yes No Yes Yes No
Develop
JAX-RS
applications
Yes Yes Yes Yes Yes
Develop
JAX-WS
applications
Yes No Yes Yes Yes
Develop Web
2.0 and
Mobile web
applications
Yes Yes Yes Yes Yes
Develop
OSGi
applications
Yes
Note: The
tools for
developing
OSGi
applications
support the
following
technologies:
v Web 2.5
v Web 3.0
v JPA
v JAX-RS
v JSF
v EJB Lite
Yes
Note: The
tools for
developing
OSGi
applications
support the
following
technologies:
v Web 2.5
v Web 3.0
v JPA
v JAX-RS
v JSF
Yes
Note: The
tools for
developing
OSGi
applications
support the
following
technologies:
v Web 2.5
v Web 3.0
v JPA
v JAX-RS
v JSF
v EJB
Yes
Note: The
tools for
developing
OSGi
applications
support the
following
technologies:
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, except
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 feature
packs and managed (federated) WebSphere Application Server Network
Deployment environments.
Advanced support
The following features are supported on the WebSphere Application Server full
profile, 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 feature
packs and managed (federated) WebSphere Application Server Network
Deployment 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 with
access to the Rational
Application Developer documentation.

Note: Some documented features are available only with the full Rational
Application Developer for WebSphere Software product.
For details about how to integrate the workbench with the server, see Testing and
publishing on a server.
Additional features available with Rational Application Developer
for WebSphere Software
For enterprise-level development, consider using Rational Application Developer
as your integrated development environment. Rational Application Developer
Chapter 1. IBM WebSphere Application Server Developer Tools for Eclipse, Version 9.0 Beta overview 3
provides a complete environment for Java, Java EE, web, web services, SOA, OSGi,
Web 2.0, mobile, and portal designers and developers, including the server
development tools. It also provides integration and support for the following
application servers and associated feature packs:
v WebSphere Application Server V8.5 Liberty Profile
v WebSphere Application Server V8.5
Rational Application Developer is designed to accelerate development and unit test
to ensure delivery of higher quality applications. It offers tools for teams that are
using the emerging trends of Web 2.0, SOA, OSGi, and Cloud computing that help
accelerate adoption and software delivery.
For more information about this product, see Rational Application Developer for
WebSphere Software or Rational Application Developer overview.
Chapter 2. The Liberty profile
The Liberty profile is a highly composable, fast to start, dynamic application server
runtime 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 runtime
environment (JRE), you must install a JRE provided by either IBM or Oracle
beforehand. For more information about supported Java environments, and where
to 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 WebSphere
Application Server programming model:
v Web applications
v OSGi applications
v Enterprise JavaBeans (EJB) applications
1
Associated services such as transactions and security are only supported when
required by these application types and by JPA.
Features are the units of functionality by which you control the pieces of the
runtime environment that are loaded into a particular server. For a list of the main
Liberty 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.
You can work with the runtime environment directly, or
use the WebSphere Application Server Developer Tools for Eclipse.
On distributed platforms, the Liberty profile provides both a development and an
operational environment. On the Mac, it provides a development environment.
Liberty profile: Architecture
The Liberty profile is a highly composable and dynamic runtime environment.
OSGi services are used to manage component lifecycles, and the injection of
dependencies and configuration. The server process comprises a single JVM, the
Liberty kernel, and any number of optional features. The feature code and most of
the kernel code runs as OSGi bundles within an OSGi framework. Features
provide 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. The
configuration is parsed, and then the configured features are loaded by the feature
manager. The kernel extensively uses OSGi services to provide a highly dynamic
runtime environment. The OSGi Configuration Admin service manages system
configuration, and an OSGi Declarative Services component manages the lifecycle
of system services. The file monitor service detects application and configuration
file changes, and the logging service writes messages and debug information to the
local file system.
OSGi
framework
(runtime)
Java 6+
Kernel
monitor-1.0
jsp-2.2 jsf-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 Configuration
Admin
File Monitor
OSGi Declarative
Services
Logging service
Feature bundle
Figure 2. Liberty profile kernel
Features are specified in the system configuration files that are the server.xml file
and any other included files. The server configuration files populate the OSGi
Configuration Admin service, which injects the feature configuration into the
feature manager service. The feature manager maps each feature name to a list of
bundles that provide the feature. The bundles are installed into the OSGi
framework and started. The feature manager responds to configuration changes by
dynamically adding and removing features while the server is running.
Runtime services provide configuration default settings so that the configuration
you 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 a
server.xml file. You might choose to structure your configuration into a number of
separate 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, the
kernel configuration management parses your configuration and applies it over the
system default settings. The set of configuration properties that belongs to each
service is injected into the service each time the configuration is updated.
useful-api-3.2.jar
useful-core-3_.
useful-extras-3.2_.
*
*
/lib/features/useful-3.2.mf
<featureManager>
<feature>useful-3.2</feature>
</featureManager>
server.xml
installs and starts
bundles in OSGi
framework
reads bundle
list
reads
config
injects config
Feature Manager
OSGi Configuration
Admin
Feature bundle
Figure 3. Feature management
Chapter 2. The Liberty profile 7
The OSGi Declarative Services component is used so that function can be
decomposed into discrete services, which are activated only when needed. This
behavior helps the runtime environment to be late and lazy, keeping the
footprint small and the startup fast. Declared services are added to the OSGi
service registry, and dependencies between services can be resolved without
loading implementation classes. Service activation can be delayed until a service is
used: when the service reference is resolved. Configuration for each service is
injected as the service is activated, and is reinjected if the configuration is later
modified.
Programming model support
This set of tables shows the extent to which each of the major server profiles
supports 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 a
specification reference, and an indication of whether the technology is supported by the full profile, and by the Liberty
profile.
Technology Specification reference Full profile Liberty profile
Java Platform, Enterprise
Edition 6 (Java EE 6)
JSR 316
Java Platform, Enterprise
Edition 6 Web Profile
JSR 316
Web services technologies

Java API for RESTful Web
Services (JAX-RS) 1.1
JSR 311
Implementing Enterprise Web
Services 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 defaults
Config metadata
injects merged
config into bundles
reads default
config from bundles
merges user
config over
defaults
optional
includes
Kernel bundle
OSGi Configuration
Admin
Config defaults
Config metadata
Feature bundle
Figure 4. Configuration management
Table 1. Java EE 6 support by profile (continued).
profile.
Java API for XML-Based Web
Services (JAX-WS) 2.2
JSR 224
Java Architecture for XML

Binding (JAXB) 2.2
JSR 222
Web Services Metadata for the

Java Platform
JSR 181
Java API for XML-based RPC

(JAX-RPC) 1.1
JSR 101
Java APIs for XML Messaging
1.3
JSR 67
Java API for XML Registries
(JAXR) 1.0
JSR 93
SOAP with Attachments API
for Java (SAAJ) 1.3
JSR 67
Web application technologies

Java Servlet 3.0 JSR 315
JavaServer Faces 2.0 JSR 314
JavaServer Pages
2.2/Expression Language 2.2
JSR 245
Standard Tag Library for
JavaServer Pages (JSTL) 1.2
JSR 52
Debugging Support for Other
Languages 1.0
JSR 45
Enterprise application
technologies
Contexts and Dependency
Injection for Java (Web Beans
1.0)
JSR 299
Dependency Injection for Java

1.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 EJB
Lite subset and Message
Driven Beans.)
Java EE Connector Architecture
1.6
JSR 322
Java Persistence 2.0 JSR 317
Common Annotations for the
Java Platform 1.1
JSR 250 (The Liberty profile does not
support @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).
profile.
Management and security
technologies
Java Authentication Service
Provider Interface for
Containers
JSR 196
Java Authorization Contract for
Containers 1.3
JSR 115
Java EE Application
Deployment 1.2
JSR 88
J2EE Management 1.1 JSR 77
Java EE-related specifications
in 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 Activation
Framework (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 by
the 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 by
the 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 are
not supported.)
Remote Services R4.2 Compendium Chapter 13
SCA Configuration Type
Specification
R4.2 Enterprise Chapter 129
Remote Bundle Repositories
SIP (SIP annotations are not
supported.)
Liberty profile externals support
External functions and resources of the Liberty profile can be used directly, and
can be relied on to be in the next release. Internal or incidental aspects of the
profile 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 the
next release?
The following resources can be used directly and will continue to be available in
the 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 Liberty
feature 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 be
impacted when you apply service or upgrade to future releases. Examples of
product internals that you should avoid relying on include, but are not restricted
to, 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/javadoc
directory of the server image.
v Direct use of the product binaries in the /lib directory. The only JAR files that
can 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 be
modified when service or upgrade is applied. Do not make your own
modifications to files in these locations, or they might be overwritten by product
maintenance 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 are
your 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 backward
compatibility. These are Java packages that are considered part of the
implementation of features developed in open source communities and delivered
as part of the Liberty profile. Third-party APIs are not visible to applications by
default; Java EE applications with a classloader configuration that explicitly allows
third-party access will have visibility to those packages on the application class
loader, and OSGi applications must explicitly import the packages. Consider the
impact of incompatible changes before deciding to use third-party APIs.
Liberty profile: Server configuration
The Liberty profile is configured by exception. The runtime environment operates
from a set of built-in configuration default settings, and you only need to specify
configuration that overrides those default settings. You do this by editing either the
server.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 work
with later versions of the runtime environment.
v Dynamically responsive to updates.
v Forgiving, so that missing values are assumed and unrecognized properties are
ignored.
runtime environment that are loaded into a particular server. They are the primary
mechanism that makes the server composable. The list of features that you specify
in the server configuration provides a functional server. See Liberty features on
page 14.
When you first install and start the server, a feature manager and a default server
configuration 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 environment
that is designed to cover most common requirements, therefore you only need to
specify changes from the default configuration.
For a full list of the elements that you can configure to complement or modify the
configuration provided by Liberty features, see Liberty profile: Configuration
elements in the server.xml file on page 97.
You can also use a bootstrap.properties file to specify properties that are needed
before the main configuration is processed, and to define variables that are used in
the main configuration.
Service author perspective: Runtime management of
configuration
The Liberty profile configuration service parses the primary server.xml file and
any files it includes, merges the contents over the default configuration values
provided by the installed bundles, then feeds the resulting property sets into the
OSGi Configuration Admin Service (CA). CA injects each set of properties into the
service that owns the set, if it is registered with CA.
The ordering of these steps is flexible. Services can register with CA before or after
the initial property sets are established. Properties can be updated in CA after the
initial injection, at which time the updated properties are injected into the owning
service. It is therefore important that the services can receive, and respond
appropriately to, updates to their configuration at any time that the service is
active. Specifically, if a service delays its activation until its configuration is
available, it must still be able to activate.
To enable a service to receive configuration data, there are a number of steps
involved. See Enabling a service to receive configuration data on page 436.
Liberty profile: Feature management
runtime 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 each
feature 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 include
other features within them. The same feature can be included in one or more other
features. At run time, the feature manager computes the combined list of content
that is required to support the requested set of features.
For information about the main available features, see Liberty features. For
information 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 the
list of required bundles, stops and uninstalls those bundles that are no longer
required, and installs and starts any additions. All features are therefore designed
to 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 of
features might provide an advantage over using the superseded feature. For
example, new, finer-grained features might be used in place of the superseded one
in order to reduce the server footprint by excluding content that might not be
necessary. The new feature or features might not completely replace the function of
the superseded feature, so you must consider your scenario before deciding
whether to change your configuration. Superseded features remain completely
supported and valid for use in your configuration; the superseded label just
provides an indication that you might be able to improve your configuration.
Liberty features
runtime environment that are loaded into a particular server.
The following list contains information about the main available features. Including
a feature in the configuration might cause one or more additional features to be
loaded automatically. For example, if you include the wab-1.0 feature, the
servlet-3.0 and blueprint-1.0 features are loaded automatically. Each feature
includes a brief description, and an example of how the feature is declared within
the <featureManager> element inside the server.xml file. For example:
<server>
<featureManager>
</featureManager>
</server>
For a full list of available features, see the .mf files under the lib/features
directory 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 in
the Liberty profile. The file name matches the feature name. For example, the
servlet-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 each
layer of an application.
The validation can be applied to all layers of JavaBeans in an application
by 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 OSGi
applications that use the OSGi blueprint container specification.
With the OSGi Applications support in WebSphere Application Server, you
can develop and deploy modular applications that use Java EE and OSGi
technologies.
CDI
<feature>cdi-1.0</feature>
The cdi-1.0 feature enables support for the Contexts and Dependency
Injection 1.0 specification on the Liberty profile.
The supported entry point into CDI is through an expression language
lookup of an @Named CDI style bean, with other CDI beans injected into
it. 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 a
management collective and includes a management repository MBean that
is accessible using the JMX/REST connector that is provided by the
restConnector-1.0 feature. The collective controller acts as a storage and
collaboration mechanism to which collective members can connect. The
collectiveController-1.0 feature includes a ServerCommandMbean that
can be used to remote start or stop servers that are managed by the
collective controller.
See Setting up the server-management environment for the Liberty
profile on page 401.
Collective member
<feature>collectiveMember-1.0</feature>
The collectiveMember-1.0 feature enables a server to be a member of a
management collective, allowing it to be managed by the collective
controller.
See Setting up the server-management environment for the Liberty
Enterprise JavaBeans (EJB) Lite subset
<feature>ejblite-3.1</feature>
The ejblite-3.1 feature provides support for EJB applications written to the
EJB 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 Web
Services 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-Based
Web Services on the Liberty profile.
v For web applications that use the jaxws-2.2 server
feature, you must enable the servlet-3.0 and jsp-2.2 features in the
server.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 the
server.xml file.
v For JAX-WS client applications, you can use both
unmanaged 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 XML
Binding (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>
The jdbc-4.0 feature provides support for applications that access a
database. You can take an existing application that uses Java Database
Connectivity (JDBC) and a data source, and deploy the application to a
server.
See also Deploying an existing JDBC application to the Liberty profile on
page 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 in
the 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 use
application-managed and container-managed JPA written to the JPA 2.0
specification.
The support is built on top of Apache OpenJPA with extensions to support
the container-managed programming model.
Extended Persistence Context is now available for use with
Stateful Session beans.
See also Deploying a JPA application to the Liberty profile on page 530
and 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 JSF
framework. 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 JSP
2.2 specification.
If you include the jsp-2.2 feature, you also include the servlet-3.0
feature.
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 a
set of JSON handling classes for Java environments. The JSON4J library
provides a simple Java model for constructing and manipulating data to be
rendered as JSON data.
See also Using JSON content in JAX-RS application requests and responses
and JSON4J Libraries API.
Local JMX Connector
The localConnector-1.0 feature provides a local JMX connector that is
built into the JVM. The JMX connector can be used only on the same host
machine by someone running under the same user ID and the same JDK. It
enables local access by JMX clients such as jConsole, or other JMX clients
that 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 time
to be initialized. The messaging run time is responsible for providing the
application connectivity, managing the state of destinations such as topics
or queues, and handling Quality of Service, security, and transactions.
<feature>jmsMessaging-1.1</feature>
The wasJMSClient-1.1 feature enables support for JMS resource
configuration required by the messaging applications to connect to the JMS
Server on the Liberty profile
<feature>jmsComms-1.0</feature>
The jmsComms-1.0 feature provides support for inbound connections from
the remote messaging application. The remote messaging applications can
connect to the JMS messaging engine through TCP/IP. The applications
can also connect securely using SSL. To connect using SSL, you must
enable 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 the
messaging engine. When the wasJMSSecurity-1.0 feature is enabled, it
starts authenticating and authorizing the users who are trying to connect to
the messaging engine. The user 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 a particular role, the user must have the
access to that destination. The access to the destination is defined in the
<messagingSecurity> element in the server.xml file. If the
wasJMSSecurity-1.0 feature is added and the <messagingSecurity> element
is missing in the server.xml file, then the users can neither connect to the
messaging engine nor perform any messaging action (for example, sending
or receiving messages from the destinations).
Notes:
v 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 is enabled.
v When you enable the jmsSecurity-1.0 feature, you must also configure
the <messagingSecurity> element in the server.xml file. This enables
authorized 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 and
associated database connections. Access to MongoDB connections is
available either by JNDI lookup or resource injection. The native
com.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 on
the Liberty profile.
REST connector
<feature>restConnector-1.0</feature>
The restConnector-1.0 feature provides a secure JMX connector that can
be used locally or remotely using any JDK. It enables remote access by
JMX clients through a REST-based connector and requires SSL and basic
user 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 this
feature.
The Liberty profile provides a dummy keystore and a dummy truststore,
which are the same as those provided by previous versions of WebSphere
Application Server.
The secure HTTPS listener is not started unless the ssl-1.0 feature is
enabled. 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 Liberty
profile bootstrap properties on page 95.
Security
<feature>appSecurity-2.0</feature>
This version of the appSecurity feature secures only
applications that are based explicitly on the presence of other features. If
the servlet-3.0 feature is present with the appSecurity-2.0 feature, web
applications are secured. If the servlet-3.0 feature is not present, then
web applications are not secured. If the ejblite-3.1 feature is present with
the appSecurity-2.0 feature, EJB applications are secured. If the
ejblite-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 can
choose to use the appSecurity-2.0 version instead in your server
configuration. See Superseded feature on page 14.
The appSecurity-1.0 feature provides support for securing the server
runtime environment and applications. The following aspects are
supported:
v Basic user registry
v Lightweight Directory Access Protocol (LDAP) user registry
v Basic authorization
v 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
getCallerIdentity
3
.
When you add the appSecurity-1.0 or appSecurity-2.0 feature to your
server, you must also configure a user registry, such as the basic user
registry or the LDAP user registry.
See also Chapter 9, Securing the Liberty profile and its
applications, on page 445 and appSecurity-2.0 feature restrictions on
page 568.
Server status
<feature>serverStatus-1.0</feature>
The serverStatus-1.0 feature enables Liberty profile servers to
automatically publish their status to WebSphere Application Server
deployment managers and job managers that are aware of the server as a
resource in their Job configuration. The known states are Started and
Stopped.
See Submitting jobs to manage Liberty profile servers and Installing
Liberty profile server resources using the job manager.
Servlet
The servlet-3.0 feature provides support for HTTP Servlets written to the
Java Servlet 3.0 specification.
See also Chapter 9, Securing the Liberty profile and its applications, on
page 445.
Session Persistence
<feature>sessionDatabase-1.0</feature>
The sessionDatabase-1.0 feature provides session affinity and failover
support on the Liberty profile.
3. The getCallerIdentity API is not supported for Singleton session beans.
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 enterprise
bundles.
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 and
blueprint-1.0 features.
Web services security
<feature>wssecurity-1.0</feature>
The wssecurity-1.0 feature provides support for securing web services at
the message level. To secure web services messages, you must enable this
feature. Web services security policies defined in a WSDL file are ignored
and 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 shared
libraries, global libraries, and automatic shared libraries to reduce the number of
duplicate library files on your system.
Library elements
Liberty profile libraries have three elements; <folder>, <file>, and <fileset>. For
example:
<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) rather
than the resource itself.
If an element in the list is a file, the contents of that JAR or compressed .zip file are
searched. 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 global
library directory, and then are specified in the class loader configuration for each
application.
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, and
that application does not have a <classloader> element configured, the application
uses these libraries. If a class loader configuration is present, these libraries are not
used 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 the
same as the directory name. When creating automatic shared libraries, only a
reference to the directory name of the library is required.
Resource files and JAR files are picked up and made available from the automatic
shared 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 the
automatic 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 Liberty
profile server, or you can package them for delivery to your users.
The Liberty profile provides various System Programming Interfaces (SPIs) that
you can use to extend the runtime environment; you can also use more advanced
features such as operating the Liberty profile server from your Java applications
programmatically.
Product extension
A product extension is a directory on disk that is structured like the Liberty profile
installation directory, wlp. It is defined to the Liberty installation through a file in
the wlp/etc/extensions directory called extension-name.properties. The contents
of the product extension directory are then used to extend the Liberty profile.
Multiple product extensions can be installed together but they must have unique
names; this is enforced through the naming of the properties files. The default
product extension location, wlp/usr/extension, does not require a properties file;
content under this location is automatically detected and is known to the runtime
as the usr product extension.
Product extensions usually contain one or more Liberty features but can have any
content that extends the Liberty profile environment, for example scripts or
resources.
Feature
A Liberty feature consists of a definition file (feature manifest), and a collection of
OSGi bundles that provide classes and services corresponding to a particular
capability in the Liberty profile runtime environment.
Scenarios for using a Liberty feature instead of a regular
application
Implementing a function as a Liberty feature instead of as an application might be
appropriate in a number of scenarios. The following list describes some of the
benefits 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 tools
having to be changed.
v Features can easily expose classes and services to each other and to user
applications.
v Features can be extremely lightweight with no application container
dependencies.
v Features can be used to augment a particular programming model. For example,
a User Feature can add support for custom Blueprint namespace handlers or
Blueprint annotations to the OSGi Application programming model.
Note: Features cannot generally be directly portable to other application servers; if
portability is important you should use specification-compliant applications.
Developing a simple feature
See Developing a Liberty feature manually on page 419, Creating a Liberty
feature 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 a
product extension directory. This might be the predefined user product extension
location or an extension that is located outside the Liberty profile installation
directory. Then you can add the feature name into the server configuration.
The user product extension is a predefined directory where the server looks for
additional features. The feature definition .mf file must be copied into the
${wlp.user.dir}/extension/lib/features directory and the bundle .jar files must
be copied into the ${wlp.user.dir}/extension/lib directory.
User-written features are added to the server configuration in the same way as
product features. To avoid name clashes with features from different providers,
features that are part of a product extension must be prefixed with the extension
name. 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 the
server.xml as follows:
<featureManager>
<feature>usr:simple-1.0</feature>
</featureManager>
If you have installed a feature called myFeature into your own location, and
defined a product extension in the wlp/etc/extensions/myExt.properties file, you
must 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 the
bundles 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 the
IBM-API-Package header in the feature manifest. Listing the class packages in the
IBM-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 the
IBM-API-Service header in the feature manifest. A feature provides OSGi services
so that you can refer to those services programmatically from your applications.
Services should generally be registered into the OSGi Service Registry (SR) to allow
applications (or other features) to locate them. OSGi applications and other features
can perform a direct lookup from the SR, or can use capabilities such as Blueprint
or OSGi Declarative Services to inject their service dependencies. Java EE
applications are more likely to locate services through JNDI; in the Liberty profile
there is a federation of the SR and JNDI that allows Java EE applications to use
JNDI to locate services in the SR. For more information, see Working with the
OSGi 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 OSGi
bundles in the feature as web application bundles (WABs). In addition to the OSGi
headers that a bundle requires, you can specify the web application context path
by using the Web-ContextPath header.
For example:
Web-ContextPath: myWABapp
Webapp-Context: myWABapp
Bundle-ClassPath: WEB-INF/classes
Configuration injection and processing
A major benefit of using features is that they can be easily configured by the user
in the server.xml file (and included files). The configuration files are monitored
and parsed by the Liberty profile kernel and the resulting sets of properties can be
injected 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 of
configuration properties are identified by a persisted identity (PID) that is used to
associate the element in the server.xml file with the component that registers to
receive the properties.
For example, if you register your feature with the CA service using a PID of
com.acme.console, a user can specify the following configuration in the server.xml
file:
<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 properties
by using OSGi Metatype descriptors. The use of descriptors causes your
configuration metadata to be included in the configuration schema that is
generated by the liberty profile and is used by the Developer Tools, so your
configuration properties are automatically presented to application developers as
they configure their server.
For more details on receiving and describing configuration
properties, 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 Declarative
Services (DS) to enable the feature to be composed of multiple services, and to
manage the injection of dependencies and configuration properties. The use of DS
allows lazy activation of services, deferring the loading of Java classes until the
service 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 Declarative
Services on page 434.
Liberty profile: Security
Liberty profile security provides protection for web resources as per the Servlet 3.0
specification, and protection for the JMX connections when you are using the REST
connector.
The following diagram shows a typical security process involved when accessing a
protected web resource. To make the security process work, you must configure
the 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 an
exception for the authentication failure.
5. The WebSecurity Collaborator uses the Authorization service to perform a user
authorization check.
6. The Authorization service returns the authorization result to the WebSecurity
Collaborator.
7. The WebSecurity Collaborator returns the result of the security check about
whether the user is authorized.
8. The WebContainer serves or rejects the requested resource.
The following sections provides a summary of the primary security components in
the Liberty profile:
v Quick start on page 27
v Authentication on page 27
v Authorization on page 27
v Secure Socket Layer (SSL) on page 27
v Single Sign-On (SSO) on page 27
v Web security-related properties on page 27
v Security public APIs on page 28
v Management security on page 28
v
2
1
7
8
3 6
4 5
WebContainer
WebSecurity
Collaborator
Authentication
service
Authorization
service
Browser/HTTP client
Figure 5. Typical security flow for web resources
v Authentication aliases on page 28
v Configuration examples and samples on page 28
v Security compatibility and differences on page 28
v Troubleshooting on page 28
v
Tools on page 28
Quick start
With the quickStartSecurity element, you can configure a single user security
environment in the Liberty profile. See Liberty profile: Quick overview of
security on page 29 for details of how the security workflow is when you use the
quickStartSecurity element, and Getting started with security in the Liberty
profile on page 445 for a sample task.
Authentication
Authentication confirms the identity of a user. The most common form of
authentication is user name and password, such as through either basic
authentication 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. This
process 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 the
Liberty profile on page 459 for detailed tasks.
Authorization
Authorization determines whether to grant a user access to resources within the
system. The Java EE model uses subjects, resources, and roles to determine what
can and cannot be allowed. This process involves checking the user credentials
such as the user ID and password, certificates, and tokens, and creating a subject
based on the authenticated user. See Liberty profile: Authorization on page 40
for more concepts and Authorizing access to resources in the Liberty profile on
page 472 for detailed tasks.
Secure Socket Layer (SSL)
SSL provides transport level security. See Enabling SSL communication for the
Liberty profile on page 449 for detailed tasks.
Single Sign-On (SSO)
SSO enables access to applications without the user being prompted to login
multiple times. See Concept of SSO for more details and Customizing SSO
configuration using LTPA cookies for the Liberty profile on page 468 for the
detailed task.
Web security-related properties
There are many configuration properties that you can configure as part of web
security, such as SSO and client certificate authentication, for your applications. See
Liberty profile: Configuration elements in the server.xml file on page 97 for
available attributes and see Configuring web security related properties for the
Liberty profile on page 493 for some examples.
Security public APIs
The Liberty profile contains public APIs that you can use to implement security
functions. The security public APIs in the Liberty profile are a subset of the full
profile security public APIs. The main classes are WSSecurityHelper, WSSubject,
and RegistryHelper. These classes contain a subset of the methods that are
available 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 separate
JAR file under the /dev/ibm-api/javadoc directory of the server image.
See Developing extensions to the Liberty profile security infrastructure on page
497 for some examples.
Management security
Management security means that you can manage the Liberty profile by using a
remote JMX client. To secure remote connections using the REST connector, see
Connecting to the Liberty profile by using JMX on page 386. You can also
develop your own JMX client application as described in Developing a JMX Java
client 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 security
configurations. You can refer to those examples when you configure security for
your application in the Liberty profile.
Security compatibility and differences
You can learn about the main differences in the security capability between the full
profile and the Liberty profile. See Configuration differences between the full
profile and Liberty profile: security on page 46.
Troubleshooting
Use the troubleshooting information to solve security-related problems when you
use 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 Liberty
profile. See Editing the Liberty profile configuration by using developer tools on
page 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 security
This topic describes some common security terms, along with an example that
helps you understand the basic workflow of security in the Liberty profile.
Security key terms
Authentication
authentication is user name and password, such as through basic
authentication or form login for web applications. When a user is
authenticated, the source of a request is represented as a Subject object at
run time.
Authorization
Authorization determines whether a user has access to a given role within
the system. The Java EE model uses subjects, roles, and role mappings to
determine if access is allowed.
Role A role is defined within the Java EE application. Some roles, such as the
Administrator role, are predefined by the system. Other roles are defined
by the application developer. In Java EE, subjects are usually granted or
denied access to a role based on the roles they perform within the
application.
Subject
A subject is both a general term and a Java object:
javax.security.auth.Subject. Generally, the term subject means active
entities within the system, such as users on the system, and even the
system process itself.
Security workflow example
The following example demonstrates how the security is applied when a user
requests access to a resource. For example, a user Bob wants to access a servlet
myWebApp. See the code samples in Getting started with security in the Liberty
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 access
to the servlet myWebApp is denied.
Another user Alice can log in to the system because Alice is a valid user. But
Alice is not in the testing role. An HTTP 403 error (Access Denied/Forbidden)
displays when Alice logs in.
Liberty profile: Authentication
Authentication 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 process
involves collecting this user credential information (based on how the web
application was configured to collect this data) and validating it against the
configured registry. When the credential information is verified, a JAAS subject is
created 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 to
determine whether the user can access the resource.
The following diagram illustrates a typical authentication process flow for a web
resource.
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 absence
calling the JAAS service to perform the authentication to create a subject. The
JAAS service calls a set of login modules to handle the authentication. One or
more of the login modules creates the subject depending on the credential data.
The login module then calls the registry that is configured to validate the
credential information. If the validation is successful, the authentication process
collects and creates relevant information for that user, including the groups that the
user belongs to and the single sign-on (SSO) token used for SSO capability, and
stores them in the subject as relevant credentials. You can also customize the
information saved in the subject by plugging in custom login modules during this
process.
When the authentication is successful, the SSO token that is created during the
process is sent back to the browser in a cookie. The default name of the
configurable cookie is ltpaToken2. On subsequent calls, the token information is
Authentication
service
AuthCache
service
JAAS
service
Subject
permit/deny
ID/password
SSOToken
certificate
Browser/HTTP client
UserRegistry
service
Credential
service
Token
service
Figure 6. Overview of authentication process
used to authenticate the user. If this authentication fails, the authentication service
tries to use other authentication data, such as the user ID and password, if they
still 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 32
v Callback handler on page 33
v Credentials and tokens on page 33
v LTPA on page 33
v Single sign-on (SSO) on page 34
v Pluggable authentication on page 35
v Identity assertion on page 35
v RunAs() authentication on page 37
v Proxy login module on page 37
v Certificate login on page 37
v Hash table login module on page 38
User registries
When validating the authentication data of a user, the login modules call the user
registry that is configured to validate the user information. The Liberty profile
supports both a simple configuration-based user registry and a more robust
LDAP-based repository. For more information, see Configuring a user registry for
the Liberty profile on page 459.
Authentication cache
Because creating a subject is relatively expensive, the Liberty profile provides an
authentication cache to store a subject after the authentication of a user is
successful. The default expiration time for the cache is 10 minutes. If the user does
not log back in within 10 minutes, the subject is removed and the process of
authentication repeats to create a subject for that user. Changes to the configuration
that affect the creation of the subject, such as adding a login module or changing
the LTPA keys, will cause the authentication cache to be cleared. If the subject is
cached and the information in the registry changes, the cache is updated with the
information in the registry. You can configure the cache timeout period, and the
cache 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 Liberty
profile supports the following JAAS configurations:
system.WEB_INBOUND
Used when accessing web resources such as servlets and JSPs.
WSLogin
Used by applications when using the programmatic login.
system.DEFAULT
Used for login when no JAAS configuration is specified.
The system.WEB_INBOUND and system.DEFAULT configurations have these
default login modules in this order: hashtable, userNameAndPassword,
certificate, and token. The WSLogin configuration has the proxy login module as
the default login module, and the proxy delegates all the operations to the real
login module in system.DEFAULT.
No explicit configuration is required unless you want to customize by using the
custom login modules. Depending on the requirement, you can customize specific
login configurations. For example, if you want all the web resource logins to be
customized, you must add custom login modules only to the system.WEB_INBOUND
configuration. See Configuring a JAAS custom login module for the Liberty
JAAS login modules
JAAS configuration uses a set of login modules to create the subject. The Liberty
profile provides a set of login modules in each of the login configurations.
Depending on the authentication data, a particular login module creates the
subject. The authentication data is passed to the login modules by using the
callback handler, as specified in the JAAS specification. For example, if the user ID
and password callback handler is being used for authentication, the
userNameAndPassword login module handles the authentication. If a
SingleSignonToken credential is presented as the authentication data, only the
token login module handles the authentication.
The following default login modules are supported in the Liberty profile:
userNameAndPassword
Handles the authentication when user name and password are used as the
authentication data.
certificate
Handles the authentication when an X509 certificate is used as the
authentication data of mutual SSL.
token Handles the authentication when an SSO token is presented as the
authentication data. During the authentication process, an SSO token is
created and sent back to the HTTP client (browser) in a cookie. On
subsequent requests, this cookie is sent back by the browser and the server
extracts the token from the cookie to authenticate the user when the single
sign-on is enabled.
hashtable
Used when the authenticated data is sent through a predefined hash table.
For more information about the hash table login, see Hash table login
module on page 38. This login module is also used by the security run
time when authentication is performed using identity only; for example, in
the case of runAs.
proxy The default login module for WSLogin. See Proxy login module on page
37.
The login modules are called in the order that they are configured. The default
order is hashtable, userNameAndPassword, certificate, token. If you must
customize 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 module
first in the list of login modules so that it is called first. When a custom login
module is used, you must specify all the login module information in the
configuration along with the custom login module in the required order.
When a login module determines that it can handle the authentication, it first
makes sure that the authentication data that is passed in is valid. For example, for
user name and password authentication, the configured user registry is called to
verify the authentication information. For token authentication, the token must be
decrypted and valid for the verification to succeed.
When the authentication data is validated, the login modules create credentials
with additional data for the user including the groups and the SSO token. A
custom login module can add additional data to the subject by creating its own
credentials. For the Liberty profile authorization to work, the subject must contain
the WSCredential, WSPrincipal, and SingleSignonToken credentials. The
WSCredential credential contains the groups information, with additional
information that is required by the security runtime environment.
Callback handler
The Liberty profile supports various callback handlers for providing data to the
login modules during the JAAS authentication process. A custom login module can
use the callback handler information to authenticate itself. For example, if the
callback handler needs to access some information in an HttpServletRequest
object, it can do so by using that specific callback handler.
The following callback handlers and factories for programmatic JAAS login are
supported 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 on
page 499.
Credentials and tokens
As mentioned in the loginModule section, credentials are created as part of the
subject creation process. The Liberty profile creates the WSCredential,
SingleSignonToken, and WSPrincipal credentials. The SingleSignonToken credential
contains 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 and
encrypted by using the Lightweight Third Party Authentication (LTPA) keys that
are generated during the first server startup. The default expiration time is 2 hours
and is an absolute time, not based on user activities. After the 2 hours, the token
expires and the user must log in again to access the resource.
LTPA
LTPA is intended for distributed and multiple application server environments. In
the Liberty profile, LTPA supports SSO and security in a distributed environment
through cryptography. This support enables LTPA to encrypt, digitally sign, and
securely transmit authentication-related data, and later decrypt and verify the
signature.
Application servers can securely communicate using the LTPA protocol. The
protocol also provides the SSO feature, whereby a user is required to authenticate
only when connecting to a domain name system (DNS). Then the user can access
resources in other Liberty profile servers in the same domain without getting
prompted. The realm names on each system in the DNS domain are case-sensitive
and must match identically.
The LTPA protocol uses cryptographic keys to encrypt and decrypt user data that
passes between the servers. These keys must be shared between different servers
for the resources in one server to access resources in other servers, assuming that
all the servers involved use the same user registry. LTPA requires that the
configured user registry must be a centrally shared repository so that users and
groups are the same, regardless of the server.
When using LTPA, a token is created that contains the user information and an
expiration time, and is signed by the keys. The LTPA token is time sensitive. All
participating servers must have their time and date synchronized. If not, LTPA
tokens are prematurely expired and cause authentication or validation failures.
Coordinated Universal Time (UTC) is used by default, and all other servers must
have the same UTC time. See your operating system documentation for
information about how to ensure the same UTC time among servers.
The LTPA token passes to other servers through cookies for web resources when
SSO is enabled.
If the receiving servers use the same keys as the originating server, the token can
be decrypted to obtain the user information, which then is validated to make sure
that the token is not expired and that the user information in the token is valid in
its registry. On successful validation, the resources in the receiving servers are
accessible after the authorization check.
Each server must have valid credentials. When the credentials expire, the server is
required to communicate to the user registry to authenticate. Extending the time
that the LTPA token remains cached presents a slightly increased security risk to be
considered when defining your security policies.
If key sharing is required between different Liberty profile servers, copy the keys
from one server to another. For security purposes, the keys are encrypted with a
randomly-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. The
password 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 profile
server start time. For more information about the LTPA support, see Configuring
LTPA 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 access
applications on other servers without getting prompted again. To make SSO work,
the LTPA keys must be exchanged across different Liberty profile servers, the user
registries 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 restart
the server to use the new LTPA keys. The registries that are used by all the servers
participating in the SSO domain must be the same.
When a user is authenticated in one Liberty profile server, the SSO token created
for the user during the authentication process is put in the cookie that is sent to
the HTTP client, for example a browser. If there is another request from that client
to access another set of applications on a different server, but in the same DNS that
was configured as part of the SSO configuration in the first server, the cookie is
sent along with the request. The receiving server tries to authenticate the user
using the token in the cookie. If both conditions are met, the receiving server
validates the token and creates a subject based on the user in this server, without
prompting 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 is
prompted to enter the credential information again.
Any application that is configured to use the Form-login attribute must have SSO
to 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 user
when the resource is accessed.
See Customizing SSO configuration using LTPA cookies for the Liberty profile on
page 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-based
authentication. See Developing a custom TAI for the Liberty profile on page
498.
For more details about the JAAS login module and TAI, see Advanced
authentication in WebSphere Application Server.
Identity assertion
Besides authentication that requires a requesting entity to prove its identity, the
Liberty profile also supports identity assertion. This is a relaxed form of
authentication that does not require identity proof, but rather accepts the identity
based on a trust relationship with the entity that vouches for the asserted identity.
Use the following ways to assert identities in the Liberty profile
1. 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 use
IdentityAssertionLoginModule, use the JAAS login framework, where trust
validation is accomplished in one custom login module and credential creation
is accomplished in IdentityAssertionLoginModule. You can use the two login
modules to create a JAAS login configuration that can be used to assert an
identity.
The following two custom login modules are required:
User implemented login module (trust validation)
The user implemented login module performs whatever the user
requires in trust verification. When trust is verified, the trust
verification status and the login identity must be put into a map in the
share state of the login module, so that the credential creation login
module can use the information. Store this map in the following
property:
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 of
the login context.
The identity assertion login module looks for the trust information in
the shared state property:
This property contains the trust status and the identity to log in, and
must 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 not
trusted.
v
com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.principal
This property contains the principal of the identity to log in if a
principal is used.
v
com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certificates
This property contains an array of a certificate chain that contains the
identity to log in if a certificate is used.
A WSLoginFailedException message is returned if the state, trust, or
identity information is missing. The login module then logs in with the
identity, and the subject contains the new identity.
See Customizing an application login to perform an identity assertion using
JAAS on page 503.
RunAs() authentication
When you have successfully authenticated after calling a servlet, the servlet can
make subsequent calls, for example to other servlets. These subsequent calls are
normally made under the same security identity that you originally used to log in
to the servlet. This identity is known as the caller identity. Alternatively, you can
choose to delegate to a different identity by using the RunAs specification, so that
any subsequent calls that the servlet makes run under this other identity. To
summarize, 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 the
RunAs user. If this authentication fails, the server falls back to propagate the caller
identity.
To use the RunAs specification, you must update the deployment descriptor of
your application to include the run-as element or @RunAs annotation. Set this
element 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 and
delegates all the operations to the real login module implementation. The real login
module implementation is specified as the delegate option in the option
configuration. The proxy login module is required because the application class
loaders do not have visibility of shared library class loaders of the application
server product. With an application programmatic login that uses the Login()
method of the LoginContext class with JAAS login context entry WSLogin, the
proxy login module delegates all the work to the JAAS login context entry
system.DEFAULT.
Certificate login
With the certificate login feature, you can authenticate web requests such as
servlets by using client side X509 certificates instead of supplying a user ID and
password.
Certificate authentication works by associating a user in the user registry with the
distinguished name in the client certificate of a web request. Trust is established by
having the client certificate trusted by the server, for example the signer of the
client certificate must be in the trust store of the server. This mechanism eliminates
the 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 hash
table, and then add the hash table to the shared state. If the identity is switched in
this login module, you must add the hash table to the shared state. If the identity
is not switched, but the value of the requiresLogin code is true, you can create the
hash 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 consider
creating a hash table to gather attributes in special cases. For example, if you are
using your own special user registry, then creating a UserRegistry implementation,
using a hash table, and letting the server gather the user attributes for you, might
be a simple solution.
The following rules define in more details about how a hash table login is
completed. You must use a java.util.Hashtable object in either the Subject (public
or private credential set) or the shared-state HashMap. The
com.ibm.wsspi.security.token.AttributeNameConstants class defines the keys that
contain the user information. If the Hashtable object is put into the shared state of
the login context using a custom login module that is listed before the hashtable
login module, the value of the java.util.Hashtable object is searched using the
following key within the shared-state hashMap:
Property
com.ibm.wsspi.security.cred.propertiesObject
Reference to the property
AttributeNameConstants.WSCREDENTIAL_PROPERTIES_KEY
Explanation
This key searches for the Hashtable object that contains the required
properties in the shared state of the login context.
Expected result
A java.util.Hashtable object.
If a java.util.Hashtable object is found inside the Subject or within the shared
state area, verify that the following properties are present in the hash table:
v com.ibm.wsspi.security.cred.uniqueId
AttributeNameConstants.WSCREDENTIAL_UNIQUEID
Returns
java.util.String
Explanation
The value of the property must be a unique representation of the user.
For the Liberty profile default implementation, this property represents
the information that is stored in the application authorization
configuration. The information is in the application deployment
descriptor after it is deployed and the user-to-role mapping is
performed. See the expected format examples if the user to role mapping
is performed by looking up a user registry implementation of the Liberty
profile.
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
AttributeNameConstants. WSCREDENTIAL_ SECURITYNAME
Returns
java.util.String
Explanation
This property searches for securityName of the authentication user. This
name is commonly called the display name or short name. The Liberty
profile uses the securityName attribute for the getRemoteUser,
getUserPrincipal, and getCallerPrincipal application programming
interfaces (APIs). To ensure compatibility with the default
implementation for the securityName value, call the public String
getUserSecurityName(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
AttributeNameConstants. WSCREDENTIAL_GROUP
Returns
java.util.ArrayList
Explanation
This 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 format
of these groups is important because the groups are used by the Liberty
profile authorization engine for group-to-role mappings in the
deployment descriptor. The format that is provided must match the
format expected by the Liberty profile default implementation. When
you use a third-party authorization provider, you must use the format
that is expected by the third-party provider. To ensure compatibility with
the default implementation for the unique group IDs value, call the
public List getUniqueGroupIds(String uniqueUserId) UserRegistry
method.
Table 5. Format examples for group. This table gives some format examples when
configuring 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 examples
when configuring inbound identity mapping.
User Registry Format (group) value
Basic basicRegistryRealm/group1
The com.ibm.wsspi.security.cred.group property is required. A user is
not required to be associated groups.
v com.ibm.wsspi.security.cred.cacheKey
AttributeNameConstants. WSCREDENTIAL_CACHE_KEY
Returns
java.lang.Object
Explanation
This key property can specify an object that represents the unique
properties of the login, including the user-specific information and the
user dynamic attributes that might affect uniqueness. For example, when
the 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 the
correct 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 is
specified for WSCREDENTIAL_UNIQUEID. When this information is
found in the java.util.Hashtable object, the Liberty profile creates a
Subject similar to the Subject that goes through the normal login process,
at least for LTPA. The new Subject contains a WSCredential object and a
WSPrincipal object that is fully populated with the information found in
the Hashtable object.
Liberty profile: Authorization
Authorization in the Liberty profile determines whether a user has access to a
given role within the system.
Authorization specifies access rights to resources. It usually follows authentication
that confirms an identity. Whereas authentication answers the question: "Are you
who you say you are?"; authorization answers the question: "Do you have
permission 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 41
v Special subjects on page 42
v Access IDs and authorization on page 42
Authorization for administrative functions
When an entity attempts to access a resource, the authorization service determines
whether that entity has the required rights to access the resource. This concept
holds true whether an entity is accessing an application or performing
administrative functions. The main difference between authorizing access to an
application and access to an administrative function lies in how the users are
mapped to roles. For authorization of applications, use the application-bnd
element 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 the
administrator-role element in the server.xml file to map the users to the
administrator 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 an
application served by the Liberty profile. The web container calls the
authorization service to determine whether a user has permission to access a
certain resource, given a set of one or more required roles. The required roles
are determined by the auth-constraint elements in the deployment descriptor
and @ServletSecurity annotations.
2. The authorization service determines what objects the required role is mapped
to. This step is accomplished by processing the mappings defined in the
ibm-application-bnd.xmi file or the ibm-application-bnd.xml file, and the
application-bnd element of the server.xml file. The mappings from these two
sources are merged. If the same role is present in both sources, only the role
mapping in the server.xml file is used. The advantage of using the server.xml
file for mapping roles to users is that your application does not need to be
packaged into an EAR file and it is easier to update. Alternatively, using the
ibm-application-bnd.xmi/xml file makes your application portable to other
servers 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 the
authorization service returns immediately to allow anyone access. If the role is
mapped to the ALL_AUTHENTICATED_USERS special subject and the user is
authenticated, then the authorization service grants access to the user. If none
of these conditions are met, then the authorization service determines what
1
4
2 3
2 2
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>
Authorization
service
Figure 7. Overview of authorization process
users and groups are mapped to the required role. The authorization service
grants access to the resource if the user is mapped to the required role or if the
user is part of a group that is mapped to the role.
4. The authorization service returns a result back to the web container to indicate
whether the user is granted or denied access.
Special subjects
When you map entities to roles, you can map a special subject instead of a specific
user or group. A special subject is an extension to the concept of a subject. A
special 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 enter
credentials.
v ALL_AUTHENTICATED_USERS: represents any entity that has successfully
authenticated to the server.
To map a special subject to a user, update either the ibm-application-bnd.xmi/xml
file or the server.xml file. In this example, the role named AllAuthenticated is
mapped 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 page
472.
Access IDs and authorization
When authorizing a user or group, the server needs a way to uniquely identify
that user or group. The unique ID of the user and group serve this purpose and
are used to build the authorization configuration. These IDs are determined by the
user registry implementation: the unique user ID is the value of
getUniqueUserId(), 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 the
authorization configuration. These explicit access IDs are used instead of the values
returned by the user registry implementation. To specify an access ID in the
ibm-application-bnd.xml/xmi file or the server.xml file, use the access-id
attribute for the user or group element.
In this example, an access ID is specified for the user Bob and the group
developers:
<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 the
unique IDs and realm name within your code, which causes problems when you
want to modify your user registry.
Liberty profile: Security public APIs
Security public APIs in the Liberty profile provides a way of extending the security
infrastructure.
The Liberty profile contains public APIs that you can use to implement security
functions. The security public APIs in the Liberty profile are a subset of the full
profile security public APIs. The main classes are WSSecurityHelper, WSSubject,
and RegistryHelper. These classes contain a subset of the methods that are
available in the full profile versions. There is also a new class WebSecurityHelper.
The following sections describe those main classes. There are also other classes
such as UserRegistry, WSCredential, and other exception classes.
All the security public APIs supported by the Liberty profile are in the Java API
documentation. 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.
WSSecurityHelper
This class contains only the methods isServerSecurityEnabled() and
isGlobalSecurityEnabled(). They both return true if either of the
following 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 from
the full profile WSSecurityHelper class for compatibility.
Note:
v There are no cells in the Liberty profile, so there is no distinction in the
Liberty profile between global security and server security. Therefore
both methods return the same value.
v The method revokeSSOCookies(javax.servlet.http.HttpServletRequest
req,javax.servlet.http.HttpServletResponse res) is not supported in
the Liberty profile. Instead you can use the Servlet 3.0 logout function.
v The method getLTPACookieFromSSOToken() has been renamed to a new
public API class: WebSecurityHelper.
WSSubject
This class provides utility methods for querying and setting the security
thread context. All methods from the full profile WSSubject are supported
in the Liberty profile.
Note: Java 2 security is not enabled in the Liberty profile, so the Java 2
security checks in WSSubject are not performed.
RegistryHelper
This class provides access to the UserRegistry object and trusted realm
information. In the Liberty profile, it contains the following subset of the
full profile methods:
public static UserRegistry getUserRegistry(String realmName) throws
WSSecurityException
public static List<String> getInboundTrustedRealms(String realmName)
throws WSSecurityException
public static boolean isRealmInboundTrusted(String inboundRealm,
String localRealm)
WebSecurityHelper
This 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 the
Liberty profile to do a programmatic login and operate on the Subject.
v Example 1: Create a Subject and use it for authorization
v Example 2: Create a Subject and make it as the current Subject on the thread
v Example 3: Get information of the current Subject on the thread
Example 1: Create a Subject and use it for authorization
This example demonstrates how to use WSSecurityHelper, WSSubject, and
UserRegistry to do a programmatic login to create a Java Subject, then
perform an action and use that Subject for any authorization that is
required.
Note: The following code uses WSSecurityHelper to check if security is
enabled before doing further security processing. This check is used
extensively because of the modular nature of the Liberty profile: If security
is not enabled then the security run time is not loaded. WSSecurityHelper
is 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 info
return;
}
String userid = "user1";
String password = "user1password";
try {
if (ur.isValidUser(userid)) {
// create a Subject, authenticating with
// a userid and password
CallbackHandler 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 authorization
WSSubject.doAs(subject, action);
}
} catch (CustomRegistryException e) {
return;
} catch (RemoteException e) {
return;
} catch (LoginException e) {
return;
}
}
...
private final PrivilegedAction action = new PrivilegedAction() {
@Override
public Object run() {
// do something useful here
return null;
}
};
}
Example 2: Create a Subject and make it the current Subject on the thread
The following example demonstrates how to use WSSecurityHelper and
WSSubject to do a programmatic login to create a Java Subject, make that
Subject the current Subject on the thread, and finally restore the original
security thread context.
enabled before doing further security processing.
import javax.security.auth.login.LoginContext;
import com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl;
...
CallbackHandler wscbh = new WSCallbackHandlerImpl("user1", "user1password");
LoginContext ctx;
try {
// create a Subject, authenticating with
// a userid and password
ctx = new LoginContext("WSLogin", wscbh);
ctx.login();
Subject mySubject = ctx.getSubject();
Subject oldSubject = null;
try {
// Save a ref to the current Subject on the thread
oldSubject = WSSubject.getRunAsSubject();
// Make mySubject the current Subject on the thread
WSSubject.setRunAsSubject(mySubject);
// Do something useful here. Any authorization
// required will be performed using mySubject
} catch (WSSecurityException e) {
return;
} finally {
// Put the original Subject back on the thread context
if (oldSubject != null) {
try {
WSSubject.setRunAsSubject(oldSubject);
}
}
}
} catch (LoginException e) {
return;
}
}
Example 3: Get information of the current Subject on the thread
The following example demonstrates how to use WSSecurityHelper,
WSSubject, and WSCredential to get information about the current Subject
on the thread.
enabled before doing further security processing.
import java.util.ArrayList;
import java.util.Iterator;
import java.util.Set;
import javax.security.auth.login.CredentialExpiredException;
import com.ibm.websphere.security.auth.CredentialDestroyedException;
import com.ibm.websphere.security.cred.WSCredential;
...
// Get the callers subject
Subject callerSubject;
try {
callerSubject = WSSubject.getCallerSubject();
return;
}
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 groups
ArrayList<String> groups = wsCred.getGroupIds();
for (String group : groups) {
System.out.println("Group name: " + group);
}
} catch (CredentialExpiredException e) {
return;
} catch (CredentialDestroyedException e) {
return;
}
}
}
}
Configuration differences between the full profile and Liberty
profile: security
The configuration differences in the security capability between the Liberty profile
and full profile indicates the items that you might need to know during
applications migration.
The Liberty profile security supports only a subset of security features in the full
profile. Unless the support is explicitly mentioned in the Liberty profile
documentation, 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.
In the Liberty profile, you can configure user-to-role mappings and RunAs users in
the application-bnd element of the server.xml file. For a Run-As entry, the
password is optional. In the full profile, you can only configure the Run-AS entry
in the ibm-application-bnd.xml/xmi file. For a Run-As entry, the password is
required. See Configuring authorization for applications on the Liberty profile on
page 472.
Liberty profile: The limits to protection through password
encryption
The Liberty profile supports Advanced Encryption Standard (AES) encryption for
passwords that are stored in the server.xml file. When you use this option for
protecting system passwords in the Liberty profile configuration, you need to
understand the limits to the protection it provides.
Encrypting a password in the Liberty profile configuration does not guarantee that
the password is secure or protected; it only means that someone who can see the
encrypted password, but does not know the encryption key, cannot easily recover
the password. The application server process requires access to both the encrypted
password and the decryption key, so both these data items need to be stored on
the file system that is accessible to the server runtime environment. The encryption
key is also required by anyone who encrypts a password that is placed in the
server configuration. For an attacker that has access to exactly the same set of files
as the Liberty profile server instance, applying AES encryption to the password
therefore provides no additional security over and above exclusive or (XOR)
encoding.
Nonetheless, there are still reasons why you might consider encrypting passwords
in the Liberty profile configuration. The Liberty profile configuration is designed to
be highly composable and sharable. The administration subsystem of the full
profile (the administrative console and wsadmin scripting) prevents an
administrator from gaining access to an XOR-encoded password. The Liberty
profile is designed to be configured without an administration subsystem, and so
any XOR-encoded password is visible to any administrator. Given these design
features, 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 the
passwords are encrypted and the encoding key is then protected as security
sensitive.
The encryption key used for decrypting can be overridden from the default by
setting the wlp.password.encryption.key property. This property should not be set
in the server.xml file that stores the password, but in a separate configuration file
that is included by the server.xml file. This separate configuration file should
contain only a single property declaration, and should be stored outside the
normal configuration directory for the server. This ensures that the file containing
the key is not included when you are running the server dump or package
command. The encryption key property can also be specified as a bootstrap
property. If you choose this option, you should put the encryption key in a
separate properties file that is included in the server bootstrap.properties file.
For information about using XOR or AES to protect your passwords see the related
links, especially Liberty profile: securityUtility command on page 456.
Liberty profile: Messaging
Liberty messaging is a composable, flexible, and dynamic JMS messaging engine
that runs in the Liberty profile. Liberty messaging is JMS 1.1 compliant and
supports both the point-to-point and publish/subscribe messaging models.
Liberty messaging runs only in the Liberty run time, and you can use the Liberty
feature manager to enable or disable the messaging features as required. Because
the messaging run time is highly composable, you can enable the basic messaging
features for the run time, and dynamically enable additional messaging features,
such as security, transactions, and remote communication, based on the
requirement.
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, which
means that at any given time there can be only one messaging engine that is
running in a Liberty kernel.
Liberty messaging architecture
Liberty messaging is highly composable and dynamic in nature. Liberty messaging
consists of several other internal messaging subcomponents, implemented as OSGi
bundles, that can be enabled or disabled based on the user requirements. OSGi
services are used to manage component lifecycles and the injection of
dependencies and configurations.
The messaging run time and the other messaging subcomponents run as OSGi
bundles in an OSGi framework. This enables the Liberty kernel to load or unload
the messaging bundles based on the usage. For example, if the user does not use
messaging security then the bundles that are related to messaging security are not
initialized.
Application deployment
Liberty messaging supports three types of JMS application connectivity. The
application 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 Messaging
Runtime Service
Persistence Store
Service
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 for
applications. When the JMS application is deployed in the same JVM where the
messaging engine is running, the application can communicate with the in-process
messaging engine, without going over the TCP/IP layer. This provides significant
performance benefits for the applications to send and receive messages.
JMS applications that are running on the Liberty profile that is not hosting the
messaging engine must connect over TCP/IP in order to communicate with the
messaging engine.
Message handling
Destinations (queues or topics) are always localized to the messaging engine where
the destinations are defined. If the application needs to send or receive a message
from a destination, it must always connect to the messaging engine that localizes
the destination.
Liberty server J2SE client
Liberty Server
Messaging
Engine
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 is
provided as a part of the product.
Overview
Note: The basic log and trace facility is enabled by default. To use HPEL you must
enable it.
HPEL provides a convenient mechanism for storing and
accessing log, trace, System.err, and System.out information produced by the
application server or your applications. It is an alternative to the basic log and
trace facility, which provides the JVM logs and diagnostic trace files commonly
named 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. See
the following figure to understand how applications and the application server
store log and trace information.
Liberty Server Liberty Server
Messaging Engine
JMS Application JMS consumer
J2SE Client
JMS consumer
Queue/Topic
JMS Application
Figure 10. Message handling in Liberty messaging
Log data
repository
Trace data
repository
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 is
typically intended to be reviewed by administrators. This includes any
information 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 or
higher (including Detail, Config, Info, Audit, Warning, Severe, Fatal, and
any custom levels at level Detail or higher).
HPEL trace data repository
The trace data repository is a storage facility for trace records. Trace data is
typically intended for use by application programmers or by the
WebSphere Application Server support team. This includes any information
applications or the server write to the OSGi logging service at level
LOG_DEBUG or java.util.logging at levels below level Detail (including
Fine, 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 log
file is provided for convenience, primarily so that log content can be read
without having to run the LogViewer command-line tool to convert the log
data repository content to plain text.
The text log file does not contain any content that is not also stored in
either the log data repository or trace data repository. You can disable the
text log to enhance server performance. The text log can be configured to
record trace content for debugging convenience.
Note: Writing trace to the text log is expensive from a performance
perspective.
Log and trace performance
HPEL has been designed and tested to significantly
outperform the existing basic log and trace facility. One result is that the
application server can run with trace enabled while causing less impact to
performance than tracing the same components using basic logging. Another result
is that applications that frequently write to the logs can run faster when using
HPEL. A number of factors contribute to the overall performance of HPEL logging
and tracing.
Log and trace events are each stored in only one place
Log events, System.out, and System.err are stored in the log data
repository. Trace events are stored in the trace data repository. If the text
log file is disabled, HPEL will only write log and trace content to these
repositories. Storing each type of event in one place ensures that
performance is not wasted on redundant data storage.
Log events, and optionally trace events, are written to the text log file
when it is enabled. Since this data is always also stored in the log data and
trace data repositories, the text log file content is redundant. The text log is
convenient for users who do not want to run the LogViewer command-line
tool to see their logs and trace; but you can disable the text log if this
convenience is not needed.
Data is not formatted unless it is needed
Formatting data for a user to read uses processor time. Rather than format
log event and trace event data at run time, HPEL log and trace data is
stored more rapidly in a proprietary binary representation. This improves
the performance of the log and trace facility. By deferring log and trace
formatting until the LogViewer is run, sections of the log or trace that are
never viewed are never formatted.
You can enable the text log file, which stores the log data and trace data in
an already readable text format.
Note: Disable the text log when performance of your server is a key
concern, 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 the
same amount of data in small blocks. HPEL provides the capability to
buffer log and trace data before writing it to disk. By default, log and trace
data is stored in an 8 KB buffer before being written to disk. If the buffer is
filled within 10 seconds, the buffer is written to disk. If the buffer is not
filled within that time it is automatically written to disk to ensure that the
logs 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 or
trace, or how long to retain log and trace records, and leave the management of
log 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-use
command (LogViewer), avoiding any possible confusion over which file to access
for certain content.
Reading from the log data and trace data repositories
The log data and trace data repositories are stored in a WebSphere
Application Server proprietary format and cannot be read using text file
editors such as Notepad or VI. You can copy the log data and trace data
repositories 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 for
HPEL users to work with the log data and trace data repositories. The
LogViewer provides filtering and formatting options that make finding
important content in the log data and trace data repositories easy. For
example, a user might filter any errors or warnings, then filter all log and
trace entries that occurred within 10 seconds of a key error message on the
same thread.
Filtering using log and trace record extension content
HPEL provides the capability for developers to add custom extensions to
log and trace records using a log record context API
(com.ibm.websphere.logging.hpel.LogRecordContext). You can use the
LogViewer command-line tool to filter records based on the content of log
and trace record extensions.
Development resources
HPEL has been designed to make working with log and trace content more flexible
and effective than the basic logging facility. Log and trace content can be easily
filtered 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 create
powerful log handling programs using the HPEL API.
Reading the log data and trace data
Developers can use the com.ibm.websphere.logging.hpel API to read the
log data and trace data repositories
HPEL API
An API has been provided to make it easy for developers to develop tools
to consume content from the HPEL log and trace repositories. For example,
a developer might write a Java program to search the log and trace content
to find any messages with message IDs that match a known list of
important message IDs. This API is in the com.ibm.websphere.logging.hpel
package. Refer to the API documentation for details on the HPEL log
reading API.
Log and trace record extensibility
As with other log and trace record fields, developers can access the record
extensions using the HPEL API. This is useful when writing tools to read
from log and trace repositories. Developers can also make use of the log
record context API to access extensions in custom log handlers, filters, and
formatters at run time.
LogViewer command-line tool
Use the LogViewer command to query the contents of the High Performance
Extensible Logging (HPEL) log and trace repositories. You can also use the
LogViewer command to view new log and trace repository entries as the server
writes content to them.
LogViewer
The High Performance Extensible Logging (HPEL) facility writes to the log and
trace repositories in a binary format. You can view, query and filter the repository
using the LogViewer command. The LogViewer command provides options for
quickly converting HPEL logs into a text file in various formats, including basic,
advanced, and Common Base Event format. The command also provides options
to make getting the data you need from the logs easier; for example, allowing you
to 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 trace
repositories:
v
Windows
(Windows) logViewer.bat
Optional parameters
[Liberty profile] servername
Specifies the name of the server whose log and trace data repositories you
want the logViewer command to use. This parameter is not needed in cases
where there is only one Liberty profile server created nor in cases where you
specify the path to the log and trace data repository root using the
-repositoryDir parameter.
-repositoryDir directory_name
Specifies the path to the repository directory. In the case where you want to
query both the log and trace data together, provide the path to the parent
directory, which contains both the log data and tracedata directories. If you use
the default repository location, profile_root/logs/application_server/, and run
this tool from the profile bin directory, then this argument is optional. The tool
checks the default location if one is not provided. If multiple application
servers exist in this profile with HPEL repositories, you are prompted to select
which server log and trace repository you want to view.
-outLog file_name
Specifies the file name you want the text output written to. If you do not
provide this information, the text output is displayed on the console.
-format basic | advanced | cbe-1.0.1
Specifies the output format. Supported formats include basic, advanced, and
the CBE-1.0.1 format. If you do not provide this information, the output is in
basic format.
-monitor [integer]
Specifies that you want the logViewer to continuously monitor the repository
and output new log record entries as they are created. You can provide an
optional integer argument after this parameter to specify how often you want
the LogViewer tool to query the repository for new records. By default the
logViewer queries the repository for new records every 5 seconds. When used
with other filtering options, only those new records that match the filter
criteria are displayed.
-help
Use this parameter to have the LogViewer tool list the full set of options that
are available.
-startDate date_time
You can filter the results that are displayed from the repository by date and
time. Use the startDate parameter to filter out log entries that occurred after
the date or date time provided as an argument. Provide either a date or date
and time, entered in the MM/dd/yy format or the MM/dd/yy H:m:s:S:z
format, where z represents timezone.
-stopDate date_time
Use this parameter to filter out log entries that occurred before the specified
date or date time. Provide the argument in the same format as the -startDate
option.
-level level_name
Specifies that you want the tool to only display those log events which match
the level name you provide as an argument. Valid values for the level name
are FINEST, FINER, FINE, DETAIL, CONFIG, INFO, AUDIT, WARNING,
SEVERE, FATAL.
-minLevel level_name
Specifies that you want the tool to only display records which are at or above
the specified level. Valid values for the level name are FINEST, FINER, FINE,
DETAIL, CONFIG, INFO, AUDIT, WARNING, SEVERE, FATAL.
-maxLevel level_name
Specifies that you want the tool to only display records that are at or below the
specified level. Valid values for the level name are FINEST, FINER, FINE,
-includeLoggers logger_name
When this option is used, only log events from the specified loggers are
included 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 parent
logger. When used in combination with the -excludedLoggers option, the more
specific match determines if the log event is included or excluded.
-excludeLoggers logger_name
Use this option to exclude log events from the specified loggers in the
LogViewer output. Separate multiple entries with a comma. The * symbol can
be used as a wildcard to include all loggers below a parent logger. When used
in combination with the -includeLoggers option, the more specific match
determines if the log event is included or excluded.
-thread thread_id
Use this option to restrict LogViewer output to only those log events from a
specific thread. Any log messages that were not created by the thread ID
provided as an argument to this option are not displayed. Specify the thread
ID in hex format.
-extractToNewRepository directory_name
This option redirects log and trace records from a binary repository to a new
binary 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 new
repository. This option uses the directory path where the new repository must
be written as an argument. Therefore, the directory must be empty. If the
directory does not exist, the directory is created. However, errors that occur
during the directory creation might create extraneous directories.
-listInstances
Use this option to list the IDs of available server process instances that are
available to use with the -instance option. After running LogViewer with the
-listInstances option, you can then use the -instance option to invoke
LogViewer with one of the server process instance IDs as an argument. Since
this option does not process any log or trace records, all other options are
ignored when you specify this option.
-instance instance_id
Use this option to retrieve the log and trace data for a given server process
instance 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 that
contains subprocesses, such as the z/OS
operating system.
If this option is combined with -latestInstance, -instance is ignored.
-latestInstance
Use this option to retrieve the log and trace data from the most recent server
instance. If this option is used with the -instance option, the -instance option is
ignored.
-message match_string
Use this option to retrieve only log or trace data with a message field that
matches the requested text.
-includeExtensions name[=value][,name[=value]]*
Use this option to retrieve the log and trace data with an extension name that
matches the requested name, and an extension value that matches the
requested value. You can also use this option to retrieve the log and trace data
with an extension name that matches the requested name, and an extension
value 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 as
extensions, and so cannot be filtered on with this option.
Separate multiple name=value arguments with a comma. Specify '==' (two
equals signs) in place of '=' (one equals sign) in cases where the name or value
must contain an equal sign. Specify ',,' (two commas) in place of ',' (one
comma) in cases where the name or value must contain a comma.
-encoding character_set
Specifies the character set that the LogViewer command will use for text
output.
Filtering considerations
Be aware of LogViewer filtering optimizations. The LogViewer tool is able to filter
log and trace data most efficiently when used with the following filter options:
v startDate
v stopDate
v thread
v level
v minLevel
v maxLevel
Example usage
See the following examples of LogViewer commands used with full profile servers
on UNIX-based systems. The examples show how to run LogViewer from the
profile 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 the
advanced 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 specific
repository 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 with
value 'WebContainer : 6'
logViewer.sh -includeExtensions thread="WebContainer : 6" -format advanced
v Write events from the default repository that were a part of the request with
requestID 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 servicing
the PlantsByWebSphere application.
logViewer.sh -includeExtensions appName=PlantsByWebSphere
MongoDB databases
MongoDB (from humongous) is a scalable, high-performance, open source
NoSQL database. The Liberty profile provides configuration support for MongoDB
Java driver Version 2.10.0 or later.
The Liberty profile provides a mongo-2.0 feature that you can use to configure
MongoDB instances and associated database connections for your applications.
Access to MongoDB connections is available either by Java Naming and Directory
Interface (JNDI) lookup or resource injection, as with other product resources. All
actual database manipulation is performed by the native com.mongodb API.
The MongoDB server and client MongoDB driver are not available with the
product. You must download, install, and configure the MongoDB database servers
and client drivers.
Chapter 3. End-to-end paths for the Liberty profile
Start here for step-by-step guidance in working with the WebSphere Application
Server Liberty profile. Identify the scenario that most closely matches your own
project 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 Java
Message Service (JMS) on a single server. To enable JMS messaging between two
servers, you also add the jmsComms feature. To make the jmsServer feature work in
a secure mode, you add the jmsSecurity feature. To also use SSL when passing
messages between two servers, you add the ssl feature.
Procedure
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 a single Liberty profile server
You can configure the wasJMSClient-1.1 and wasJMSServer-1.0 Liberty features in
the same server. In this scenario, the application is deployed on the same server
where the Messaging Engine and the JMS resources exist. You can also configure
the wasJMSSecurity-1.0 feature to make the wasJMSServer-1.0 feature work in a
secure mode.
Procedure
v 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 the
Messaging 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 the
Queue 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 the
Messaging 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 the
TopicSpace 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 a
secure 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 is
enabled.
About this task
The wasJMSSecurity-1.0 feature supports secure connections to the messaging
engine. When the wasJMSSecurity-1.0 feature is enabled, it starts authenticating
and authorizing the users who are trying to connect to the messaging engine. The
user 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 a
particular role, the user must have the access to that destination. The access to the
destination is defined in the <messagingSecurity> element in the server.xml file. If
the wasJMSSecurity-1.0 feature is added and the <messagingSecurity> element is
missing in the server.xml file, then the users can neither connect to the messaging
engine nor perform any messaging action (for example, sending or receiving
messages 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 users
to access messaging destinations.
Procedure
1. 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" />
<group name="Developers">
<member name="user2" />
</group>
<group name="Testers">
</group>
</basicRegistry>
2. Configure the MessagingSecurity tag to restrict users from accessing the
destinations.
By default, none of the users have any permission on any of the destinations
that are defined in the Messaging Engine. When you configure the
MessagingSecurity tag, you assign permission based on what the administrator
has defined. Regular expressions are supported for the MessagingSecurity
Permission 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" />
<group name="Developers" />
</role>
<role name="tester">
<permission name="QUEUE1" actions="BROWSE"/>
<permission name="TopicSpace1" actions="RECEIVE"/>
<group name="Testers" />
</role>
</messagingSecurity>
In the previous configuration, user1, user3 and Developers have SEND and
BROWSE permission on QUEUE1, and ALL permission on the destinations matching
the T.* regular expression. Similarly user5, user6 and the Testers group have
BROWSE permission on QUEUE1 and have RECEIVE permission on TopicSpace1.
The following example grants user1, user3 and Developers ALL permissions on
all the destinations:
<messagingSecurity>
<role name="DEFAULT">
<permission name=".*" actions="ALL"/>
</role>
3. Connect to the Messaging Engine using a authenticated user, and perform an
operation based on the authorization permissions which are declared by the
administrator.
4. Optional: While connecting to the Messaging Engine, specify UserName and
Password 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 acts
as client, and configure the wasJMSServer-1.0 feature on a different server. For
inter-server communication to work, you also have to add the JMSComms-1.0
feature on the server side. You can also configure the wasJMSSecurity-1.0 feature
to make the wasJMSServer-1.0 feature work in a secure mode, and configure the
ssl-1.0 feature to enable SSL communication between the two servers.
Procedure
v Configure the client side.
To enable the wasJMSClient-1.1 feature at the client side, configure the following
two properties in the ConnectionFactory:
connectionName="localhost:7276:BootstrapBasicMessaging"
This property specifies the server which needs to be contacted, where
the 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 is
running; <port> is the JMS inbound port which is configured at the
server side in a later step; <mode> is BootstrapBasicMessaging if SSL is
not being used, and BootStrapSecureMessaging if SSL is being used.
targetTransport="CLIENT"
This property specifies the behaviour of the Client when it tries to
connect to the messaging engine. There are three options:
BINDING
Specifies that the application should connect to a Messaging
Engine which exists locally. If it does not find a Messaging
Engine locally, the connection will fail.
CLIENT
Specifies that the application should connect to the Messaging
Engine which is declared in the ConnectionName property (a
remote Messaging Engine). If it cannot connect to the Messaging
Engine, the connection will fail.
BINDING_THEN_CLIENT
In this mode, the application first tries to connect to a Messaging
Engine which exists locally. If it does not find a Messaging
Engine locally, the application looks up the ConnectionName then
tries to connect to the remote Messaging Engine.
Note: If a value for targetTransport is not specified, then the
BINDING_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 enables
the 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 Client
applications can connect by using the jmsPort if SSL is not being used, and
by using the jmsSSLPort if SSL is being used. The port number is the one
that 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 a
secure 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 is
enabled.
About this task
The wasJMSSecurity-1.0 feature supports secure connections to the messaging
engine. When the wasJMSSecurity-1.0 feature is enabled, it starts authenticating
and authorizing the users who are trying to connect to the messaging engine. The
user 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 a
particular role, the user must have the access to that destination. The access to the
destination is defined in the <messagingSecurity> element in the server.xml file. If
the wasJMSSecurity-1.0 feature is added and the <messagingSecurity> element is
missing in the server.xml file, then the users can neither connect to the messaging
engine nor perform any messaging action (for example, sending or receiving
messages 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 users
to access messaging destinations.
Procedure
1. 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:
<group name="Developers">
</group>
<group name="Testers">
</group>
</basicRegistry>
2. Configure the MessagingSecurity tag to restrict users from accessing the
destinations.
By default, none of the users have any permission on any of the destinations
that are defined in the Messaging Engine. When you configure the
MessagingSecurity tag, you assign permission based on what the administrator
has defined. Regular expressions are supported for the MessagingSecurity
Permission tag. Here is a sample configuration:
<messagingSecurity>
<role name="developer">
<permission name="QUEUE1" actions="SEND,BROWSE"/>
<permission name="T.*" actions="ALL"/>
</role>
<role name="tester">
<permission name="QUEUE1" actions="BROWSE"/>
<permission name="TopicSpace1" actions="RECEIVE"/>
<group name="Testers" />
</role>
In the previous configuration, user1, user3 and Developers have SEND and
BROWSE permission on QUEUE1, and ALL permission on the destinations matching
the T.* regular expression. Similarly user5, user6 and the Testers group have
BROWSE permission on QUEUE1 and have RECEIVE permission on TopicSpace1.
The following example grants user1, user3 and Developers ALL permissions on
all the destinations:
<messagingSecurity>
<role name="DEFAULT">
<permission name=".*" actions="ALL"/>
</role>
3. Connect to the Messaging Engine using a authenticated user, and perform an
operation based on the authorization permissions which are declared by the
administrator.
4. Optional: While connecting to the Messaging Engine, specify UserName and
Password in the createConnection call.
Here is the syntax:
[createConnection(userName, password)]
Securing communications with the Liberty profile
You can configure the Liberty profile server to provide secure communications
between a client and the server.
About this task
To configure secure communications, you can either specify a minimal SSL
configuration or a detailed SSL configuration in the server.xml file. The minimal
configuration only requires the SSL feature and a keystore entry to be specified. In
the ${wlp.install.dir}/templates/config directory of the Liberty profile, there is
an sslConfig.xml file that contains several examples of SSL configurations.
The SSL configuration that is designated as the
default SSL configuration is used to create the process's default SSLContext using
the SSLContext.setDefault() method. The default SSL configuration can be the
minimal SSL configuration, or the configuration identified by the sslRef attribute
on the sslDefault element if multiple SSL configurations are defined. Because the
default SSLContext is set on the process, the javax.net.ssl.keyStore and
javax.net.ssl.trustStore properties will not be recognized.
Procedure
v Enable SSL communications between a client and a Liberty profile server
v Optional: Create a keystore from the command prompt
v Optional: Encode passwords from the command prompt
v 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 Liberty
profile.
Procedure
Migrate data access applications to the Liberty profile.
Migrating data access applications to the Liberty profile
For data access applications, you need to change configurations when you migrate
a data source from the WebSphere Application Server full profile to the Liberty
profile.
Procedure
v 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.
profile: dataSource and jdbcDriver elements
This page identifies some differences in configuration between dataSource in the
Liberty 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 is
MatchOriginalRequest.
The full profile allows connectionSharing to be configured in a finer grained
manner, where individual connection properties can be matched based on the
original connection request or the current state of the connection. In the full
profile, connectionSharing is a combination of bits representing which
connection 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 the
original 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 is
1, which means that the isolation level is matched based on the current state
of the connection and all other properties are matched based on the original
connection request.
v Time duration properties of data source
Time duration properties can optionally be specified with units in the Liberty
profile. 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 97
for accepted time units and formats of dataSource element. Omitting the units in
the 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 source
implementation classes. Alternatively, you can use a single jdbcDriver
element for both. Defining multiple jdbcDriver elements does not cause
different class loaders to be used. In the Liberty profile, jdbcDriver elements
always use the class loader of the shared library with which they are
configured.
In the full profile, a JDBC provider is defined to point to the JDBC driver
JARs, compressed files, and native files. You must define separate JDBC
providers for XA capable and non-XA capable data source implementation
classes.
For some of the commonly used JDBC drivers, the Liberty profile infers the data
source 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 override
these classes such as javax.sql.DataSource,
javax.sql.ConnectionPoolDataSource, and javax.sql.XADataSource.
The following example shows how to override the default
javax.sql.XADataSource and javax.sql.ConnectionPoolDataSource
implementations 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"/>
<fileset dir="C:/Drivers/derby" includes="derby.jar" />
</library>
for more information about the jdbcDriver element.
profile: connectionManager element
This page identifies some differences in configuration between connectionManager
in the Liberty profile and connection pools in the full profile.
v Properties with different names
maxConnectionsPerThread, which is maxNumberofMCsAllowableInThread in the
full 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 properties
You can optionally specify the time duration properties with units in the Liberty
profile. For example,
<connectionManager id="pool1" connectionTimeout="30s" reapTime="3m" maxIdleTime="30m"/>
for accepted time units and formats for the connectionManager element. If you
do not specify time units in the Liberty profile, the same default units are used
as in the full profile.
v Differences between immediate timeout values and never (disable) timeout
There 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 changes
In the Liberty profile , there are three purge policy values: EntirePool,
FailingConnectionOnly, and ValidateAllConnections.
In the full profile, there are two purge policy values: EntirePool and
FailingConnectionOnly, with a second property,
defaultPretestOptimizationOverride, determining the behavior of
FailingConnectionOnly.
Purge policies in the Liberty profile, and their full profile equivalents, are as
follows:
purgePolicy="EntirePool", which is the same for both.
purgePolicy="FailingConnectionOnly", which is equivalent to
purgePolicy="FailingConnectionOnly" with
defaultPretestOptimizationOverride="false" in the full profile.
purgePolicy="ValidateAllConnections", which is equivalent to
purgePolicy="FailingConnectionOnly" with
defaultPretestOptimizationOverride="true" in the full profile.
Migrating a DB2 data source to the Liberty profile
You 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 in
the 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"
<resourceProperties xmi:id="J2EEResourceProperty_1321914499002" name="serverName"
type="java.lang.String" value="localhost" required="false" ignore="false"
<resourceProperties xmi:id="J2EEResourceProperty_1321914499003" name="portNumber"
type="java.lang.Integer" value="50000" required="false" ignore="false"
<resourceProperties xmi:id="J2EEResourceProperty_1321914499010" name="currentLockTimeout"
<resourceProperties xmi:id="J2EEResourceProperty_1321914499013" name="currentSchema"
type="java.lang.String" value="DBUSER2" required="false" ignore="false"
<resourceProperties xmi:id="J2EEResourceProperty_1321914499015" name="cursorSensitivity"
<resourceProperties xmi:id="J2EEResourceProperty_1321914499016" name="deferPrepares"
type="java.lang.Boolean" value="true" required="false" ignore="false"
<resourceProperties xmi:id="J2EEResourceProperty_1321914499027" name="loginTimeout"
<resourceProperties xmi:id="J2EEResourceProperty_1321914499032"
name="resultSetHoldability" type="java.lang.Integer" value="1" required="false"
ignore="false" confidential="false" supportsDynamicUpdates="false"/>
name="retrieveMessagesFromServerOnGetMessage"
type="java.lang.Boolean" value="true" required="false" ignore="false"
<resourceProperties xmi:id="J2EEResourceProperty_1321914499041" name="traceLevel"
type="java.lang.Integer" value="-1" required="false" ignore="false"
name="beginTranForResultSetScrollingAPIs" type="java.lang.Boolean" value="false"
required="false" ignore="false" confidential="false" supportsDynamicUpdates="false"/>
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"
name="nonTransactionalDataSource" type="java.lang.Boolean" value="false"
name="syncQueryTimeoutWithTransactionTimeout" type="java.lang.Boolean" value="false"
name="webSphereDefaultIsolationLevel" type="java.lang.Integer" value="2"
name="webSphereDefaultQueryTimeout" type="java.lang.Integer" value="10"
</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.jar
db2jcc_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.jcc
databaseName="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 profile
You 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 data
source 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 Server
Developer Tools for Eclipse, or by extracting an archive file. If you install the
profile by using an archive file, you must apply service by using a fix pack archive
file.
About this task
To try out the Liberty profile, and use the Liberty profile to develop applications
that run on the WebSphere Application Server Liberty profile or full profile, you
can download the no-charge developer edition from the WASdev community
download page. This edition runs on distributed platforms including IBM i, and on
the Mac.
To use the Liberty profile in a production environment with guaranteed service
levels and IBM support, you must purchase WebSphere Application Server (base),
WebSphere Application Server Network Deployment or WebSphere Application
Server Express
. The Liberty profile is included with these editions, and can also
be downloaded separately, as an edition-specific archive file, from Passport
Advantage
online. The associated service is available from Fix Central.

For Windows, Linux, and Mac OS, you can also install the WebSphere Application
Server Developer Tools for Eclipse, then use the tools to install the profile.
Procedure
v
Installing the Liberty profile developer tools and
(optionally) the Liberty profile.
v
Installing the Liberty profile by extracting an archive
file on page 83.
Installing the Liberty profile developer tools and (optionally) the
Liberty profile
You can install WebSphere Application Server Developer Tools for Eclipse into an
existing Eclipse workbench. You can install the application-serving environment
separately, or you can use the tools to install the environment for you. You might
also want to install Maven Integration for Eclipse.
Before you begin
You can install the Liberty profile application-serving environment as described in
this topic, or as described in Installing the Liberty profile by extracting an archive
file on page 83.
To install the Liberty profile developer tools, you require the
following 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 Server
Developer 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 of
the Liberty profile for Windows, Linux, and Mac OS. If you have not yet installed
the 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.
Procedure
1. 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 of
the 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 repository
existing Eclipse workbench from a repository such as Eclipse Marketplace or
WASdev.
Before you begin
To install the Liberty profile developer tools, you require the following system
components:
See System requirements for WebSphere Application Server Developer Tools for
Eclipse on page 80.
About this task
You can install the WebSphere Application Server Developer Tools for Eclipse from
installation files located in a remote repository by either using your Eclipse
workbench to find the installation files, or by finding a link to the installation files
on a web page.
Procedure
1. 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 Selected
Features 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 Application
Server version Developer Tools.
d. Select and drag the Install icon to your Eclipse workbench, and drop it
on the Eclipse toolbar. The Confirm Selected Features page opens.
3. On the Confirm Selected Features page, expand the parent nodes and select the
features 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. The
installation process starts.
Note: During the installation, a Security Warning dialog box might open and
display 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.
Installing the developer tools from downloaded installation
files
existing Eclipse workbench from installation files that you downloaded to your
computer. To install the product while you are not connected to the Internet, you
must download additional prerequisite Eclipse files.
Before you begin
To install the Liberty profile developer tools, you require the following system
components:
See System requirements for WebSphere Application Server Developer Tools for
Eclipse on page 80.
Important: You must be connected to the Internet during the installation, before
you install WebSphere Application Server Developer Tools for Eclipse.
Procedure
1. 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 Server
Developer Tools for Eclipse V9.0 Beta and click Download.
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 (for
example, you are installing only the WebSphere Application Server V8.5
Liberty Profile Tools feature), then expand the IBM WebSphere Application
Server Developer Tools for Eclipse V9.0 Beta node and select the features
that you want to install.
You can install the following features:
Feature Description
Dojo Toolkit (optional) Provides Dojo Toolkit for building Web 2.0
applications.
OSGi Application Development Tools Provides tools for developing and
maintaining OSGi-based applications and
bundles.
Web Development Tools Develop web applications using the latest
web technologies such as HTML5, CSS3,
Dojo Toolkit, Servlet 3.0 and JSP 2.2.
Feature Description
Web Services Development Tools - Liberty Tools for developing and testing JAX-WS
Web services and clients for Liberty.
WebSphere Application Server V8.5 - Liberty
Profile
Tools for developing and administering
WebSphere Application Server V8.5 - Liberty
Profile.
WebSphere Application Server V8.5 Tools Tools for developing and administering
WebSphere 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 and
display 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.
What to do next
Configure the installation.
Configuring the developer tools installation
After you install the WebSphere Application Server Developer Tools for Eclipse,
you must complete the required configuration steps. There are also optional
configuration 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 74
v Installing the developer tools from downloaded installation files on page 76
Attention: These configuration steps require you to modify files. Create a backup
copy of the files before you modify them.
Procedure
v Complete the required configuration steps.
1. Stop the workbench.
2. Locate the eclipse.ini file in the <Eclipse installation
directory>\eclipse directory, where <Eclipse installation directory> is the
directory 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
If you are using an Oracle 32-bit JRE, then add the following text after
the -vmargs line:
-Xms100m
-Xmx960m
-XX:MaxPermSize=320m
If you are using an Oracle 64-bit JRE, then add the following text after
the -vmargs line:
-Xms100m
-Xmx1024m
-XX:MaxPermSize=512m
-Xmx1024m
-XX:+UseCompressedOops
6. Locate the line --launcher.XXMaxPermSize in the eclipse.ini file and modify
the value:
If you are using an Oracle 32-bit JRE, change the value to 320M:
--launcher.XXMaxPermSize
320M
If you are using an Oracle 64-bit JRE, change the value to 512M:
--launcher.XXMaxPermSize
512M
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 installation
directory> 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 the
eclipse.ini file in a text editor. <Eclipse installation directory> is the
directory where you installed Eclipse.
b. Delete the following lines:
-showsplash
org.eclipse.platform
c. Delete the following lines, if they exist:
-product
org.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 can
use the tools to download and install it for you when you create a server for the
first time. See Creating a Liberty profile server by using developer tools on page
93.
You might also want to install Maven Integration for Eclipse.
Installing Maven Integration for Eclipse
You can install tools for developing Apache Maven projects in the workbench.
Procedure
To install the Maven tools support:
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.
System requirements for WebSphere Application Server
Developer 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 an
Eclipse 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)
Runtime environment for Java (JRE) requirements
The required JRE depends on the features that you are installing:
If you are installing any of the WebSphere
Application Server Tools features for
versions 8.5, 8.0 or 7.0
If you are NOT installing any of the
WebSphere Application Server Tools
features for versions 8.5, 8.0 or 7.0
v IBM Runtime Environment for Windows,
Java Technology Edition, Version 6.0 SR9
FP1 or later.
v IBM Runtime Environment for Linux, Java
Technology Edition, Version 6.0 SR9 FP1
or later.
v IBM Runtime Environment for Windows,
Java Technology Edition, Version 7.0 GA
or later.
v IBM Runtime Environment for Linux, Java
Technology Edition, Version 7.0 GA or
later.
Tip: The IBM Runtime Environment for
Windows or Linux, Java Technology Edition
Version 6.0 is included with WebSphere
Application Server version 8.5, 8.0 and
version 7.0. It is located in the following
directory <WebSphere Application Server
installation directory>/java/jre
Tip: The IBM Runtime Environment for
Windows or Linux, Java Technology Edition
Version 7.0 is optionally installed with
WebSphere Application Server version 8.5. If
installed, it is located in the following
directory:<WebSphere Application Server
installation directory>/java_1.7_32/jre
Any Java 6+ or Java 7+ runtime
environment
The following versions work well:
v IBM Runtime Environment for Windows
or Linux, Java Technology Edition, Version
7.0 GA OR later.
v IBM Runtime Environment for Windows
or Linux, Java Technology Edition, Version
6.0 SR9 FP1 or later.
v Oracle Java Platform Standard Edition
Runtime Environment Version 7.0 latest
Update available.
v Oracle Java Platform Standard Edition
Runtime Environment Version 6.0 latest
Update available.
Tip: IBM Developer Kits and Runtime
Environments 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 connected
to the Internet during the installation, then you must download and install
prerequisite Eclipse files before you install WebSphere Application Server
Developer 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.1
v Graphical Editing Framework (GEF) 3.8.1
v Eclipse Data Tools Platform (DTP) 1.10.1
v EMF Transaction 1.6.0
v EMF Validation 1.6.0
v Graphiti
v Graphical Modeling Framework (GMF) 1.6.1
v Web Tools Platform (WTP) 3.4.1
3. For each compressed file that you downloaded in the previous step, extract the
contents of the file into the eclipse directory of your Eclipse 3.8.1 IDE. Ensure
that 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 path
C:\eclipse-SDK-3.8.1-win32\ , then you must extract the contents of each file
into the directory C:\eclipse-SDK-3.8.1-win32\.
When you are finished, the extracted files will be in the existing directories of
your 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, you
can install the Liberty profile and you are ready to create a server. For the
no-charge developer edition, you can download the archive file from the WASdev
community. For all other editions, you can use the archive file that is included with
each edition of WebSphere Application Server, or you can download an
edition-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 this
topic. For distributed platforms, you can also use the WebSphere Application
Server Developer Tools for Eclipse to install the profile as described in Installing
the Liberty profile developer tools and (optionally) the Liberty profile on page 73.
This topic assumes that your system meets the operating system and Java
requirements for using the Liberty profile. See System Requirements for WebSphere
Application Server v8.5 - Liberty.
Procedure
1. Get a copy of the distribution image:
v For the no-charge developer edition (with no IBM support), you can
download the archive file from the WASdev community download page.
v For all other editions, you can use the archive file that is included with each
edition 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 Advantage
online.
2. Extract the distribution image to your preferred directory.
This image is packaged as an archive file called wlp-edition-version.jar. For
example:
v To extract the distribution image by using the wizard, run java -jar
wlp-edition-version.jar
v To extract the distribution image by accepting the license terms and
conditions 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 or
JRE location using the JAVA_HOME property in the server.env file, as described
in Customizing the Liberty profile environment on page 352. On Linux or
UNIX systems, you can instead set JAVA_HOME in the user .bashrc file, or
append the JDK or JRE path to the PATH environment variable. On Windows
systems, you can instead set JAVA_HOME as a system environment variable, or
append the JDK or JRE path to the PATH system variable.
For example, on Windows systems you can use the
following commands to set the JAVA_HOME property, and to add the Java /bin
directory to the path:
set JAVA_HOME=C:\Progra~1\Java\JDK16
set PATH=%JAVA_HOME%\bin;%PATH%
Notes:
v The Liberty profile runtime environment searches for the java command in
this order: JAVA_HOME property, JRE_HOME property, and system PATH property.
v For more information about supported Java environments, and where to get
them, 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 an
alternative to using IBM Installation Manager. If you installed the Liberty profile
by using the self-extracting archive, and want to upgrade to the latest fix pack
version, you can apply a new fix pack archive to a new location, and migrate any
required user files and server configuration data.
About this task
If you used IBM Installation Manager to install the Liberty profile, you must use
Installation Manager to apply a fix pack.
Important: You must apply a new fix pack archive to a new location. If you install
a fix pack to a previous installation location, you cannot back out the fix pack from
the previous installation location.
Procedure
1. Install the new runtime environment.
a. Optional: If you are overwriting your current installation, stop all servers
that are running on the system. This minimizes the risk of incompatible
behaviors 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 all
servers.
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, to
install 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 archive
file 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 is
installed. If the same location is used, you cannot uninstall the fix pack and
return to your previous version.
2. Migrate any user data and server configurations. The Liberty profile defines
two 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 the
new runtime environment will continue to use the same location. This results
in no backup of server configuration data. To ensure that your server
configuration is backed up, copy the directory referenced by WLP_USER_DIR to a
new location on your file system. To protect the original environment, change
the 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 server
configuration.
If WLP_USER_DIR has not been set, the server configuration and shared resources
are stored in the usr directory at the root of the server's runtime environment
(for example, <liberty_8501>/usr). During uninstallation of the runtime
environment, you can reset the WLP_USER_DIR environment variable.
If the WLP_OUTPUT_DIR environment variable is set on your system, the new
server 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 the
WLP_OUTPUT_DIR environment variable. During uninstallation, reset this value to
its original value.
If the WLP_OUTPUT_DIR value is not set, the default location is in the server root
directory (for example <liberty_8501>/usr/servers/<serverName>). If the new
runtime environment is installed to a new location, no updates are required
during installation or uninstallation because logs continue to appear under the
usr/servers/<serverName>/logs directory of each respective installation.
Note: If the server.xml file, or any included XML configuration file, references
another resource outside the server configuration directory, these resources
must also be copied across, or the references will need to be updated. This also
applies to any resources that the application references directly, such as
references to hardcoded paths on file systems. During uninstallation of the fix
pack, 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 with
the --clean parameter as a launch option. For example, server start
--clean. You have to use the --clean option only once; all subsequent server
starts 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 installation
If you installed the Liberty profile by using the self-extracting archive, you can
uninstall a fix pack from the Liberty profile runtime environment in a given
location by migrating any user data and server configurations to the previous
Liberty profile runtime environment in a different location, and deleting the fix
pack runtime environment.
Procedure
1. 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 the
Migrate 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 an
alternative to using IBM Installation Manager. If you installed the Liberty profile
using the self-extracting archive, and want to install an interim fix, you can apply
an executable JAR file.
About this task
If you used IBM Installation Manager to install the Liberty profile, you must use
Installation Manager to apply an interim fix.
An interim fix is named <Liberty profile level>-WS-WASProd_WLPArchive-<fix
type><fix id>.jar
v <Liberty profile level> refers to a 4-digit fix pack level identifier, which indicates
the 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, and
TF for a diagnostic fix
v <fix id> refers the APAR reference number. If a diagnostic fix is provided before
an 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 the
content into the Liberty profile base folder (/wlp).
Note: When the interim fix is applied, no backup data is created. If you want to
back out an interim fix, you must manually remove or restore files from the /wlp
folder.
Each interim fix is provided with a readme.txt file, which contains backup and
restore instructions specific to the fix content, in a section titled Directions to
apply 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 --clean
parameter as a launch option.
Procedure
1. 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 to
your 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 interim
fix. The following launch options are available for the JAR file:
--installLocation
The 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 in
the same directory as the JAR file, then you can use this option to
change where the JAR file will patch. [LibertyRootDir] can either be
relative to the location of the JAR file, or an absolute file path.
--suppressInfo
The only messages output from the JAR file will be error messages or
confirmation 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 only
once; all subsequent server starts will not require it.
Removing an interim fix from a Liberty profile archive install
If you installed the Liberty profile by using the self-extracting archive, then to
remove 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 use
Installation 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 and
restore 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 --clean
parameter as a launch option.
Procedure
1. 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 option
once. 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 to
a 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 and
remove Liberty features that specify the capabilities of your server.
Procedure
v Defining directory locations and properties.
v Verifying the integrity of Liberty profile
installation on page 91.
v
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 when
multiple Liberty profile servers are running on the same machine.
Liberty profile: Directory locations and properties
In the Liberty profile, many directories have properties associated with them.
These properties can be used to specify file locations when you configure the
server.
Table 10. Runtime environment default directory structure. Column 1 contains a file and
directory tree. If a directory has a property associated with it, this is given in column 2. A
description 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 example
restConnector.jar.
+- jython/ Jython-based scripts
+- dev/ APIs available at compile time
or run time
+- ibm-api/ Public APIs available for both
compile and run time by default
+- javadoc/ Java document archives
+- spec/ Public specification APIs
available for both compile and
run time by default
+- third-party/ Third-party APIs that are
available at compile time by
default and must be specified in
the configuration using the
apiTypeVisibility attribute of
the classloader element for
applications at run time.
Table 10. Runtime environment default directory structure (continued). Column 1 contains a
file and directory tree. If a directory has a property associated with it, this is given in column
2. A description of each file or directory is given in Column 3.
+- tools/ Ant plug-in for the Liberty
profile
+- etc/ User customized server variables
that apply to all servers
(optional)
+- server.env Default server script
environment variables (optional)
+- jvm.options Default jvm options (optional)
+- lafiles/ License information files
+- lib/ Platform runtime environment
+- templates/ Runtime customization
templates and examples
+- config/ Configuration examples for
security
+- server/ Server template when creating a
server
+- 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} to
reference server-specific
configuration (applications).
+-
bootstrap.properties
Server bootstrap properties
(optional)
+- jvm.options Server JVM options, which
replace the values in
wlp/etc/jvm.options (optional)
+- server.env Server script environment
variables, which are merged
with wlp/etc/server.env
(optional)
+- server.xml Server configuration overlays
(required)
+- apps/ Server configuration for
applications
+- dropins/ Server default application
dropins folder (optional)
+-
application_name
Application folder or archive
(optional)
Table 10. Runtime environment default directory structure (continued). Column 1 contains a
file and directory tree. If a directory has a property associated with it, this is given in column
2. A description of each file or directory is given in Column 3.
+- server_name server.output.dir Server output directory. Use
${server.output.dir} to
describe artifacts generated by
the server (log files and
workarea).
+- logs/ Server log files, including FFDC
logs (directory is present after
server is first run)
+- console.log Basic server status and
operations messages
+-
trace_timestamp.log
Time-stamped trace messages,
with the level of detail
determined by the current
tracing configuration
+- ffdc/ First Failure Data Capture
(FFDC) output directory
+-
ffdc_timestamp/
First Failure Data Capture
(FFDC) output that typically
includes selective memory
dumps of diagnostic data related
to the failure of a requested
operation
+- workarea/ Files created by the server as it
operates (directory is present
after server is first run)
You can use the properties associated with each directory, if any, to specify file
locations when you configure the server.
Tip: To ensure configuration portability, use the most specific property that is
appropriate, and do not rely on the relationship between resources. For example, in
some configurations the installation location, ${wlp.install.dir} might not be the
parent 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 Liberty
profile.
About this task
After you have installed the Liberty profile, you must make sure that the
installation is completed successfully and that all required features or iFixes are
installed. The productInfo command provides different options to complete the
following tasks:
v Compare the differences between APAR fixes and the current installation.
v Validate the MD5 checksum file for server installation and each feature.
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, comparing
different versions of the Liberty profile servers, and verifying the current product
versions.
Syntax
The command syntax is as follows:
productInfo action --[options]
where the possible values of the options vary depending on the value of theaction
parameter.
Parameters
The following action parameters and options values are available for the
productInfo command:
compare
Allows you to compare APAR fixes that are installed in the current
installation with a different version of Liberty profile.
--target="path to directory or archive file"
Specifies the target file with which to compare the current
installation. The value of --target can be either a directory or an
archive 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 of
APAR IDs to see if it contains them, and then lists any APARs that
are not included. This option is required if --target is not
specified.
--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.
--verbose
Display detailed error messages when an error occurs.
Note: At least one of --target or --apars must be supplied
featureInfo
Lists all the features that are installed on the current Liberty profile server.
validate
Validates the Liberty profile server against its checksum file.
--checksumfile="path to the checksum file"
Specifies the file that contains the checksum information of *.mf
and *.blst being installed. The default value is
lib/versions/productChecksums.cs. You can also validate the
integrity of an installed feature on the Liberty profile.
version
Prints the product information such as the product name, edition, version,
and iFix information.
--output=filename
--verbose
Display 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\wlp
productInfo compare --target=C:\wlp\newInstall.jar --output=C:\wlp\compareOutput.txt
productInfo compare --apars=com.ibm.ws.apar.PM39074,com.ibm.ws.apar.PM39075,com.ibm.ws.apar.PM39080
productInfo featureInfo --output=c:\wlp\featureListOutput.txt
productInfo validate --checksumfile=c:\wlp\libs\versions\checksums\appSecurity-2.0-mf.cs
productInfo 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 have
not yet installed the Liberty profile, the developer tools can install it for you the
first time you create a server.
Before you begin
Make sure you have installed the developer tools as described in Installing the
Liberty 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 a
Liberty profile server manually on page 95.
When you create a new server using the tools, you specify the installation of the
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.
If you want to use the tools to install a Liberty edition (other than the no-charge
developer edition) from an archive file, make sure you have downloaded the
archive file.
Procedure
1. 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 following
steps:
a. In the Installation folder section of the Liberty Profile Runtime
Environment page, browse for the directory where you installed the Liberty
profile 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 have
previously downloaded, complete the following steps:
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 the
Liberty profile, complete the following steps:
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 your
local file system, choose Local download. Otherwise, choose the WASdev
community download page.
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. In the Installation Folder page, specify the target installation folder, then
click Finish. The Liberty profile is downloaded and installed to your chosen
folder.
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 next
v 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 or
remove applications on the server, and many other tasks. You can perform these
tasks by using the server context menu (right-click on the server to open the
pop-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 manually
You can create a server from the command prompt.
Before you begin
You can create a server as described in this topic, or as
described in Creating a Liberty profile server by using developer tools on page
93.
Procedure
1. 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 specified
server 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 can
specify those ports by Specifying Liberty profile bootstrap properties other than
using 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 properties
Bootstrap properties initialize the runtime environment for a particular server.
Generally, they are attributes that affect the configuration and initialization of the
runtime core.
About this task
Bootstrap properties are set in a text file named bootstrap.properties. This file
should 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 the
server directory as described in Customizing the Liberty profile environment on
page 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 and
included files.
You can edit the bootstrap.properties file using a text
editor or the editor in the WebSphere Application Server Developer Tools for
Eclipse. See Editing the Liberty profile configuration by using developer tools on
page 344.
If you update the bootstrap.properties file, you must restart the server with the
--clean option for the changes to take effect.
Procedure
v Use predefined properties to configure trace and logging.
For example, change the name of your trace file by specifying the property
com.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 various
development environments that allow machine- or environment-specific
customization. For example:
1. Specify the properties default.http.port and default.https.port in the
bootstrap.properties file:
default.http.port = 9081
default.https.port = 9444
Note: If you do not specify the properties, the default HTTP port is 9080 and
HTTPS ports is 9443. To override the default HTTP endpoint definition, set
the id attribute of the httpEndpoint element to defaultHttpEndpoint in the
server 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 is
listening only on address 127.0.0.1/localhost. You can also use the host
property to specify a single IP address, and then the system listens only on
the 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. There
is no administrative console for the Liberty profile. Administrators and developers
use 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 operates
from a set of built-in configuration default settings, and you only need to specify
configuration that overrides those default settings. You do this by editing either the
server.xml file or another XML file that is included in server.xml at run time.
runtime environment that are loaded into a particular server. They are the primary
mechanism that makes the server composable. The list of features that you specify
in the server configuration provides a functional server.
When you first install and start the server, a feature manager and a default server
configuration 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 environment
that is designed to cover most common requirements, therefore you only need to
specify changes from the default configuration.
Procedure
v Liberty profile: Configuration elements in the server.xml file
v Administering the Liberty profile by using developer tools on page 344
v 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 file
The application server configuration is described in a series of elements in the
server.xml configuration file. Each element has one or more attributes or
sub-elements. This topic contains details of the possible elements, attributes, and
sub-elements that can be configured.
List of elements in the server.xml configuration file.
v activationSpec on page 101
v activedLdapFilterProperties on page 101
v administrator-role on page 102
v application on page 103
v application-bnd on page 104
v applicationMonitor on page 106
v authCache on page 107
v authData on page 108
v authenticated on page 109
v authentication on page 110
v automaticLibraries on page 110
v baseEntry on page 110
v basicRegistry on page 111
v binaryLog on page 112
v binaryTrace on page 114
v bundleRepository on page 116
v channelfw on page 116
v classloader on page 117
v client on page 119
v clientManager on page 120
v config on page 121
v connectionManager on page 123
v contextService on page 125
v customLdapFilterProperties on page 126
v databaseStore on page 127
v dataSource on page 128
v disk on page 132
v domino50LdapFilterProperties on page 134
v edirectoryLdapFilterProperties on page 135
v ejbContainer on page 135
v executor on page 136
v featureManager on page 138
v federatedRepository on page 139
v 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 145
v httpClassification on page 147
v httpDispatcher on page 148
v httpEncoding on page 149
v httpEndpoint on page 158
v httpOptions on page 160
v httpSession on page 162
v httpSessionDatabase on page 167
v idsLdapFilterProperties on page 172
v include on page 173
v iplanetLdapFilterProperties on page 174
v jaasLoginContextEntry on page 175
v jaasLoginModule on page 176
v 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 181
v jndiEntry on page 181
v jpa on page 182
v jspEngine on page 183
v keyStore on page 185
v ldapRegistry on page 186
v library on page 192
v localStore on page 194
v logging on page 195
v 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 207
v mimeTypes on page 208
v mongo on page 208
v mongoDB on page 212
v monitor on page 213
v nativeTransactionManager on page 213
v netscapeLdapFilterProperties on page 214
v oauthProvider on page 215
v oauthRoles on page 220
v permission on page 221
v pluginConfiguration on page 221
v properties on page 223
Chapter 7. Administering the Liberty profile 99
v properties.datadirect.sqlserver on page 223
v properties.db2.i.native on page 231
v properties.db2.i.toolbox on page 238
v properties.db2.jcc on page 250
v properties.derby.client on page 262
v properties.derby.embedded on page 265
v properties.informix on page 267
v 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 292
v properties.microsoft.sqlserver on page 294
v properties.oracle on page 298
v properties.sybase on page 300
v quickStartSecurity on page 302
v realm on page 302
v remoteAccess on page 305
v role on page 306
v safAuthorization on page 307
v safCredentials on page 308
v safRegistry on page 308
v safRoleMapper on page 309
v securewayLdapFilterProperties on page 309
v serverCommand on page 310
v ssl on page 311
v sslDefault on page 311
v sslOptions on page 312
v supportedEntityType on page 312
v syncToOSThread on page 313
v tcpOptions on page 313
v textLog on page 314
v transaction on page 316
v 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 323
v variable on page 324
v virtualHost on page 324
v webAppSecurity on page 325
v webContainer on page 329
v wimRegistry on page 336
v wlmClassification on page 337
v wsSecurityClient on page 337
v wsSecurityProvider on page 340
activationSpec
Defines a JMS Activation Specification configuration. PID is
com.ibm.ws.jca.activationSpec.
Attributes
id Description: The unique identifier that represents the activation spec.
Required: true
Data type: string
value
Description: Must be in the format of <ApplicationName/ModuleName/
ComponentName> for example id="JMSSample/JMSSample/
SampleMDB"
Required: true
Data type: string
activedLdapFilterProperties
Specifies the list of default Microsoft Active Directory LDAP filters. PID is
com.ibm.ws.security.registry.ldap.internal.filters.actived.
Attributes
userFilter
Description: An LDAP filter clause for searching the user registry for
users.
Default value: (&(sAMAccountName=%v)(objectcategory=user))
Required: true
Data type: string
groupFilter
groups.
Default value: (&(cn=%v)(objectcategory=group))
Required: true
Data type: string
userIdMap
Description: An LDAP filter that maps the name of a user to an LDAP
entry.
Default value: user:sAMAccountName
Required: true
Data type: string
groupIdMap
Description: An LDAP filter that maps the name of a group to an LDAP
entry.
Default value: *:cn
Required: true
Data type: string
groupMemberIdMap
Description: An LDAP filter that identifies user to group memberships.
Default value: memberof:member
Required: true
Data type: string
administrator-role
A collection of users and/or groups assigned the server administrator role. PID is
com.ibm.ws.management.security.role.administrator.
Sub-elements
user
Description: User assigned a role.
Required: false
Data type: string
group
Description: Group assigned a role.
Required: false
Data type: string
application
Defines the properties of an application. PID is com.ibm.ws.app.manager.
Attributes
location
Description: Location of an application expressed as an absolute path or
a path relative to the server-level apps directory.
Required: true
Data type: string
name
Description: Name of an application.
Required: false
Data type: string
type
Description: Type of application archive.
Default value: ${location:type}
Required: false
Data type: string
context-root
Description: Context root of an application.
Required: false
Data type: string
autoStart
Description: Indicates whether or not the server should start the
application automatically when the server starts.
Default value: true
Required: false
Data type: boolean
application-bnd
Binds general deployment information included in the application to specific
resources. PID is com.ibm.ws.javaee.dd.appbnd, and it is the child of complex type
application.
Attributes
version
Description: Version of the application bindings specification.
Required: false
Data type: string
Sub-elements
security-role
Required: false
Data type: A role that is mapped to users and groups in a domain user
registry.
name
Description: Name of a security role.
Required: true
Data type: string
user
Required: false
Data type: A user possessing a security role.
name
Description: Name of a user possessing a security role.
Required: true
Data type: string
access-id
Description: A user access ID in the general form
user:realmName/userUniqueId. A value will be generated if one
is not specified.
Required: false
Data type: string
group
Required: false
Data type: A group possessing a security role.
name
Description: Name of a group possessing a security role.
Required: true
Data type: string
access-id
Description: Group access ID
Required: false
Data type: string
special-subject
Required: false
Data type: Name of a special-subject possessing a security role.
type
Description: One of the following special subject types:
ALL_AUTHENTICATED_USERS, EVERYONE.
Range:
EVERYONE
ALL_AUTHENTICATED_USERS
All authenticated users
Required: true
Data type: string
run-as
Required: false
Data type: ID and password of a user required to access a bean from
another bean.
userid
Description: ID of a user required to access a bean from another
bean.
Required: true
Data type: string
password
Description: Password of a user required to access a bean from
another bean. The value can be stored in clear text or encoded
form. To encode the password, use the securityUtility tool with
the encode option.
Required: false
Data type: password (string)
applicationMonitor
Defines how the server responds to application additions, updates, and deletions.
PID is com.ibm.ws.app.manager.monitor.
Attributes
pollingRate
Description: Rate at which the server checks for application additions,
updates, and deletions. 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
multiple values in a single entry. For example, 1s500ms is equivalent to
1.5 seconds.
Default value: 500ms
Required: false
Data type: string
dropins
Description: Location of the application drop-in directory expressed as an
absolute path or a path relative to the server directory.
Default value: dropins
Required: false
Data type: string
dropinsEnabled
Description: Monitor the drop-in directory for application additions,
updates, and deletions.
Default value: true
Required: false
Data type: boolean
updateTrigger
Description: Application update method or trigger.
Default value: polled
Range:
polled Server will scan for application changes at the polling interval
and update any applications that have detectable changes.
mbean
Server will only update applications when prompted by an
MBean called by an external program such as an integrated
development environment or a management application.
disabled
Disables all update monitoring. Application changes will not be
applied while the server is running.
Required: false
Data type: string
authCache
Controls the operation of the authentication cache service. PID is
com.ibm.ws.security.authentication.cache.
Attributes
initialSize
Description: Initial number of entries supported by the authentication
cache.
Default value: 50
Required: false
Data type: int
maxSize
Description: Maximum number of entries supported by the
authentication cache.
Default value: 25000
Required: false
Data type: int
timeout
Description: Amount of time after which an entry in the cache will be
removed. 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 multiple values in a
single entry. For example, 1s500ms is equivalent to 1.5 seconds.
Default value: 600s
Required: false
Data type: string
allowBasicAuthLookup
Description: Allow lookup by user ID and hashed password.
Default value: true
Required: false
Data type: boolean
authData
Authentication data for connecting to an Enterprise Information System (EIS). PID
is com.ibm.ws.security.jca.internal.authdata.config.
Attributes
user
Description: Name of the user to use when connecting to the EIS.
Required: true
Data type: string
password
Description: Password of the user to use when connecting to the EIS. The
value can be stored in clear text or encoded form. It is recommended that
you encode the password. To do so, use the securityUtility tool with the
encode option.
Required: true
authenticated
Security role for authorization code and token requests. PID is
com.ibm.ws.security.oauth20.authenticated.role.
Sub-elements
user
Description: User who has the security role.
Required: false
Data type: string
group
Description: Group that has the security role.
Required: false
Data type: string
specialSubject
Description: specialsubject.desc
Range:
All authenticated users.
EVERYONE
All users for every request, even if the request was not
authenticated.
Required: false
Data type: string
authentication
Controls the built-in authentication service configuration. PID is
com.ibm.ws.security.authentication.
Attributes
cacheEnabled
Description: Enables the authentication cache.
Default value: true
Required: true
Data type: boolean
allowHashtableLoginWithIdOnly
Description: Allow an application to login with just an identity in the
hashtable properties. Use this option only when you have applications
that require this and have other means to validate the identity.
Default value: false
Required: false
Data type: boolean
automaticLibraries
Configure automatic libraries. PID is
com.ibm.ws.classloading.sharedlibrary.automatic.
Attributes
monitorEnabled
Description: Monitor the automatic library folder for new or deleted
libraries
Default value: true
Required: false
Data type: boolean
baseEntry
baseEntry.desc. PID is com.ibm.ws.wim.core.baseEntry.
Attributes
name
Description: The name of a base entry.
Required: true
Data type: string
baseDN
Description: Base distinguished name (DN) in the repository.
Required: false
Data type: string
basicRegistry
A simple XML-based user registry. PID is com.ibm.ws.security.registry.basic.config.
Attributes
realm
Description: The realm name represents the user registry.
Default value: BasicRegistry
Required: true
Data type: string
Sub-elements
user
Required: false
Data type: A user in a Basic User Registry.
name
Description: Name of a user in a Basic User Registry.
Required: true
Data type: string
password
Description: Password of a user in a Basic User Registry. The value
can be stored in clear text or encoded form. It is recommended that
you encode the password. To do so, use the securityUtility tool with
the encode option.
Required: true
group
Required: false
Data type: A group in a Basic User Registry.
name
Description: Name of a group in a Basic User Registry.
Required: true
Data type: string
member
Required: false
Data type: A member of a Basic User Registry group.
name
Description: 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) log
options. The HPEL log can be viewed using the logViewer command (in the profile
bin directory). PID is com.ibm.ws.logging.binaryLog, and it is the child of complex
type logging.
Attributes
dataDirectory
Description: Specifies the location on the local file system to store the log
records.
Inherits: com.ibm.hpel.log.dataDirectory
Default value:
Required: false
Data type: string
purgeMaxSize
Description: Specifies the maximum size for all log files.
Inherits: com.ibm.hpel.log.purgeMaxSize
Default value: 50
Required: false
Data type: int
purgeMinTime
Description: Specifies the duration after which a server can remove a log
record.
Inherits: com.ibm.hpel.log.purgeMinTime
Default value: -1
Required: false
Data type: int
fileSwitchTime
Description: Specifies whether, in addition to regular switching of the
current file, to also start the new file at the defined time of day.
Inherits: com.ibm.hpel.log.fileSwitchTime
Required: false
Data type: int
bufferingEnabled
Description: Specifies whether to allow a small delay in saving records to
the disk for improved performance.
Inherits: com.ibm.hpel.log.bufferingEnabled
Default value: true
Required: false
Data type: boolean
outOfSpaceAction
Description: Specifies the action to perform when the file system where
records are kept runs out of free space.
Inherits: com.ibm.hpel.log.outOfSpaceAction
Default value: StopLogging
Range:
StopServer
Stop Server
PurgeOld
Remove old records
StopLogging
Stop Logging
Required: false
Data type: string
binaryTrace
Use this page to configure High Performance Extensible Logging (HPEL) trace
options. The HPEL trace can be viewed using the logViewer command (in the
profile bin directory). PID is com.ibm.ws.logging.binaryTrace, and it is the child of
complex type logging.
Attributes
dataDirectory
Description: Specifies the directory to store binary trace files. This
location is also used for dumping records stored in the HPEL memory
buffer.
Inherits: com.ibm.hpel.trace.dataDirectory
Default value:
Required: false
Data type: string
memoryBufferSize
Description: Specifies the maximum size of in memory buffer in
megabytes (MB).
Inherits: com.ibm.hpel.trace.memoryBufferSize
Required: false
Data type: int
purgeMaxSize
Description: Specifies the maximum size for all trace files.
Inherits: com.ibm.hpel.trace.purgeMaxSize
Default value: 50
Required: false
Data type: int
purgeMinTime
record.
Inherits: com.ibm.hpel.trace.purgeMinTime
Default value: -1
Required: false
Data type: int
fileSwitchTime
Inherits: com.ibm.hpel.trace.fileSwitchTime
Required: false
Data type: int
bufferingEnabled
Inherits: com.ibm.hpel.trace.bufferingEnabled
Default value: true
Required: false
Data type: boolean
outOfSpaceAction
Inherits: com.ibm.hpel.trace.outOfSpaceAction
Range:
StopServer
Stop Server
PurgeOld
Remove old records
StopLogging
Stop Logging
Required: false
Data type: string
bundleRepository
EBA bundle repository service. PID is com.ibm.ws.eba.bundle.repository.
Attributes
filesetRef
Description: Space separated list of fileset references
Required: false
Data type: List of configuration IDs of type fileset (comma-separated
string).
Sub-elements
fileset
Description: Space separated list of fileset references
Required: false
Data type: Element of type fileset.
channelfw
Defines channel and chain management settings. PID is com.ibm.ws.channelfw.
Attributes
chainStartRetryInterval
Description: Time interval between start retries. 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 multiple values in a single entry. For example, 1s500ms is
equivalent to 1.5 seconds.
Default value: 5s
Required: false
Data type: string
chainStartRetryAttempts
Description: Number of retry attempts to make per chain.
Default value: 60
Required: false
Data type: int
chainQuiesceTimeout
Description: 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, specify
500 milliseconds as 500ms. You can include multiple values in a single
entry. For example, 1s500ms is equivalent to 1.5 seconds.
Default value: 30s
Required: false
Data type: string
warningWaitTime
Description: Amount of time to wait before notifying of a missing factory
configuration. 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 multiple
values in a single entry. For example, 1s500ms is equivalent to 1.5
seconds.
Default value: 10s
Required: false
Data type: string
classloader
Classloader Service. PID is com.ibm.ws.classloading.classloader, and it is the child
of complex type application.
Attributes
delegation
Description: Controls whether parent classloader is used before or after
this classloader.
Default value: parentFirst
Range:
parentFirst
Parent first
parentLast
Parent last
Required: false
Data type: string
privateLibraryRef
Description: List of library references. Library class instances are unique
to this classloader, independent of class instances from other classloaders.
Required: false
Data type: List of configuration IDs of type library (comma-separated
string).
commonLibraryRef
Description: List of library references. Library class instances are shared
with other classloaders.
Required: false
Data type: List of configuration IDs of type library (comma-separated
string).
apiTypeVisibility
Description: The types of API package this class loader will be able to
see, 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
privateLibrary
Description: List of library references. Library class instances are unique
to this classloader, independent of class instances from other classloaders.
Required: false
Data type: Element of type library.
commonLibrary
Description: List of library references. Library class instances are shared
with other classloaders.
Required: false
client
OAuth client definition. Only clients defined here can access the provider. PID is
com.ibm.ws.security.oauth20.client.
Attributes
name
Description: Name of the client (sometimes referred to as the Id).
Required: false
Data type: string
secret
Description: Secret key of the client.
Required: false
displayname
Description: Display name of the client.
Required: false
Data type: string
redirect
Description: URL to redirect the client's requests to.
Required: false
Data type: string
enabled
Description: Client is enabled if true, disabled if false.
Default value: true
Required: false
Data type: boolean
clientManager
Security role for client management requests. PID is
com.ibm.ws.security.oauth20.clientmanager.role.
Sub-elements
user
Description: User who has the security role.
Required: false
Data type: string
group
Description: Group that has the security role.
Required: false
Data type: string
specialSubject
Description: Special subject that has the security role.
Range:
All authenticated users.
EVERYONE
All users for every request, even if the request was not
authenticated.
Required: false
Data type: string
config
Defines how the server processes configuration information. PID is
com.ibm.ws.config.
Attributes
onError
Description: Action to take after incurring a configuration error.
Inherits: onError
Default value: WARN
Range:
WARN
Server will issue warning and error messages when it incurs a
configuration error.
FAIL Server will issue a warning or error message on the first error
occurrence and then stop the server.
IGNORE
Server will not issue any warning and error messages when it
incurs a configuration error.
Required: true
Data type: string
monitorInterval
Description: Rate at which the server checks for configuration updates.
Default value: 500ms
Required: false
Data type: string
updateTrigger
Description: Configuration update method or trigger.
Default value: polled
Range:
polled Server will scan for changes at the polling interval on all the
configuration files and update the runtime configuration with the
changes detected.
mbean
Server will only update the configuration when prompted by an
MBean called by an external program such as an integrated
development environment or a management application.
disabled
Disables all update monitoring. Configuration changes will not be
applied while the server is running.
Required: false
Data type: string
connectionManager
Connection Manager configuration. PID is com.ibm.ws.jca.connectionManager.
Attributes
agedTimeout
Description: Amount of time before a physical connection can be
discarded by pool maintenance. A value of -1 disables this timeout.
(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 90 seconds.
Default value: -1
Required: false
Data type: string
connectionTimeout
Description: Amount of time after which a connection request times out.
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 is equivalent to 90 seconds.
Default value: 30s
Required: false
Data type: string
maxIdleTime
Description: Amount of time after which an unused or idle connection
can be discarded during pool maintenance, if doing so does not reduce
the pool below the minimum size. A value of -1 disables this timeout.
Default value: 30m
Required: false
Data type: string
maxPoolSize
Description: Maximum number of physical connections for a pool. A
value of 0 means unlimited.
Default value: 50
Required: false
Data type: int
minPoolSize
Description: Minimum number of physical connections to maintain in the
pool. The pool is not pre-populated. Aged timeout can override the
minimum.
Required: false
Data type: int
purgePolicy
Description: Specifies which connections to destroy when a stale
connection is detected in a pool.
Default value: EntirePool
Range:
EntirePool
When a stale connection is detected, all connections in the pool
are marked stale, and when no longer in use, are closed.
FailingConnectionOnly
When a stale connection is detected, only the connection which
was found to be bad is closed.
ValidateAllConnections
When a stale connection is detected, connections are tested and
those found to be bad are closed.
Required: false
Data type: string
reapTime
Description: Amount of time between runs of the pool maintenance
thread. A value of -1 disables pool maintenance. 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 is equivalent to 90
seconds.
Default value: 3m
Required: false
Data type: string
maxConnectionsPerThread
Description: Limits the number of open connections on each thread.
Required: false
Data type: int
numConnectionsPerThreadLocal
Description: Caches the specified number of connections for each thread.
Required: false
Data type: int
contextService
Configures how context is propagated to threads. PID is
com.ibm.ws.context.service.
Attributes
onError
Description: Determines the action to take in response to configuration
errors. For example, if securityContext is configured for this
contextService, but the security feature is not enabled, then onError
determines whether to fail, raise a warning, or ignore the parts of the
configuration which are incorrect.
Inherits: onError
Default value: WARN
Range:
FAIL Fail when incorrect configuration is encountered.
IGNORE
Ignore incorrect configuration.
WARN
onError.WARN
Required: true
Data type: string
baseContextRef
Description: Specifies a base context service from which to inherit context
that is not already defined on this context service.
Required: false
Data type: Configuration ID of type contextService (string).
Sub-elements
baseContext
Description: Specifies a base context service from which to inherit context
that is not already defined on this context service.
Required: false
Data type: Element of type contextService.
customLdapFilterProperties
Specifies the list of default Custom LDAP filters. PID is
com.ibm.ws.security.registry.ldap.internal.filters.custom.
Attributes
userFilter
users.
Default value: (&(uid=%v)(objectclass=ePerson))
Required: true
Data type: string
groupFilter
groups.
Default value:
(&(cn=%v)(|(objectclass=groupOfNames)
(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))
Required: true
Data type: string
userIdMap
entry.
Default value: *:uid
Required: true
Data type: string
groupIdMap
entry.
Default value: *:cn
Required: true
Data type: string
groupMemberIdMap
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 is
com.ibm.ws.security.oauth20.database.store.
Attributes
dataSourceRef
Description: Reference to the data source for the store.
Required: false
Data type: Configuration ID of type dataSource (string).
cleanupExpiredTokenInterval
Description: Expired token cleanup interval (seconds). The equivalent
provider parameter in the full application server profile is
oauthjdbc.CleanupInterval. 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 is equivalent to 90 seconds.
Default value: 3600
Required: false
Data type: string
user
Description: Database store user
Required: false
Data type: string
password
Description: Password used to access the database.
Required: false
Sub-elements
dataSource
Description: Reference to the data source for the store.
Required: false
Data type: Element of type dataSource.
dataSource
Defines a data source configuration. PID is com.ibm.ws.jdbc.dataSource.
Attributes
jndiName
Description: JNDI name for a data source.
Required: true
Data type: string
jdbcDriverRef
Description: JDBC driver for a data source.
Required: false
Data type: Configuration ID of type jdbcDriver (string).
connectionManagerRef
Description: Connection manager for a data source.
Required: false
Data type: Configuration ID of type connectionManager (string).
type
Description: Type of data source.
Range:
javax.sql.XADataSource
javax.sql.ConnectionPoolDataSource
javax.sql.DataSource
Required: false
Data type: string
connectionSharing
Description: Specifies how connections are matched for sharing.
Default value: MatchOriginalRequest
Range:
MatchOriginalRequest
When sharing connections, match based on the original
connection request.
MatchCurrentState
When sharing connections, match based on the current state of
the connection.
Required: false
Data type: string
isolationLevel
Description: Default transaction isolation level.
Range:
TRANSACTION_READ_UNCOMMITTED
Dirty reads, non-repeatable reads and phantom reads can occur.
TRANSACTION_READ_COMMITTED
Dirty reads are prevented; non-repeatable reads and phantom
reads can occur.
TRANSACTION_REPEATABLE_READ
Dirty reads and non-repeatable reads are prevented; phantom
reads can occur.
TRANSACTION_SERIALIZABLE
Dirty reads, non-repeatable reads and phantom reads are
prevented.
TRANSACTION_SNAPSHOT
Snapshot isolation for Microsoft SQL Server JDBC Driver and
DataDirect Connect for JDBC driver.
Required: false
Data type: string
statementCacheSize
Description: Maximum number of cached statements per connection.
Default value: 10
Required: false
Data type: int
transactional
Description: Enable participation in transactions that are managed by the
application server.
Default value: true
Required: false
Data type: boolean
beginTranForResultSetScrollingAPIs
Description: Attempt transaction enlistment when result set scrolling
interfaces are used.
Default value: true
Required: false
Data type: boolean
beginTranForVendorAPIs
Description: Attempt transaction enlistment when vendor interfaces are
used.
Default value: true
Required: false
Data type: boolean
commitOrRollbackOnCleanup
Description: Determines how to clean up connections that might be in a
database unit of work (AutoCommit=false) when the connection is closed
or returned to the pool.
Range:
commit
Clean up the connection by committing.
rollback
Clean up the connection by rolling back.
Required: false
Data type: string
queryTimeout
Description: Default query timeout for SQL statements. In a JTA
transaction, syncQueryTimeoutWithTransactionTimeout can override this
default. 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 is equivalent to 90 seconds.
Required: false
Data type: string
recoveryAuthDataRef
Description: Authentication data for transaction recovery.
Required: false
Data type: Configuration ID of type authData (string).
syncQueryTimeoutWithTransactionTimeout
Description: Use the time remaining (if any) in a JTA transaction as the
default query timeout for SQL statements.
Required: false
Data type: boolean
supplementalJDBCTrace
Description: Supplements the JDBC driver trace that is logged when
JDBC driver trace is enabled in bootstrap.properties. JDBC driver trace
specifications 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
jdbcDriver
Description: JDBC driver for a data source.
Required: false
Data type: Element of type jdbcDriver.
connectionManager
Description: Connection manager for a data source.
Required: false
Data type: Element of type connectionManager.
recoveryAuthData
Description: 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 are
removed from the cache and saved to disk. The location is a fully-qualified
directory location that is used by the disk offload function. The Flush to Disk on
Stop option specifies that when the server stops, the contents of the memory cache
are moved to disk. PID is com.ibm.ws.cache.disk, and it is the child of complex
type null.
Attributes
sizeInEntries
Description: Specifies a value for the maximum disk cache size, in
number of entries.
Required: false
Data type: int
sizeInGB
Description: Specifies a value for the maximum disk cache size, in
gigabytes (GB).
Default value: 3
Required: false
Data type: int
evictionPolicy
Description: Specifies the eviction algorithm and thresholds that the disk
cache uses to evict entries.
Default value: RANDOM
Range:
RANDOM
SIZE
Required: false
Data type: string
highThreshold
Description: Specifies when the eviction policy starts.
Default value: 80
Required: false
Data type: int
lowThreshold
Description: Specifies when the eviction policy ends.
Default value: 70
Required: false
Data type: int
location
Description: Specifies a directory to use for disk offload.
Required: false
Data type: string
flushToDiskOnStopEnabled
Description: Set this value to true to have objects that are cached in
memory saved to disk when the server stops. This value is ignored if
Enable disk offload is set to false.
Required: false
Data type: boolean
domino50LdapFilterProperties
Specifies the list of default IBM Lotus
Domino
LDAP filters. PID is

com.ibm.ws.security.registry.ldap.internal.filters.domino50.
Attributes
userFilter
users.
Default value: (&(uid=%v)(objectclass=Person))
Required: true
Data type: string
groupFilter
groups.
Default value: (&(cn=%v)(objectclass=dominoGroup))
Required: true
Data type: string
userIdMap
entry.
Default value: person:uid
Required: true
Data type: string
groupIdMap
entry.
Default value: *:cn
Required: true
Data type: string
groupMemberIdMap
Default value: dominoGroup:member
Required: true
Data type: string
edirectoryLdapFilterProperties
Specifies the list of Novell eDirectory LDAP filters. PID is
com.ibm.ws.security.registry.ldap.internal.filters.eDirectory.
Attributes
userFilter
users.
Default value: (&(cn=%v)(objectclass=Person))
Required: true
Data type: string
groupFilter
groups.
Default value: (&(cn=%v)(objectclass=groupOfNames))
Required: true
Data type: string
userIdMap
entry.
Default value: person:cn
Required: true
Data type: string
groupIdMap
entry.
Default value: *:cn
Required: true
Data type: string
groupMemberIdMap
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
poolCleanupInterval
Description: The interval between removing unused bean instances. This
setting only applies to stateless session and message-driven beans. 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 is
Default value: 30s
Required: true
Data type: string
cacheSize
Description: The number of stateful session bean instances that should be
cached in memory.
Default value: 2053
Required: true
Data type: int
cacheCleanupInterval
Description: The interval between passivating unused stateful session
bean instances when the size is exceeded. Specify a positive integer
seconds.
Default value: 3s
Required: true
Data type: string
executor
Defines threading and execution settings for the server. PID is
com.ibm.ws.threading.
Attributes
name
Description: Name of the executor for which the thread is performing
work.
Default value: Default Executor
Required: false
Data type: string
maxThreads
Description: Maximum number of threads that can be associated with the
executor. If greater than 0, this value must be greater than or equal to the
value of coreThreads. If the value of maxThreads is less than or equal to
0, the maximum number of threads is unbounded.
Default value: -1
Required: false
Data type: int
coreThreads
Description: Steady-state or core number of threads to associate with the
executor. The number of threads associated with the executor will quickly
grow 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 threads
on the system.
Default value: -1
Required: false
Data type: int
keepAlive
Description: Amount of time to keep an idle thread in the pool before
allowing it to terminate. Specify a positive integer followed by a unit of
1.5 seconds.
Default value: 60s
Required: false
Data type: string
stealPolicy
Description: The work-stealing policy to employ. The options for this
policy determine how work is queued, and how threads obtain queued
work.
Default value: LOCAL
Range:
STRICT
All threads that generate work own a local work pile. Threads
that are associated with the executor take work from other
threads when the local work pile is exhausted.
LOCAL
A global work queue is used for work that is generated by
threads that are not associated with the executor. Work generated
by threads associated with the executor is placed on a local work
pile. This work pile is owned by the generating thread, unless
another thread steals it. Threads that are associated with the
executor take work associated with other threads if the local work
pile is empty and there is no work on the global work queue.
NEVER
A global work queue is used to feed work to threads that are
associated with the executor. No stealing will occur.
Required: false
Data type: string
rejectedWorkPolicy
Description: Policy to employ when the executor is unable to stage work
for execution.
Default value: ABORT
Range:
ABORT
Raise an exception.
CALLER_RUNS
Execute the work immediately on the caller's thread.
Required: false
Data type: string
featureManager
Defines how the server loads features. PID is com.ibm.ws.kernel.feature.
Attributes
onError
Description: Action to take after a failure to load a feature.
Inherits: onError
Default value: WARN
Range:
WARN
Server will issue warning and error messages when it incurs a
feature configuration error.
FAIL Server will issue a warning or error message on the first feature
configuration error occurrence and then stop the server.
IGNORE
Server will not issue any warning and error messages when it
incurs a feature configuration error.
Required: true
Data type: string
Sub-elements
feature
Required: false
Data type: string
federatedRepository
Configuration for the Federated Manager core services. PID is
com.ibm.ws.wim.core.config.
Attributes
maxSearchResults
Description: Maximum number of entries that can be returned in a
search.
Default value: 4500
Required: false
Data type: int
searchTimeOut
Description: The maximum amount of time, in milliseconds, to process a
search.
Required: false
Data type: int
supportedEntityTypeRef
Description: The configuration of the supported Entity Type.
Required: false
Data type: List of configuration IDs of type supportedEntityType
(comma-separated string).
realmRef
Description: The realm configuration.
Required: false
Data type: List of configuration IDs of type realm (comma-separated
string).
primaryRealmRef
Description: Primary realm configuration.
Required: false
Data type: Configuration ID of type realm (string).
Sub-elements
supportedEntityType
Description: The configuration of the supported Entity Type.
Required: false
Data type: Element of type supportedEntityType.
realm
Description: The realm configuration.
Required: false
Data type: Element of type realm.
primaryRealm
Description: Primary realm configuration.
Required: false
Data type: Element of type realm.
fileset
Fileset Service. PID is com.ibm.ws.kernel.metatype.helper.fileset.
Attributes
dir
Description: The base directory to search for files.
Default value: ${server.config.dir}
Required: true
Data type: string
caseSensitive
Description: Boolean to indicate whether or not the search should be case
sensitive (default: true).
Default value: true
Required: false
Data type: boolean
includes
Description: The comma or space separated list of file name patterns to
include in the search results (default: *).
Default value: *
Required: false
Data type: string
excludes
Description: The comma or space separated list of file name patterns to
exclude from the search results, by default no files are excluded.
Default value:
Required: false
Data type: string
scanInterval
Description: Scanning interval to check the fileset for changes as a long
with 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 integer
Default value: 0
Required: false
Data type: string
fileTransfer
Main file transfer configuration element. PID is
com.ibm.ws.management.filetransfer.
Sub-elements
readLocation
Description: 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
writeLocation
Description: 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 is
com.ibm.ws.messaging.security.group.
Attributes
name
Description: The name of the group.
Required: true
Data type: string
groupDisplayNameMapping
The property mapping for groupDisplayName (default: cn). PID is
com.ibm.ws.wim.groupDisplayNameMapping.
Attributes
propertyForInput
Description: The property that maps to the user registry attribute for
input. The valid values are: uniqueId, uniqueName, externalId,
externalName and the attributes of PersonAccount and Group entity
types.
Default value: cn
Required: true
Data type: string
propertyForOutput
output. The valid values are: uniqueId, uniqueName, externalId,
types.
Default value: cn
Required: true
Data type: string
groupSecurityNameMapping
The property mapping for groupSecurityName (default: cn). PID is
com.ibm.ws.wim.groupSecurityNameMapping.
Attributes
propertyForInput
types.
Default value: cn
Required: true
Data type: string
propertyForOutput
output. The valid values are: uniqueId, uniqueName, externalId,
types.
Default value: cn
Required: true
Data type: string
hostAuthInfo
Connection details to allow for Atlas to authenticate to the server's host. PID is
com.ibm.ws.management.repository.member.hostAuthInfo.
Attributes
hostName
Description: The fully qualified host name or IP address. A '*' wildcard
will result in host name detection; this is not recommended for
multi-homed systems and may result in unexpected behaviour. The host
name must be unique within the network and must be the host name on
which the remote connection protocol is listening (SSH, or OS specific
RPC). This value will inherit from the defaultHostName variable if not
set. The host name set here will directly control where the server's
information is stored within the Atlas repository.
Inherits: defaultHostName
Default value: localhost
Required: true
Data type: string
port
Description: The port on which the remote connection protocol is
listening (SSH, or OS specific RPC). See product documentation for
supported RPC mechanisms.
Default value: 22
Required: true
Data type: int
userId
Description: The operating system user ID to use to connect to the host.
Required: false
Data type: string
userPassword
Description: The password for the operating system user. If this property
is not set, key-based authentication will be used. Use of key-based
authentication is recommended for hosts which support SSH. If this
property is set and sshPrivateKeyPath is also set, the key will take
precedence.
Required: false
userHome
Description: The home directory of the user login ID. Only required to be
set if sudo is to be used and SSH generation is to be done automatically.
Required: false
Data type: string
sshPublicKeyPath
Description: The path to the SSH public key file. If the key pair does not
exist, a key pair will be generated automatically. The public key will be
placed into the configured userId's authorized_keys file if it is not
present. Setting the path to the public key is not required.
Required: false
Data type: string
sshPrivateKeyPath
Description: The path to the SSH private key file. If the key pair does not
exist, a key pair will be generated automatically. The private key is
required for key-based authentication.
Required: false
Data type: string
sshPrivateKeyPassword
Description: The password for the SSH private key.
Required: false
useSudo
Description: If this property is set to true, then sudo will be used to
invoke commands. The user to sudo as can be controlled by setting
sudoUser attribute. If sudoUser is not set, then the user to sudo as will be
the configured default sudo user for the host. If this property is not set,
and either sudoUser or sudoUserPassword are set, then useSudo is
assumed to be true. If this property is set to false, and either sudoUser or
sudoUserPassword are set, then a warning will be printed and the sudo
options will be ignored.
Required: false
Data type: boolean
sudoUser
Description: The sudo user ID. This property should not be set when
useSudo=false.
Required: false
Data type: string
sudoUserPassword
Description: The password for the sudo user. This property should not be
set when useSudo=false.
Required: false
httpClassification
An element representing a rule used by WLM for classifying incoming HTTP
requests. PID is com.ibm.ws.zos.wlm.httpclassification, and it is the child of
complex type wlmClassification.
Attributes
transactionClass
Description: Defines the priority
Default value:
Required: false
Data type: string
host
Description: Defines which host to map the transaction class to
Default value: *
Required: false
Data type: string
port
Description: Defines which port to map the transaction class to
Default value: *
Required: false
Data type: string
resource
Description: Defines the URI to use when mapping transaction class
Default value: *
Required: false
Data type: string
method
Description: Defines the HTTP method to map to
Default value: *
Required: false
Data type: string
httpDispatcher
HTTP Dispatcher configuration. PID is com.ibm.ws.http.dispatcher.
Attributes
appOrContextRootMissingMessage
Description: Message to return to the client when the application in the
requested URI can not be found.
Required: false
Data type: string
httpEncoding
Configuration properties for the HTTP Transport Encoding service. PID is
com.ibm.ws.transport.http.encoding.
Attributes
converter.Shift_JIS
Description: Converter for Shift_JIS
Default value: Cp943C
Required: false
Data type: string
converter.EUC-JP
Description: Converter for EUC-JP
Default value: Cp33722C
Required: false
Data type: string
converter.EUC-KR
Description: Converter for EUC-KR
Default value: Cp970
Required: false
Data type: string
converter.EUC_KR
Description: Converter for EUC_KR
Required: false
Data type: string
converter.EUC-TW
Description: Converter for EUC-TW
Required: false
Data type: string
converter.Big5
Description: Converter for Big5
Required: false
Data type: string
converter.GB2312
Description: Converter for GB2312
Default value: EUC_CN
Required: false
Data type: string
converter.ISO-2022-KR
Description: Converter for ISO-2022-KR
Default value: ISO2022KR
Required: false
Data type: string
encoding.en
Description: Encoding for 'en' locale
Default value: ISO-8859-1
Required: false
Data type: string
encoding.fr
Description: Encoding for 'fr' locale
Required: false
Data type: string
encoding.de
Description: Encoding for 'de' locale
Required: false
Data type: string
encoding.es
Description: Encoding for 'es' locale
Required: false
Data type: string
encoding.pt
Description: Encoding for 'pt' locale
Required: false
Data type: string
encoding.da
Description: Encoding for 'da' locale
Required: false
Data type: string
encoding.ca
Description: Encoding for 'ca' locale
Required: false
Data type: string
encoding.fi
Description: Encoding for 'fi' locale
Required: false
Data type: string
encoding.it
Description: Encoding for 'it' locale
Required: false
Data type: string
encoding.nl
Description: Encoding for 'nl' locale
Required: false
Data type: string
encoding.no
Description: Encoding for 'no' locale
Required: false
Data type: string
encoding.sv
Description: Encoding for 'sv' locale
Required: false
Data type: string
encoding.is
Description: Encoding for 'is' locale
Required: false
Data type: string
encoding.eu
Description: Encoding for 'eu' locale
Required: false
Data type: string
encoding.cs
Description: Encoding for 'cs' locale
Required: false
Data type: string
encoding.hr
Description: Encoding for 'hr' locale
Required: false
Data type: string
encoding.hu
Description: Encoding for 'hu' locale
Required: false
Data type: string
encoding.lt
Description: Encoding for 'lt' locale
Required: false
Data type: string
encoding.pl
Description: Encoding for 'pl' locale
Required: false
Data type: string
encoding.sh
Description: Encoding for 'sh' locale
Required: false
Data type: string
encoding.sk
Description: Encoding for 'sk' locale
Required: false
Data type: string
encoding.sl
Description: Encoding for 'sl' locale
Required: false
Data type: string
encoding.sq
Description: Encoding for 'sq' locale
Required: false
Data type: string
encoding.fo
Description: Encoding for 'fo' locale
Required: false
Data type: string
encoding.ro
Description: Encoding for 'ro' locale
Required: false
Data type: string
encoding.mt
Description: Encoding for 'mt' locale
Required: false
Data type: string
encoding.et
Description: Encoding for 'et' locale
Required: false
Data type: string
encoding.lv
Description: Encoding for 'lv' locale
Required: false
Data type: string
encoding.be
Description: Encoding for 'be' locale
Required: false
Data type: string
encoding.bg
Description: Encoding for 'bg' locale
Required: false
Data type: string
encoding.mk
Description: Encoding for 'mk' locale
Required: false
Data type: string
encoding.ru
Description: Encoding for 'ru' locale
Required: false
Data type: string
encoding.sr
Description: Encoding for 'sr' locale
Required: false
Data type: string
encoding.uk
Description: Encoding for 'uk' locale
Required: false
Data type: string
encoding.ar
Description: Encoding for 'ar' locale
Required: false
Data type: string
encoding.fa
Description: Encoding for 'fa' locale
Required: false
Data type: string
encoding.ms
Description: Encoding for 'ms' locale
Required: false
Data type: string
encoding.el
Description: Encoding for 'el' locale
Required: false
Data type: string
encoding.iw
Description: Encoding for 'iw' locale
Required: false
Data type: string
encoding.he
Description: Encoding for 'he' locale
Required: false
Data type: string
encoding.ji
Description: Encoding for 'ji' locale
Required: false
Data type: string
encoding.yi
Description: Encoding for 'yi' locale
Required: false
Data type: string
encoding.tr
Description: Encoding for 'tr' locale
Required: false
Data type: string
encoding.th
Description: Encoding for 'th' locale
Default value: windows-874
Required: false
Data type: string
encoding.vi
Description: Encoding for 'vi' locale
Default value: windows-1258
Required: false
Data type: string
encoding.ja
Description: Encoding for 'ja' locale
Default value: Shift_JIS
Required: false
Data type: string
encoding.ko
Description: Encoding for 'ko' locale
Default value: EUC-KR
Required: false
Data type: string
encoding.zh
Description: Encoding for 'zh' locale
Default value: GB2312
Required: false
Data type: string
encoding.zh_TW
Description: Encoding for 'zh_TW' locale
Default value: Big5
Required: false
Data type: string
encoding.hy
Description: Encoding for 'hy' locale
Default value: UTF-8
Required: false
Data type: string
encoding.ka
Description: Encoding for 'ka' locale
Required: false
Data type: string
encoding.hi
Description: Encoding for 'hi' locale
Required: false
Data type: string
encoding.mr
Description: Encoding for 'mr' locale
Required: false
Data type: string
encoding.sa
Description: Encoding for 'sa' locale
Required: false
Data type: string
encoding.ta
Description: Encoding for 'ta' locale
Required: false
Data type: string
encoding.bn
Description: Encoding for 'bn' locale
Required: false
Data type: string
httpEndpoint
Configuration properties for an HTTP endpoint. PID is com.ibm.ws.http.
Attributes
httpOptionsRef
Description: HTTP protocol options for the endpoint.
Inherits: defaultHTTPVar
Required: false
Data type: Configuration ID of type httpOptions (string).
tcpOptionsRef
Description: TCP protocol options for the endpoint.
Default value: defaultTCPOptions
Required: false
Data type: Configuration ID of type tcpOptions (string).
enabled
Description: Toggle the availability of an endpoint. When true, this
endpoint will be activated by the dispatcher to handle HTTP requests.
Default value: true
Required: false
Data type: boolean
host
Description: IP address, domain name server (DNS) host name with
domain name suffix, or just the DNS host name, used by a client to
request a resource. Use '*' for all available network interfaces.
Inherits: defaultHostName
Required: false
Data type: string
httpPort
Description: The port used for client HTTP requests. Use -1 to disable
this port.
Required: false
Data type: int
httpsPort
Description: The port used for client HTTP requests secured with SSL
(https). Use -1 to disable this port.
Required: false
Data type: int
virtualHost
Description: ID of a configured virtual host. All endpoints are associated
with the 'default_host' virtual host by default.
Default value: default_host
Required: false
Data type: string
sslOptionsRef
Description: SSL protocol options for the endpoint.
Inherits: defaultSSLVar
Required: false
Data type: Configuration ID of type sslOptions (string).
Sub-elements
httpOptions
Description: HTTP protocol options for the endpoint.
Inherits: defaultHTTPVar
Required: false
Data type: Element of type httpOptions.
tcpOptions
Required: false
Data type: Element of type tcpOptions.
sslOptions
Required: false
Data type: Element of type sslOptions.
httpOptions
HTTP protocol configuration. PID is com.ibm.ws.http.options.
Attributes
keepAliveEnabled
Description: Enables persistent connections (HTTP keepalive). If true,
connections are kept alive for reuse by multiple sequential requests and
responses. If false, connections are closed after the response is sent.
Default value: true
Required: false
Data type: boolean
maxKeepAliveRequests
Description: Maximum number of persistent requests that are allowed on
a single HTTP connection if persistent connections are enabled. A value of
-1 means unlimited.
Default value: 100
Required: false
Data type: int
persistTimeout
Description: Amount of time that a socket will be allowed to remain idle
between requests. This setting only applies if persistent connections are
enabled. Specify a positive integer followed by a unit of time, which can
Default value: 30s
Required: false
Data type: string
readTimeout
Description: Amount of time to wait for a read request to complete on a
socket after the first read occurs. Specify a positive integer followed by a
unit of time, which can be hours (h), minutes (m), or seconds (s). For
Default value: 60s
Required: false
Data type: string
writeTimeout
Description: Amount of time to wait on a socket for each portion of the
response data to be transmitted. Specify a positive integer followed by a
Default value: 60s
Required: false
Data type: string
httpSession
Configuration for HTTP session management. PID is com.ibm.ws.session.
Attributes
storageRef
Description: The ID of the persistent storage location for session data. If
no storage location is defined, session data will be stored in the local
application server's memory.
Required: false
Data type: string
sslTrackingEnabled
Description: Specifies that session tracking uses Secure Sockets Layer
(SSL) information as a session ID.
Required: false
Data type: boolean
urlRewritingEnabled
Description: Specifies that the session management facility uses rewritten
URLs to carry the session IDs.
Required: false
Data type: boolean
protocolSwitchRewritingEnabled
Description: Adds the session ID to a URL when the URL requires a
switch from HTTP to HTTPS or from HTTPS to HTTP.
Required: false
Data type: boolean
cookiesEnabled
Description: Specifies that session tracking uses cookies to carry session
IDs.
Default value: true
Required: false
Data type: boolean
cookieName
Description: A unique name for a session management cookie.
Default value: JSESSIONID
Required: false
Data type: string
cookieDomain
Description: Domain field of a session tracking cookie.
Default value:
Required: false
Data type: string
cookieMaxAge
Description: Maximum amount of time that a cookie can reside on the
client browser.
Default value: -1
Required: false
Data type: int
cookiePath
Description: A cookie is sent to the URL designated in the path.
Default value: /
Required: false
Data type: string
cookieSecure
Description: Specifies that the session cookies include the secure field.
Required: false
Data type: boolean
cookieHttpOnly
Description: Specifies that session cookies include the HttpOnly field.
Browsers that support the HttpOnly field do not enable cookies to be
accessed by client-side scripts. Using the HttpOnly field will help prevent
cross-site scripting attacks.
Default value: true
Required: false
Data type: boolean
maxInMemorySessionCount
Description: Maximum number of sessions to maintain in memory for
each web module.
Default value: 1000
Required: false
Data type: int
allowOverflow
Description: Allows the number of sessions in memory to exceed the
value of the Max in-memory session count property.
Default value: true
Required: false
Data type: boolean
invalidationTimeout
Description: Amount of time a session can go unused before it is no
longer valid.
Default value: 1800
Required: false
Data type: long
securityIntegrationEnabled
Description: Enables security integration, which causes the session
management facility to associate the identity of users with their HTTP
sessions.
Default value: true
Required: false
Data type: boolean
idLength
Description: Length of the session identifier.
Default value: 23
Required: false
Data type: int
useContextRootAsCookiePath
Description: Specifies that the cookie path equals the context root of the
web module instead of /
Required: false
Data type: boolean
alwaysEncodeUrl
Description: The Servlet 2.5 specification specifies to not encode the URL
on a response.encodeURL call if it is not necessary. To support backward
compatibility when URL encoding is enabled, set this property to true to
call the encodeURL method. The URL is always encoded, even if the
browser supports cookies.
Required: false
Data type: boolean
cloneId
Description: The clone ID of the cluster member. Within a cluster, this ID
must be unique to maintain session affinity. When set, this name
overwrites the default name generated by the server.
Required: false
Data type: string
cloneSeparator
Description: The single character used to separate the session ID from the
clone ID in session cookies. The default value should usually be used. On
some Wireless Application Protocol (WAP) devices, a colon (:) is not
allowed, so a plus sign (+) should be used instead. Different values
should rarely be used. You should understand the clone character
requirements of other products running on your system before using this
property to change the clone separator character. The fact that any
character can be specified as the value for this property does not imply
that the character you specify will function correctly. This fact also does
not imply that IBM is responsible for fixing any problem that might arise
from using an alternative character.
Default value: :
Required: false
Data type: string
debugCrossover
Description: Enable this option to perform additional checks to verify
that only the session associated with the request is accessed or referenced,
and log messages if any discrepancies are detected. Disable this option to
skip the additional checks.
Required: false
Data type: boolean
forceInvalidationMultiple
Description: If your requests normally are not bound by a response time
limit, specify 0 to indicate that the session manager should wait
indefinitely until a request is complete before attempting to invalidate the
session. Otherwise, set this property to a positive integer to delay the
invalidation of active sessions. Active timed out sessions will not be
invalidated by the first invalidation interval pass, but will be invalidated
by the interval pass based on this value. For example, a value of 2 would
invalidate an active session on the second invalidation interval pass after
the session timeout has expired.
Default value: 3
Required: false
Data type: int
idReuse
Description: In a multi-JVM environment that is not configured for
session persistence, setting this property to "true" enables the session
manager to use the same session information for all of a user's requests
even if the web applications that are handling these requests are
governed 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 use
the session ID sent from a browser to preserve session data across web
applications that are running in an environment that is not configured for
session persistence.
Required: false
Data type: boolean
noAdditionalInfo
Description: Forces removal of information that is not needed in session
identifiers.
Required: false
Data type: boolean
reaperPollInterval
Description: The wake-up interval, in seconds, for the process that
removes invalid sessions. The minimum value is 30 seconds. If a value
less than the minimum is entered, an appropriate value is automatically
determined 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 is
usually between 2 and 3 minutes.
Default value: -1
Required: false
Data type: long
rewriteId
Description: Use this property to change the key used with URL
rewriting.
Default value: jsessionid
Required: false
Data type: string
securityUserIgnoreCase
Description: Indicates that the session security identity and the client
security identity should be considered a match even if their cases are
different. For example, when this property is set to true, the session
security identity USER1 matches the client security identities User1 and
user1.
Required: false
Data type: boolean
invalidateOnUnauthorizedSessionRequestException Description: Set this property to true if, in response to an unauthorized
request, you want the session manager to invalidate a session instead of
issuing an UnauthorizedSessionRequestException. When a session is
invalidated, the requester can create a new session, but does not have
access to any of the previously saved session data. This allows a single
user to continue processing requests to other applications after a logout
while still protecting session data.
Required: false
Data type: boolean
httpSessionDatabase
Controls how HTTP sessions are persisted to a database. PID is
com.ibm.ws.session.db.
Attributes
dataSourceRef
Description: The ID of the data source the session manager should use to
persist HTTP session data.
Required: true
Data type: string
useMultiRowSchema
Description: When enabled, each session data attribute is placed in a
separate row in the database, allowing larger amounts of data to be
stored for each session. This configuration can yield better performance
when session attributes are very large and few changes are required to
the session attributes. When disabled, all session data attributes are
placed in the same row for each session.
Required: false
Data type: boolean
db2RowSize
Description: Table space page size configured for the sessions table, if
using a DB2 database. Increasing this value can improve database
performance in some environments.
Default value: 4KB
Range:
4KB Use the default table space page size of 4 KB. You do not need to
create a DB2 buffer pool or table space, and you do not need to
specify a table space name.
8KB Use a table space page size of 8 KB. You must additionally create
a DB2 buffer pool and table space, and specify 8KB as the page
size for both. You must also specify the name of the table space
you created.
16KB Use a table space page size of 16 KB. You must additionally
create a DB2 buffer pool and table space, and specify 16KB as the
page size for both. You must also specify the name of the table
space you created.
32KB Use a table space page size of 32 KB. You must additionally
create a DB2 buffer pool and table space, and specify 32KB as the
page size for both. You must also specify the name of the table
space you created.
Required: false
Data type: string
tableSpaceName
Description: Table space to be used for the sessions table. This value is
only required when the DB2 Row Size is greater than 4KB.
Default value:
Required: false
Data type: string
scheduleInvalidation
Description: Enable this option to reduce the number of database updates
required to keep the HTTP sessions alive. Specify the two hours of a day
when there is the least activity in the application server. When this option
is disabled, the invalidator process runs every few minutes to remove
invalidated HTTP sessions.
Required: false
Data type: boolean
scheduleInvalidationFirstHour
Description: Indicates the first hour during which the invalidated
sessions are cleared from the persistent store. Specify this value as an
integer between 0 and 23. This value is valid only when schedule
invalidation is enabled.
Default value: 0
Required: false
Data type: int
scheduleInvalidationSecondHour
Description: Indicates the second hour during which the invalidated
sessions are cleared from the persistent store. Specify this value as an
integer between 0 and 23. This value is valid only when schedule
invalidation is enabled.
Default value: 0
Required: false
Data type: int
writeFrequency
Description: Specifies when session data is written to the persistent store.
By default, session data is written to the persistent store after the servlet
completes execution. Changing this value can improve performance in
some environments.
Default value: END_OF_SERVLET_SERVICE
Range:
END_OF_SERVLET_SERVICE
Session data is written to the persistent store after the servlet
completes execution.
MANUAL_UPDATE
A programmatic sync on the IBMSession object is required to
write the session data to the persistent store.
TIME_BASED_WRITE
Session data is written to the persistent store based on the
specified write interval value.
Required: false
Data type: string
writeInterval
Description: Number of seconds that should pass before writing session
data to the persistent store. The default is 120 seconds. This value is only
used when a time based write frequency is enabled.
Default value: 120
Required: false
Data type: int
writeContents
Description: Specifies how much session data should be written to the
persistent store. By default, only updated attributes are written, but all
attributes can be written instead (regardless of whether or not they
changed).
Default value: ONLY_UPDATED_ATTRIBUTES
Range:
ONLY_UPDATED_ATTRIBUTES
Only updated attributes are written to the persistent store.
ALL_SESSION_ATTRIBUTES
All attributes are written to the persistent store.
Required: false
Data type: string
noAffinitySwitchBack
Description: Set this property to "true" to maintain affinity to the new
member even after original one comes back up. When a cluster member
fails, its requests routed to a different cluster member, and sessions are
activated in that other member. Thus, session affinity is maintained to the
new member, and when failed cluster member comes back up, the
requests for sessions that were created in the original cluster member are
routed back to it. Allowed values are true or false, with the default being
false. Set this property to true when you have distributed sessions
configured with time-based write. Note that this property has no affect on
the behavior when distributed sessions are not enabled.
Required: false
Data type: boolean
onlyCheckInCacheDuringPreInvoke
Description: A value of true indicates that the last access time of a
session should only be updated if a request gets the session. A value of
false indicates that the last access time of a session should be updated
upon every request. Changing this value can improve performance in
some environments.
Required: false
Data type: boolean
optimizeCacheIdIncrements
Description: If the user's browser session is moving back and forth across
multiple web applications, you might see extra persistent store activity as
the in-memory sessions for a web module are refreshed from the
persistent store. As a result, the cache IDs are continually increasing and
the in-memory session attributes are overwritten by those of the
persistent copy. Set this property to true if you want to prevent the cache
IDs from continually increasing. A value of true indicates that the session
manager should assess whether the in-memory session for a web module
is 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 as
possible.
Default value: true
Required: false
Data type: boolean
tableName
Description: The database table name.
Default value: sessions
Required: false
Data type: string
useInvalidatedId
Description: Set this property to "true" to reuse the incoming ID if the
session with that ID was recently invalidated. This is a performance
optimization because it prevents checking the persistent store.
Default value: true
Required: false
Data type: boolean
useOracleBlob
Description: Set this property to "true" to create the database table using
the Binary Large Object (BLOB) data type for the medium column. This
value increases performance of persistent sessions when Oracle databases
are used. Due to an Oracle restriction, BLOB support requires use of the
Oracle Call Interface (OCI) database driver for more than 4000 bytes of
data. You must also ensure that a new sessions table is created before the
server is restarted by dropping your old sessions table or by changing the
datasource definition to reference a database that does not contain a
sessions table.
Required: false
Data type: boolean
skipIndexCreation
Description: Set this property to "true" to disable index creation on server
startup. This custom property should only be used if you want to
manually create your own database indices for session persistence.
However, it is recommended that you let session manager create database
indices. Before enabling this property, make sure that the correct index
does exist on your session database.
Required: false
Data type: boolean
usingCustomSchemaName
Description: Set this property to "true" if you are using DB2 for session
persistence and the currentSchema property is set in the data source.
Required: false
Data type: boolean
idsLdapFilterProperties
Specifies the list of default IBM Tivoli
Directory Server LDAP filters. PID is

com.ibm.ws.security.registry.ldap.internal.filters.ids.
Attributes
userFilter
users.
Required: true
Data type: string
groupFilter
groups.
Default value:
(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))
Required: true
Data type: string
userIdMap
entry.
Required: true
Data type: string
groupIdMap
entry.
Default value: *:cn
Required: true
Data type: string
groupMemberIdMap
Default value:
ibm-allGroups:member;ibm-allGroups:uniqueMember;
Required: true
Data type: string
include
Specify a configuration resource to include in the servers configuration.
Attributes
optional
Description: Allow the included resource to be skipped if it cannot be
found.
Required: false
Data type: boolean
location
Description: The resource location, this could be a file path or a URI for a
remote resource.
Required: true
Data type: string
iplanetLdapFilterProperties
Specifies the list of default Sun Java System Directory Server LDAP filters. PID is
com.ibm.ws.security.registry.ldap.internal.filters.iPlanet.
Attributes
userFilter
users.
Default value: (&(uid=%v)(objectclass=inetOrgPerson))
Required: true
Data type: string
groupFilter
groups.
Default value: (&(cn=%v)(objectclass=ldapsubentry))
Required: true
Data type: string
userIdMap
entry.
Default value: inetOrgPerson:uid
Required: true
Data type: string
groupIdMap
entry.
Default value: *:cn
Required: true
Data type: string
groupMemberIdMap
Default value: nsRole:nsRole
Required: true
Data type: string
jaasLoginContextEntry
The JAAS login context entry configuration. PID is
com.ibm.ws.security.authentication.internal.jaas.jaasLoginContextEntry.
Attributes
name
Description: Name of a JAAS configuration entry.
Required: true
Data type: string
loginModuleRef
Description: 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
jaasLoginModule
A login module in the JAAS configuration. PID is
com.ibm.ws.security.authentication.internal.jaas.jaasLoginModuleConfig.
Attributes
className
Description: Fully-qualified package name of the JAAS login module
class.
Required: true
Data type: string
controlFlag
Description: The login module's control flag. Valid values are
REQUIRED, REQUISITE, SUFFICIENT, and OPTIONAL.
Default value: REQUIRED
Range:
REQUIRED
This LoginModule is REQUIRED as per the JAAS specification.
The LoginModule is required to succeed.
REQUISITE
controlFlag.REQUISITE
SUFFICIENT
This LoginModule is SUFFICIENT as per the JAAS specification.
The LoginModule is not required to succeed. If authentication is
successful, no other LoginModules will be called and control is
returned to the caller.
OPTIONAL
This LoginModule is OPTIONAL as per the JAAS specification.
The LoginModule is not required to succeed.
Required: true
Data type: string
libraryRef
Description: A reference to the ID of the shared library configuration.
Required: false
Data type: Configuration ID of type library (string).
Sub-elements
library
Required: false
options
Description: A collection of JAAS Login module options
Required: false
jdbcDriver
Identifies a JDBC driver. PID is com.ibm.ws.jdbc.jdbcDriver.
Attributes
libraryRef
Description: Identifies JDBC driver JARs and native files.
Required: false
javax.sql.XADataSource
Description: JDBC driver implementation of javax.sql.XADataSource.
Required: false
Data type: string
javax.sql.ConnectionPoolDataSource
Description: JDBC driver implementation of
javax.sql.ConnectionPoolDataSource.
Required: false
Data type: string
javax.sql.DataSource
Description: JDBC driver implementation of javax.sql.DataSource.
Required: false
Data type: string
Sub-elements
library
Description: Identifies JDBC driver JARs and native files.
Required: false
jmsCommsEndpoint
Configuration properties for JMS incoming connection requests. PID is
com.ibm.ws.messaging.comms.server.
Attributes
tcpOptionsRef
Required: false
enabled
Description: Toggle the availability of an JMS Comms endpoint. When
true, this endpoint will be activated by the JMS Comms component.
Default value: true
Required: false
Data type: boolean
host
Description: IP address, domain name server (DNS) host name with
domain name suffix, or just the DNS host name, used by a client to
request a resource. Use '*' for all available network interfaces.
Required: false
Data type: string
jmsPort
Description: The port used for client messaging application connection
request. Use -1 to disable this port.
Default value: 7276
Required: false
Data type: int
jmsSSLPort
Description: The port used for client messaging application connection
requests secured with SSL. Use -1 to disable this port.
Default value: 7286
Required: false
Data type: int
sslOptionsRef
Required: false
Sub-elements
tcpOptions
Required: false
sslOptions
Required: false
jmsCommsOutbound
%jmsCommsOutbound.desc. PID is com.ibm.ws.messaging.comms.client.
Attributes
tcpOptionsRef
Description: TCP protocol options for JMS Comms outbound
Required: false
sslOptionsRef
Description: SSL protocol options for JMS Comms outbound
Required: false
Sub-elements
tcpOptions
Description: TCP protocol options for JMS Comms outbound
Required: false
sslOptions
Description: SSL protocol options for JMS Comms outbound
Required: false
jmsConnectionFactory
Defines a JMS connection factory configuration. PID is
com.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 is
com.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 is
com.ibm.ws.jca.jmsTopicConnectionFactory.
jndiEntry
A single entry in the JNDI default namespace. PID is
com.ibm.ws.jndi.internal.JNDIEntry.
Attributes
jndiName
Description: The JNDI name to use for this entry.
Required: true
Data type: string
value
Description: The JNDI value to associate with the name.
Required: true
Data type: string
jpa
Configuration properties for the Java Persistence API container. PID is
com.ibm.ws.jpacomponent.
Attributes
defaultJtaDataSourceJndiName
Description: Default Java
Transaction API (JTA) data source JNDI name

to be used by applications running in this server. By default, data sources
are JTA. Only data sources that are transactional are allowed in this field.
Default value:
Required: false
Data type: string
defaultNonJtaDataSourceJndiName
Description: Default non-transactional data source JNDI name to be used
by applications running in this server. Only data sources that have been
marked as non-transactional are allowed in this field.
Default value:
Required: false
Data type: string
defaultPersistenceProvider
Description: Default persistence provider.
Default value: com.ibm.websphere.persistence.PersistenceProviderImpl
Required: false
Data type: string
entityManagerPoolCapacity
Description: EntityManager pool capacity per PersistenceContext
reference. The minimum is 0 and the maximum is 500.
Default value: -1
Required: false
Data type: int
Sub-elements
excludedApplication
Description: An application to be excluded from JPA processing.
Default value:
Required: false
Data type: string
jspEngine
JSP 2.2 configuration. PID is com.ibm.ws.jsp.2.2.
Attributes
disableJspRuntimeCompilation
Description: Disable compilation of JSPs at runtime.
Required: false
Data type: boolean
extendedDocumentRoot
Description: Directory that the JSP engine will search for additional JSP
files to serve.
Default value:
Required: false
Data type: string
jdkSourceLevel
Description: Default Java source level for JSPs compiled by the JSP
engine.
Default value: 15
Range:
13
14
15
16
Required: false
Data type: string
keepGenerated
Description: Keep Java source files generated for JSPs.
Required: false
Data type: boolean
useInMemory
Description: Generate Java source and classes in memory (without
writing to disk).
Required: false
Data type: boolean
recompileJspOnRestart
Description: Recompile JSPs after an application is restarted. JSPs are
recompiled on first access.
Required: false
Data type: boolean
useImplicitTagLibs
Description: Allow JSPs to use jsx and tsx tag libs.
Default value: true
Required: false
Data type: boolean
disableResourceInjection
Description: Disable injection of resources into JSPs.
Required: false
Data type: boolean
prepareJSPs
Description: When this attribute is present, all JSPs larger than the value
(in kilobytes) are compiled at application server startup. Set this to 0 to
compile all JSPs.
Required: false
Data type: int
keyStore
A repository of security certificates used for SSL encryption. PID is
com.ibm.ws.ssl.keystore.
Attributes
password
Description: The password used to load the keystore file. The value can
be stored in clear text or encoded form. Use the securityUtility tool to
encode the password.
Required: true
location
Description: An absolute or relative path to the keystore file. If a relative
path is provided, the server will attempt to locate the file in the
${server.config.dir}/resources/security directory. Use the keystore file for
a file-based keystore, the keyring name for SAF keyrings, or the device
configuration file for hardware cryptography devices. In the SSL minimal
configuration, 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
type
Description: A keystore type supported by the target SDK.
Default value: jks
Required: false
Data type: string
ldapRegistry
Configuration properties for an LDAP user registry. PID is
com.ibm.ws.security.registry.ldap.config.
Attributes
host
Description: Address of the LDAP server in the form of a IP address or a
domain name service (DNS) name.
Required: true
Data type: string
port
Description: Port number of the LDAP server.
Required: true
Data type: int
baseDN
Description: Base distinguished name (DN) of the directory service,
which indicates the starting point for LDAP searches in the directory
service.
Required: true
Data type: string
ldapType
Description: Type of LDAP server to which a connection will be
established.
Range:
Microsoft Active Directory
actived
Custom
IBM Lotus Domino
domino50
Novell eDirectory
edirectory
IBM Tivoli Directory Server
ibm_dir_server
Sun Java System Directory Server
iplanet
Netscape Directory Server
netscape
IBM SecureWay Directory Server
secureway
Required: true
Data type: string
realm
Default value: LdapRegistry
Required: false
Data type: string
bindDN
Description: Distinguished name (DN) for the application server, which is
used to bind to the directory service.
Required: false
Data type: string
bindPassword
Description: Password for the bind DN. The value can be stored in clear
text or encoded form. It is recommended that you encode the password.
To do so, use the securityUtility tool with the encode option.
Required: false
ignoreCase
Description: Perform a case-insensitive authentication check.
Default value: true
Required: false
Data type: boolean
recursiveSearch
Description: Performs a nested group search. Select this option only if the
LDAP server does not support recursive server-side searches.
Required: false
Data type: boolean
reuseConnection
Description: Requests the application server to reuse the LDAP server
connection.
Default value: true
Required: false
Data type: boolean
sslEnabled
Description: Indicates whether an SSL connection should be made to the
LDAP server.
Required: false
Data type: boolean
sslRef
Description: ID of the SSL configuration to be used to connect to the
SSL-enabled LDAP server.
Required: false
Data type: string
searchTimeout
Description: Maximum time for an LDAP server to respond before a
request is canceled. This is equivalent to a read timeout once the
connection is established. Specify a positive integer followed by a unit of
1.5 seconds.
Default value: 1m
Required: false
Data type: string
connectTimeout
Description: Maximum time for establishing a connection to the LDAP
server. Specify a positive integer followed by a unit of time, which can be
hours (h), minutes (m), seconds (s), or milliseconds (ms). For example,
Default value: 1m
Required: false
Data type: string
certificateMapMode
Description: Specifies whether to map x.509 certificates into an LDAP
directory by EXACT_DN or CERTIFICATE_FILTER. Specify
CERTIFICATE_FILTER to use the specified certificate filter for the
mapping.
Range:
EXACT_DN
exactDN
CERTIFICATE_FILTER
certFilter
Required: false
Data type: string
certificateFilter
Description: Specifies the filter certificate mapping property for the
LDAP filter. The filter is used to map attributes in the client certificate to
entries in the LDAP registry. For example, the filter can be specified as:
uid=${SubjectCN}.
Required: false
Data type: string
activedFiltersRef
Description: Specifies the list of default Microsoft Active Directory LDAP
filters.
Required: false
Data type: Configuration ID of type activedLdapFilterProperties (string).
customFiltersRef
Description: Specifies the list of default Custom LDAP filters.
Required: false
Data type: Configuration ID of type customLdapFilterProperties (string).
domino50FiltersRef
Description: Specifies the list of default IBM Lotus Domino LDAP filters.
Required: false
Data type: Configuration ID of type domino50LdapFilterProperties
(string).
edirectoryFiltersRef
Description: Specifies the list of Novell eDirectory LDAP filters.
Required: false
Data type: Configuration ID of type edirectoryLdapFilterProperties
(string).
idsFiltersRef
Description: Specifies the list of default IBM Tivoli Directory Server
LDAP filters.
Required: false
Data type: Configuration ID of type idsLdapFilterProperties (string).
iplanetFiltersRef
Description: Specifies the list of default Sun Java System Directory Server
LDAP filters.
Required: false
Data type: Configuration ID of type iplanetLdapFilterProperties (string).
netscapeFiltersRef
Description: Specifies the list of default Netscape Directory Server LDAP
filters.
Required: false
Data type: Configuration ID of type netscapeLdapFilterProperties (string).
securewayFiltersRef
Description: Specifies the list of default IBM SecureWay Directory Server
LDAP filters.
Required: false
Data type: Configuration ID of type securewayLdapFilterProperties
(string).
Sub-elements
failoverServers
Description: List of LDAP failover servers.
Required: false
Data type: List of LDAP failover servers.
name
Description: Configuration properties for LDAP failover servers.
Required: false
Data type: string
server
Description: Configuration properties for LDAP failover server.
Required: false
Data type: Configuration properties for LDAP failover server.
host
Description: LDAP server host name, which can be either an IP
address or a domain name service (DNS) name.
Required: true
Data type: string
port
Description: LDAP failover server port.
Required: true
Data type: int
activedFilters
Description: Specifies the list of default Microsoft Active Directory LDAP
filters.
Required: false
Data type: Element of type activedLdapFilterProperties.
customFilters
Description: Specifies the list of default Custom LDAP filters.
Required: false
Data type: Element of type customLdapFilterProperties.
domino50Filters
Description: Specifies the list of default IBM Lotus Domino LDAP filters.
Required: false
Data type: Element of type domino50LdapFilterProperties.
edirectoryFilters
Description: 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 Server
LDAP filters.
Required: false
Data type: Element of type idsLdapFilterProperties.
iplanetFilters
Description: Specifies the list of default Sun Java System Directory Server
LDAP filters.
Required: false
Data type: Element of type iplanetLdapFilterProperties.
netscapeFilters
Description: Specifies the list of default Netscape Directory Server LDAP
filters.
Required: false
Data type: Element of type netscapeLdapFilterProperties.
securewayFilters
Description: Specifies the list of default IBM SecureWay Directory Server
LDAP filters.
Required: false
Data type: Element of type securewayLdapFilterProperties.
library
Shared Library. PID is com.ibm.ws.classloading.sharedlibrary.
Attributes
name
Description: Name of shared library for administrators
Required: false
Data type: string
description
Description: Description of shared library for administrators
Required: false
Data type: string
filesetRef
Description: Id of referenced Fileset
Required: false
Data type: List of configuration IDs of type fileset (comma-separated
string).
apiTypeVisibility
Description: The types of API package this library's class loader will be
able to see, 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
fileset
Description: Id of referenced Fileset
Required: false
Data type: Element of type fileset.
folder
Description: Id of referenced folder
Required: false
Data type: Folder containing resources such as .properties and .class files.
dir
Description: Directory or folder to be included in the library
classpath for locating resource files
Required: true
Data type: string
file
Description: Id of referenced File
Required: false
Data type: Add a file to be included in this library.
name
Description: Fully qualified filename
Required: true
Data type: string
localStore
Clients are defined in server.xml and tokens are cached in the server. PID is
com.ibm.ws.security.oauth20.local.store.
Attributes
clientRef
Required: false
Data type: List of configuration IDs of type client (comma-separated
string).
Sub-elements
client
Required: false
Data type: Element of type client.
logging
Controls the output of log and trace messages. PID is com.ibm.ws.logging.
Attributes
maxFileSize
Description: Maximum size of a log file, in megabytes, before being
rolled over; a value of 0 means no limit.
Inherits: com.ibm.ws.logging.max.file.size
Default value: 20
Required: false
Data type: int
maxFiles
Description: Maximum number of log files that will be kept, before the
oldest 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
logDirectory
Description: Location to which all log files will be written. The default
value is ${server.output.dir}/logs.
Inherits: com.ibm.ws.logging.log.directory
Default value: ${server.output.dir}/logs
Required: false
Data type: string
messageFileName
Description: Name of the file to which message output will be written
relative 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
traceFileName
Description: Name of the file to which trace output will be written
relative 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
traceSpecification
Description: A trace specification that conforms to the trace specification
grammar and specifies the initial state for various trace components. An
empty value is allowed and treated as 'disable all trace'. Any component
that 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
traceFormat
Description: This format is used for the trace log.
Inherits: com.ibm.ws.logging.trace.format
Default value: ENHANCED
Range:
BASIC
Use the basic trace format.
ENHANCED
Use the enhanced basic trace format.
ADVANCED
Use the advanced trace format.
Required: false
Data type: string
consoleLogLevel
Description: The logging level used to filter messages written to system
streams. 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 system
output stream. Error messages will be written to the system error
stream.
AUDIT
Audit and warning messages will be written to the system output
stream. Error messages will be written to the system error stream.
WARNING
Warning messages will be written to the system output stream.
Error messages will be written to the system error stream.
ERROR
Error messages will be written to the system error stream.
OFF No server output will be written to system streams. Only JVM
output will be written to system streams.
Required: false
Data type: string
ltpa
Lightweight Third Party Authentication (LTPA) token configuration. PID is
com.ibm.ws.security.token.ltpa.LTPAConfiguration.
Attributes
keysFileName
Description: Path of the file containing the token keys.
Default value: ${server.config.dir}/resources/security/ltpa.keys
Required: false
Data type: string
keysPassword
Description: Password for the token keys. The value can be stored in
clear 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
expiration
Description: Amount of time after which a token expires in minutes.
(h) or minutes (m). For example, specify 30 minutes as 30m. You can
include multiple values in a single entry. For example, 1h30m is
equivalent to 90 minutes.
Default value: 120m
Required: false
Data type: string
monitorInterval
Description: Rate at which the server checks for updates to the LTPA
token 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 multiple
seconds.
Default value: 0ms
Required: false
Data type: string
managedExecutorService
PID is com.ibm.ws.concurrent.managedExecutorService.
Attributes
contextServiceRef
Description: contextServiceRef.desc
Default value: DefaultContextService
Required: false
Data type: Configuration ID of type contextService (string).
jndiName
Description: JNDI name for a managed executor service
Required: false
Data type: string
Sub-elements
contextService
Description: 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
electionPort
Description: Host leader election port
Required: true
Data type: int
managementRepository
Management repository configuration. PID is com.ibm.ws.management.repository.
Sub-elements
cohort
Description: The endpoint of a management repository cohort
Required: false
Data type: string
managementRepositoryConnection
The management repository connection configuration, which consists of at least
one bootstrap address (host and port). The management repository connection can
have multiple bootstrap addresses. PID is
com.ibm.ws.management.repository.connection.
Attributes
bootstrapHost
Description: A host name for a management repository bootstrap
instance.
Required: true
Data type: string
bootstrapPort
Description: The port for the JMX/REST connector, typically the HTTPS
port.
Required: true
Data type: int
bootstrapUsername
Description: The user with which to authenticate to the Management
Repository
Required: true
Data type: string
bootstrapPassword
Description: The password for the user with which to authenticate to the
Management Repository
Required: true
sslRef
Description: ID of the SSL configuration to be used to connect to the
SSL-enabled LDAP server.
Default value: defaultSSLConfig
Required: true
Data type: string
Sub-elements
additionalBootstrapAddress
Description: An additional management repository bootstrap address
which will be used in the event of the primary address being unavailable.
Required: false
Data type: An additional management repository bootstrap address
which will be used in the event of the primary address being unavailable.
host
Description: A host name for a management repository bootstrap
instance.
Required: true
Data type: string
port
Description: The port for the JMX/REST connector, typically the
HTTPS port.
Required: true
Data type: int
member
Members of an external cache group that are controlled by WebSphere Application
Server. PID is com.ibm.ws.cache.cacheGroup.member, and it is the child of complex
type cacheGroup.
Attributes
host
Description: Fully qualified host name
Required: false
Data type: string
port
Description: IP port.
Required: false
Data type: int
Sub-elements
adapterBeanName
Description: Specifies the name of a class, which is located on the
WebSphere Application Server class path, of the adapter between
WebSphere Application Server and this external cache.
Required: true
Data type: string
messagingEngine
A messaging engine is a component, running inside a server, that manages
messaging resources. Applications are connected to a messaging engine when they
send and receive messages. PID is com.ibm.ws.messaging.runtime.
Attributes
Sub-elements
fileStore
Description: Messaging File store.
Required: false
Data type: Messaging File store.
path
Description: Path to the file store.
Default value: ${server.output.dir}/messaging/messageStore
Required: false
Data type: string
logFileSize
Description: Size in megabytes of the log file.
Default value: 10
Required: false
Data type: long
fileStoreSize
Description: fileStoreSize.desc
Default value: 400
Required: false
Data type: long
queue
Description: A JMS queue is used as a destination for point-to-point
messaging.
Required: false
Data type: A JMS queue is used as a destination for point-to-point
messaging.
forceReliability
Description: The reliability assigned to a message produced to this
destination when an explicit reliability has not been set by the
producer.
Default value: AssuredPersistent
Range:
BestEffortNonPersistent
ExpressNonPersistent
ReliableNonPersistent
ReliablePersistent
AssuredPersistent
Required: false
Data type: string
exceptionDestination
Description: The destination to which a message is forwarded by the
system when it cannot be delivered to this destination.
Default value: _SYSTEM.Exception.Destination
Required: false
Data type: string
failedDeliveryPolicy
Default value: SEND_TO_EXCEPTION_DESTINATION
Range:
SEND_TO_EXCEPTION_DESTINATION
DISCARD
KEEP_TRYING
Required: false
Data type: string
redeliveryInterval
Description: Indicates the application server the waiting time before a
message is redelivered to an MDB. The waiting time is indicated only
if the exception destination property is set to None, and the
configured number of maximum failed deliveries has been reached.
Default value: -1
Required: false
Data type: long
maxRedeliveryCount
Description: The maximum number of failed attempts to process a
message before the message is forwarded to the exception destination
for the destination. Specify a value in the range 0 - 2147483647. A
value of 0 (zero) means that if a message cannot be delivered on the
first attempt, it is either forwarded to the exception destination or
discarded, as defined by the exceptionDestination property.
Default value: 5
Required: false
Data type: int
sendAllowed
Description: Producers can send messages to this destination.
Default value: true
Required: false
Data type: boolean
receiveAllowed
Description: Clear this option (setting it to false) to prevent
consumers from being able to receive messages from this destination.
Default value: true
Required: false
Data type: boolean
maintainStrictOrder
Description: Maintains the order in which a producer sends messages
to the destination.
Required: false
Data type: boolean
maxQueueDepth
Description: The maximum number of messages that the messaging
engine can place on its message points.
Required: false
Data type: long
topicSpace
Description: topicSpaceRef.desc
Required: false
Data type: topicSpace.desc.
forceReliability
Description: topicSpace.forceReliability.desc
Range:
ReliablePersistent
AssuredPersistent
Required: false
Data type: string
exceptionDestination
Description: topicSpace.exceptionDestination.desc
Default value: _SYSTEM.Exception.Destination
Required: false
Data type: string
failedDeliveryPolicy
Default value: SEND_TO_EXCEPTION_DESTINATION
Range:
SEND_TO_EXCEPTION_DESTINATION
DISCARD
KEEP_TRYING
Required: false
Data type: string
redeliveryInterval
Description: topicSpace.redeliveryInterval.desc
Default value: -1
Required: false
Data type: long
maxRedeliveryCount
Description: topicSpace.maxRedeliveryCount.desc
Default value: 5
Required: false
Data type: int
sendAllowed
Description: topicSpace.sendAllowed.desc
Default value: true
Required: false
Data type: boolean
receiveAllowed
Description: topicSpace.receiveAllowed.desc
Default value: true
Required: false
Data type: boolean
maintainStrictOrder
Description: topicSpace.maintainStrictOrder.desc
Required: false
Data type: boolean
maxQueueDepth
Description: topicSpace.maxQueueDepth.desc
Required: false
Data type: long
alias
Description: An alias destination provides a level of abstraction between
applications and the underlying target destinations that hold messages.
Applications interact with the alias destination, so the target destination
can be changed without changing the application.
Required: false
Data type: An alias destination provides a level of abstraction between
applications and the underlying target destinations that hold messages.
Applications interact with the alias destination, so the target destination
can be changed without changing the application.
targetDestination
Description: The targetDestination parameter identifies a destination
that might be within the same Bus as the alias destination.
Default value:
Required: false
Data type: string
forceReliability
Description: The reliability assigned to a message produced to this
destination when an explicit reliability has not been set by the
producer.
Range:
ReliablePersistent
AssuredPersistent
Required: false
Data type: string
sendAllowed
Description: 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
roleRef
Description: A set of permissions mapped to the users and groups.
Required: false
Data type: List of configuration IDs of type role (comma-separated
string).
Sub-elements
role
Description: A set of permissions mapped to the users and groups.
Required: false
Data type: Element of type role.
mimeTypes
Definition of mime types shared by all http virtual hosts. PID is
com.ibm.ws.http.mimetype.
Sub-elements
type
Description: Definition of mime type as id=value. Use the extension as
the 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
libraryRef
Description: Specifies a library that contains the Mongo Java Driver
Required: false
onError
Description: Determines the action to take in response to configuration
errors.
Inherits: onError
Default value: WARN
Range:
FAIL Fail when incorrect configuration is encountered.
IGNORE
Ignore incorrect configuration.
WARN
onError.WARN
Required: false
Data type: string
password
Description: Password for database user.
Required: false
user
Description: Database user name.
Required: false
Data type: string
alwaysUseMBeans
Description: Configures whether the driver uses MBeans or MXBeans.
Required: false
Data type: boolean
autoConnectRetry
Description: Retry connections to a server, for an interval up to the
maxAutoConnectRetryTime, if the socket cannot be opened.
Required: false
Data type: boolean
connectionsPerHost
Description: Limits the number of open connections to each host.
Connections are pooled when not in use.
Required: false
Data type: int
connectTimeout
Description: Connection timeout for new connections. 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 multiple values in a single entry. For example,
1s500ms is equivalent to 1.5 seconds.
Required: false
Data type: string
cursorFinalizerEnabled
Description: Attempts to clean up DBCursors that are not closed.
Required: false
Data type: boolean
description
Description: Description of a Mongo instance.
Required: false
Data type: string
fsync
Description: Global WriteConcern fsync parameter.
Required: false
Data type: boolean
j Description: Global WriteConcern j parameter.
Required: false
Data type: boolean
maxAutoConnectRetryTime
Description: Interval during which to retry attempts to open a connection
to a server. 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 multiple
seconds.
Required: false
Data type: string
maxWaitTime
Description: Maximum amount of time to wait for an available
connection. If negative, the connection request never times out. 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 multiple values in a single entry.
For example, 1s500ms is equivalent to 1.5 seconds.
Required: false
Data type: string
readPreference
Description: Configures the read preference.
Range:
nearest
primary
primaryPreferred
secondary
secondaryPreferred
Required: false
Data type: string
safe
Description: Use WriteConcern.SAFE unless fsync, j, w, or wtimeout are
configured.
Required: false
Data type: boolean
socketKeepAlive
Description: Configures whether or not to keep sockets alive.
Required: false
Data type: boolean
socketTimeout
Description: The socket timeout. 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 multiple values in a single entry. For example, 1s500ms is
Required: false
Data type: string
threadsAllowedToBlockForConnectionMultiplier
Description: This value, multiplied by connectionsPerHost, establishes an
upper limit on threads that are allowed to wait for an available
connection.
Required: false
Data type: int
w Description: Global write concern w parameter.
Required: false
Data type: int
wtimeout
Description: Global write concern wtimeout parameter. Specify a positive
Required: false
Data type: string
Sub-elements
hostNames
Description: List of host names. The ordering of this list must be
consistent with the list of ports, such that the first element in the list of
host names corresponds to the first element in the list of ports, and so
forth.
Required: true
Data type: string
library
Description: Specifies a library that contains the Mongo Java Driver
Required: false
ports
Description: List of port numbers. The ordering of this list must be
consistent with the list of host names, such that the first element in the
list of host names corresponds to the first element in the list of ports, and
so forth.
Required: false
Data type: int
mongoDB
Configuration for a Mongo DB instance. PID is com.ibm.ws.mongo.mongoDB.
Attributes
databaseName
Description: Name of the database.
Required: true
Data type: string
jndiName
Description: JNDI name for a Mongo DB instance
Required: true
Data type: string
mongoRef
Description: Specifies the Mongo instance.
Required: false
Data type: Configuration ID of type mongo (string).
Sub-elements
mongo
Description: Specifies the Mongo instance.
Required: false
Data type: Element of type mongo.
monitor
Configuration for Monitoring. PID is
com.ibm.ws.monitor.internal.MonitoringFrameworkExtender.
Attributes
enableTraditionalPMI
Description: Internal Property to enable or disable Traditional PMI
Required: false
Data type: boolean
nativeTransactionManager
Configures the RRS Native Transaction Manager. PID is com.ibm.ws.zos.tx.
Attributes
shutdownTimeout
Description: The amount of time to wait before allowing the native
context manager to stop if one or more native contexts are in-use. A
native context is considered in-use if it contains an RRS unit of recovery
with one or more interests. The timeout is specified by a positive integer
followed 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.
Default value: 15s
Required: false
Data type: string
resourceManagerNamePrefix
Description: The resource manager prefix to be used as part of the server
generated resource manager name that is registered with Resource
Recovery Services (RRS). The prefix must contain 1 to 8 alphanumeric
(A-Z,a-z,0-9) and national (@,#,$) character only. The prefix name of
DEFAULT is a reserved prefix name that identifies a default server
configuration and should not be used for securing server access.
Default value: DEFAULT
Required: false
Data type: string
netscapeLdapFilterProperties
Specifies the list of default Netscape Directory Server LDAP filters. PID is
com.ibm.ws.security.registry.ldap.internal.filters.netscape.
Attributes
userFilter
users.
Default value: (&(uid=%v)(objectclass=inetOrgPerson))
Required: true
Data type: string
groupFilter
groups.
Default value:
(objectclass=groupOfUniqueNames)))
Required: true
Data type: string
userIdMap
entry.
Default value: inetOrgPerson:uid
Required: true
Data type: string
groupIdMap
entry.
Default value: *:cn
Required: true
Data type: string
groupMemberIdMap
Default value:
Required: true
Data type: string
oauthProvider
OAuth provider definition. PID is com.ibm.ws.security.oauth20.provider.
Attributes
localStoreRef
Required: false
Data type: Configuration ID of type localStore (string).
databaseStoreRef
Required: false
Data type: Configuration ID of type databaseStore (string).
authorizationGrantLifetime
Description: Authorization grant lifetime (seconds). The equivalent
oauth20.max.authorization.grant.lifetime.seconds. Specify a positive
or seconds (s). For example, specify 30 seconds as 30s. You can include
seconds.
Required: false
Data type: string
authorizationCodeLifetime
Description: Authorization code lifetime (seconds). The equivalent
oauth20.code.lifetime.seconds. Specify a positive integer followed by a
Default value: 60
Required: false
Data type: string
authorizationCodeLength
Description: Length of the generated authorization code. The equivalent
oauth20.code.length.
Default value: 30
Required: false
Data type: long
accessTokenLifetime
Description: Time that access token is valid (seconds). The equivalent
oauth20.token.lifetime.seconds. Specify a positive integer followed by a
Default value: 3600
Required: false
Data type: string
accessTokenLength
Description: Length of the generated OAuth access token. The equivalent
oauth20.access.token.length.
Default value: 40
Required: false
Data type: long
issueRefreshToken
Description: A value of false disables generation and the use of refresh
tokens. The equivalent provider parameter in the full application server
profile is oauth20.issue.refresh.token.
Default value: true
Required: false
Data type: boolean
refreshTokenLength
Description: Length of generated refresh token. The equivalent provider
parameter in the full application server profile is
oauth20.refresh.token.length.
Default value: 50
Required: false
Data type: long
libraryRef
Description: Reference to shared library containing mediator plugin class.
Required: false
allowPublicClients
Description: A value of false disables the access of public clients as
detailed in the OAuth specification. The equivalent provider parameter in
the full application server profile is oauth20.allow.public.clients.
Required: false
Data type: boolean
authorizationFormTemplate
Description: URL of a custom authorization page template. The
equivalent provider parameter in the full application server profile is
oauth20.authorization.form.template.
Default value: template.html
Required: false
Data type: string
authorizationErrorTemplate
Description: URL of a custom authorization error page template. The
oauth20.authorization.error.template.
Default value:
Required: false
Data type: string
customLoginURL
Description: URL of a custom login page. The equivalent provider
oauth20.authorization.loginURL.
Default value: login.jsp
Required: false
Data type: string
autoAuthorizeParam
Description: To use auto authorization, append the autoAuthorize
parameter to requests with a value of true. The equivalent provider
oauth20.autoauthorize.param.
Default value: autoauthz
Required: false
Data type: string
clientURISubstitutions
Description: Optional value to replace client URI strings for dynamic
hostnames. The equivalent provider parameter in the full application
server profile is oauth20.client.uri.substitutions.
Required: false
Data type: string
clientTokenCacheSize
Description: Maximum number of entries in the client token cache. The
oauth20.token.userClientTokenLimit.
Default value: 100
Required: false
Data type: long
filter
Description: URI filter selects requests to be authorized by this provider.
The equivalent provider parameter in the full application server profile is
Filter.
Required: false
Data type: string
characterEncoding
Description: characterEncoding.desc
Required: false
Data type: string
oauthOnly
Description: If the value is false, fall back to available authentication for
requests 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
includeTokenInSubject
Description: If the value is true, add the
com.ibm.wsspi.security.oauth20.token.WSOAuth20Token as a private
credential. The equivalent provider parameter in the full application
server profile is includeToken.
Default value: true
Required: false
Data type: boolean
Sub-elements
localStore
Required: false
Data type: Element of type localStore.
databaseStore
Required: false
Data type: Element of type databaseStore.
library
Description: Reference to shared library containing mediator plugin class.
Required: false
mediatorClassname
Description: Mediator plugin class name. The equivalent provider
oauth20.mediator.classnames.
Required: false
Data type: string
grantType
Description: An access token grant type (as detailed in the OAuth
specification) that is allowed for the provider. The equivalent provider
oauth20.grant.types.allowed.
Required: false
Data type: string
autoAuthorizeClient
Description: Name of a client that is allowed to use auto authorization.
The equivalent provider parameter in the full application server profile is
oauth20.autoauthorize.clients.
Required: false
Data type: string
oauthRoles
OAuth web application security role map. PID is
com.ibm.ws.security.oauth20.roles.
Attributes
authenticatedRef
Required: false
Data type: List of configuration IDs of type authenticated
clientManagerRef
Required: false
Data type: List of configuration IDs of type clientManager
Sub-elements
authenticated
Required: false
Data type: Element of type authenticated.
clientManager
Required: false
Data type: Element of type clientManager.
permission
The permission for the destination. PID is
com.ibm.ws.messaging.security.permission.
Attributes
name
Description: The name of the destination for which the permission is
defined.
Required: true
Data type: string
actions
Description: The actions that are allowed for this permission (the allowed
actions are SEND, RECEIVE, CREATE, and BROWSE).
Required: true
Data type: string
pluginConfiguration
Generate plugin configuration. PID is com.ibm.ws.generatePluginConfig.
Attributes
pluginInstallRoot
Description: Web container plugin installation position in file system
Default value: .
Required: false
Data type: string
webserverPort
Description: Web server HTTP port
Default value: 80
Required: false
Data type: string
webserverSecurePort
Description: Web server HTTPS port
Default value: 443
Required: false
Data type: string
sslKeyringLocation
Description: Location of SSL keyring
Default value: PATH/FILE
Required: false
Data type: string
sslStashfileLocation
Description: Location of SSL stashfile
Default value: PATH/FILE
Required: false
Data type: string
sslCertlabel
Description: SSL cert label
Default value: REPLACE
Required: false
Data type: string
ipv6Preferred
Description: IPv6 is preferred
Required: false
Data type: boolean
properties
List of JDBC vendor properties for the data source. For example,
databaseName="dbname" serverName="localhost" portNumber="50000". PID is
com.ibm.ws.jdbc.dataSource.properties, and it is the child of complex type
dataSource.
Attributes
databaseName
Description: JDBC driver property: databaseName.
Required: false
Data type: string
serverName
Description: Server where the database is running.
Required: false
Data type: string
portNumber
Description: Port on which to obtain database connections.
Required: false
Data type: int
URL
Description: URL for connecting to the database.
Required: false
Data type: string
user
Required: false
Data type: string
password
Required: false
properties.datadirect.sqlserver
Data source properties for the DataDirect Connect for JDBC driver for Microsoft
SQL Server. PID is com.ibm.ws.jdbc.dataSource.properties.datadirect.sqlserver, and
it is the child of complex type dataSource.
Attributes
databaseName
Required: false
Data type: string
serverName
Required: false
Data type: string
portNumber
Default value: 1433
Required: false
Data type: int
user
Required: false
Data type: string
password
Required: false
accountingInfo
Description: JDBC driver property: accountingInfo.
Required: false
Data type: string
alternateServers
Description: JDBC driver property: alternateServers.
Required: false
Data type: string
alwaysReportTriggerResults
Description: JDBC driver property: alwaysReportTriggerResults.
Required: false
Data type: boolean
applicationName
Description: JDBC driver property: applicationName.
Required: false
Data type: string
authenticationMethod
Description: JDBC driver property: authenticationMethod.
Range:
auto
kerberos
ntlm
userIdPassword
Required: false
Data type: string
bulkLoadBatchSize
Description: JDBC driver property: bulkLoadBatchSize.
Required: false
Data type: long
bulkLoadOptions
Description: JDBC driver property: bulkLoadOptions.
Required: false
Data type: long
clientHostName
Description: JDBC driver property: clientHostName.
Required: false
Data type: string
clientUser
Description: JDBC driver property: clientUser.
Required: false
Data type: string
codePageOverride
Description: JDBC driver property: codePageOverride.
Required: false
Data type: string
connectionRetryCount
Description: JDBC driver property: connectionRetryCount.
Required: false
Data type: int
connectionRetryDelay
Description: JDBC driver property: connectionRetryDelay. Specify a
Required: false
Data type: string
convertNull
Description: JDBC driver property: convertNull.
Required: false
Data type: int
dateTimeInputParameterType
Description: JDBC driver property: dateTimeInputParameterType.
Range:
auto
dateTime
dateTimeOffset
Required: false
Data type: string
dateTimeOutputParameterType
Description: JDBC driver property: dateTimeOutputParameterType.
Range:
auto
dateTime
dateTimeOffset
Required: false
Data type: string
describeInputParameters
Description: JDBC driver property: describeInputParameters.
Range:
describeAll
describeIfDateTime
describeIfString
noDescribe
Required: false
Data type: string
describeOutputParameters
Description: 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
enableCancelTimeout
Description: JDBC driver property: enableCancelTimeout.
Required: false
Data type: boolean
encryptionMethod
Description: JDBC driver property: encryptionMethod.
Range:
noEncryption
loginSSL
requestSSL
SSL
Required: false
Data type: string
failoverGranularity
Description: JDBC driver property: failoverGranularity.
Range:
atomic
atomicWithRepositioning
disableIntegrityCheck
nonAtomic
Required: false
Data type: string
failoverMode
Description: JDBC driver property: failoverMode.
Range:
connect
extended
select
Required: false
Data type: string
failoverPreconnect
Description: JDBC driver property: failoverPreconnect.
Required: false
Data type: boolean
hostNameInCertificate
Description: JDBC driver property: hostNameInCertificate.
Required: false
Data type: string
initializationString
Description: JDBC driver property: initializationString.
Required: false
Data type: string
insensitiveResultSetBufferSize
Description: JDBC driver property: insensitiveResultSetBufferSize.
Required: false
Data type: int
javaDoubleToString
Description: JDBC driver property: javaDoubleToString.
Required: false
Data type: boolean
JDBCBehavior
Description: JDBC driver property: JDBCBehavior. Values are: 0 (JDBC
4.0) or 1 (JDBC 3.0).
Default value: 0
Range:
0 JDBC 4.0
1 JDBC 3.0
Required: false
Data type: int
loadBalancing
Description: JDBC driver property: loadBalancing.
Required: false
Data type: boolean
loginTimeout
Description: JDBC driver property: loginTimeout. Specify a positive
seconds.
Required: false
Data type: string
longDataCacheSize
Description: JDBC driver property: longDataCacheSize.
Required: false
Data type: int
netAddress
Description: JDBC driver property: netAddress.
Required: false
Data type: string
packetSize
Description: JDBC driver property: packetSize.
Required: false
Data type: int
queryTimeout
Description: JDBC driver property: queryTimeout. Specify a positive
seconds.
Required: false
Data type: string
resultsetMetaDataOptions
Description: JDBC driver property: resultsetMetaDataOptions.
Required: false
Data type: int
selectMethod
Description: JDBC driver property: selectMethod.
Range:
cursor
direct
Required: false
Data type: string
snapshotSerializable
Description: JDBC driver property: snapshotSerializable.
Required: false
Data type: boolean
spyAttributes
Description: JDBC driver property: spyAttributes.
Required: false
Data type: string
stringInputParameterType
Description: 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
suppressConnectionWarnings
Description: JDBC driver property: suppressConnectionWarnings.
Required: false
Data type: boolean
transactionMode
Description: JDBC driver property: transactionMode.
Range:
explicit
implicit
Required: false
Data type: string
truncateFractionalSeconds
Description: JDBC driver property: truncateFractionalSeconds.
Required: false
Data type: boolean
trustStore
Description: JDBC driver property: trustStore.
Required: false
Data type: string
trustStorePassword
Description: JDBC driver property: trustStorePassword.
Required: false
useServerSideUpdatableCursors
Description: JDBC driver property: useServerSideUpdatableCursors.
Required: false
Data type: boolean
validateServerCertificate
Description: JDBC driver property: validateServerCertificate.
Required: false
Data type: boolean
XATransactionGroup
Description: JDBC driver property: XATransactionGroup.
Required: false
Data type: string
XMLDescribeType
Description: JDBC driver property: XMLDescribeType.
Range:
longvarbinary
longvarchar
Required: false
Data type: string
properties.db2.i.native
Data source properties for the IBM DB2 for i Native JDBC driver. PID is
com.ibm.ws.jdbc.dataSource.properties.db2.i.native, and it is the child of complex
type dataSource.
Attributes
databaseName
Default value: *LOCAL
Required: false
Data type: string
user
Required: false
Data type: string
password
Required: false
access
Description: JDBC driver property: access.
Default value: all
Range:
all
read call
read only
Required: false
Data type: string
autoCommit
Description: JDBC driver property: autoCommit.
Default value: true
Required: false
Data type: boolean
batchStyle
Description: JDBC driver property: batchStyle.
Default value: 2.0
Range:
2.0
2.1
Required: false
Data type: string
behaviorOverride
Description: JDBC driver property: behaviorOverride.
Required: false
Data type: int
blockSize
Description: JDBC driver property: blockSize.
Default value: 32
Range:
0
8
16
32
64
128
256
512
Required: false
Data type: int
cursorHold
Description: JDBC driver property: cursorHold.
Required: false
Data type: boolean
cursorSensitivity
Description: 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
dataTruncation
Description: JDBC driver property: dataTruncation.
Default value: true
Required: false
Data type: string
dateFormat
Description: JDBC driver property: dateFormat.
Range:
dmy
eur
mdy
iso
jis
julian
usa
ymd
Required: false
Data type: string
dateSeparator
Description: 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
decimalSeparator
Description: JDBC driver property: decimalSeparator.
Range:
Required: false
Data type: string
directMap
Description: JDBC driver property: directMap.
Default value: true
Required: false
Data type: boolean
doEscapeProcessing
Description: JDBC driver property: doEscapeProcessing.
Default value: true
Required: false
Data type: boolean
fullErrors
Description: JDBC driver property: fullErrors.
Required: false
Data type: boolean
libraries
Description: JDBC driver property: libraries.
Required: false
Data type: string
lobThreshold
Description: JDBC driver property: lobThreshold.
Default value: 0
Required: false
Data type: int
lockTimeout
Description: JDBC driver property: lockTimeout. Specify a positive
seconds.
Default value: 0
Required: false
Data type: string
loginTimeout
seconds.
Required: false
Data type: string
maximumPrecision
Description: JDBC driver property: maximumPrecision.
Default value: 31
Range:
31
63
Required: false
Data type: int
maximumScale
Description: 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
networkProtocol
Description: JDBC driver property: networkProtocol.
Required: false
Data type: int
portNumber
Required: false
Data type: int
prefetch
Description: JDBC driver property: prefetch.
Default value: true
Required: false
Data type: boolean
queryOptimizeGoal
Description: JDBC driver property: queryOptimizeGoal. Values are: 1
(*FIRSTIO) or 2 (*ALLIO).
Default value: 2
Range:
1 *FIRSTIO
2 *ALLIO
Required: false
Data type: string
reuseObjects
Description: JDBC driver property: reuseObjects.
Default value: true
Required: false
Data type: boolean
serverName
Required: false
Data type: string
serverTraceCategories
Description: JDBC driver property: serverTraceCategories.
Default value: 0
Required: false
Data type: int
systemNaming
Description: JDBC driver property: systemNaming.
Required: false
Data type: boolean
timeFormat
Description: JDBC driver property: timeFormat.
Range:
eur
hms
iso
jis
usa
Required: false
Data type: string
timeSeparator
Description: JDBC driver property: timeSeparator.
Range:
: The colon character (:).
b The character b
Required: false
Data type: string
trace
Description: JDBC driver property: trace.
Required: false
Data type: boolean
transactionTimeout
Description: JDBC driver property: transactionTimeout. Specify a positive
seconds.
Default value: 0
Required: false
Data type: string
translateBinary
Description: JDBC driver property: translateBinary.
Required: false
Data type: boolean
translateHex
Description: JDBC driver property: translateHex.
Default value: character
Range:
binary
character
Required: false
Data type: string
useBlockInsert
Description: JDBC driver property: useBlockInsert.
Required: false
Data type: boolean
properties.db2.i.toolbox
Data source properties for the IBM DB2 for i Toolbox JDBC driver. PID is
com.ibm.ws.jdbc.dataSource.properties.db2.i.toolbox, and it is the child of complex
type dataSource.
Attributes
serverName
Required: true
Data type: string
databaseName
Required: false
Data type: string
user
Required: false
Data type: string
password
Required: false
access
Description: JDBC driver property: access.
Default value: all
Range:
all
read call
read only
Required: false
Data type: string
behaviorOverride
Description: JDBC driver property: behaviorOverride.
Required: false
Data type: int
bidiImplicitReordering
Description: JDBC driver property: bidiImplicitReordering.
Default value: true
Required: false
Data type: boolean
bidiNumericOrdering
Description: JDBC driver property: bidiNumericOrdering.
Required: false
Data type: boolean
bidiStringType
Description: JDBC driver property: bidiStringType.
Required: false
Data type: int
bigDecimal
Description: JDBC driver property: bigDecimal.
Default value: true
Required: false
Data type: boolean
blockCriteria
Description: JDBC driver property: blockCriteria. Values are: 0 (no record
blocking), 1 (block if FOR FETCH ONLY is specified), 2 (block if FOR
UPDATE is specified).
Default value: 2
Range:
0
1
2
Required: false
Data type: int
blockSize
Description: JDBC driver property: blockSize.
Default value: 32
Range:
0
8
16
32
64
128
256
512
Required: false
Data type: int
cursorHold
Description: JDBC driver property: cursorHold.
Required: false
Data type: boolean
cursorSensitivity
Default value: asensitive
Range:
asensitive
insensitive
sensitive
Required: false
Data type: string
dataCompression
Description: JDBC driver property: dataCompression.
Default value: true
Required: false
Data type: boolean
dataTruncation
Description: JDBC driver property: dataTruncation.
Default value: true
Required: false
Data type: boolean
dateFormat
Description: JDBC driver property: dateFormat.
Range:
dmy
eur
mdy
iso
jis
julian
usa
ymd
Required: false
Data type: string
dateSeparator
Description: JDBC driver property: dateSeparator.
Range:
/ The forward slash character (/).
- The dash character (-).
The space character ( ).
Required: false
Data type: string
decimalSeparator
Description: JDBC driver property: decimalSeparator.
Range:
Required: false
Data type: string
driver
Description: JDBC driver property: driver.
Default value: toolbox
Range:
native
toolbox
Required: false
Data type: string
errors
Description: JDBC driver property: errors.
Default value: basic
Range:
basic
full
Required: false
Data type: string
extendedDynamic
Description: JDBC driver property: extendedDynamic.
Required: false
Data type: boolean
extendedMetaData
Description: JDBC driver property: extendedMetaData.
Required: false
Data type: boolean
fullOpen
Description: JDBC driver property: fullOpen.
Required: false
Data type: boolean
holdInputLocators
Description: JDBC driver property: holdInputLocators.
Default value: true
Required: false
Data type: boolean
holdStatements
Description: JDBC driver property: holdStatements.
Required: false
Data type: boolean
isolationLevelSwitchingSupport
Description: JDBC driver property: isolationLevelSwitchingSupport.
Required: false
Data type: boolean
keepAlive
Description: JDBC driver property: keepAlive.
Required: false
Data type: boolean
lazyClose
Description: JDBC driver property: lazyClose.
Required: false
Data type: boolean
libraries
Description: JDBC driver property: libraries.
Required: false
Data type: string
lobThreshold
Description: JDBC driver property: lobThreshold.
Default value: 0
Required: false
Data type: int
loginTimeout
seconds.
Required: false
Data type: string
maximumPrecision
Description: JDBC driver property: maximumPrecision.
Default value: 31
Range:
31
63 64
Required: false
Data type: int
maximumScale
Description: JDBC driver property: maximumScale.
Default value: 31
Required: false
Data type: int
metaDataSource
Description: JDBC driver property: metaDataSource.
Default value: 1
Required: false
Data type: int
minimumDivideScale
Description: JDBC driver property: minimumDivideScale.
Default value: 0
Required: false
Data type: int
naming
Description: JDBC driver property: naming.
Default value: sql
Range:
sql
system
Required: false
Data type: string
package
Description: JDBC driver property: package.
Required: false
Data type: string
packageAdd
Description: JDBC driver property: packageAdd.
Default value: true
Required: false
Data type: boolean
packageCCSID
Description: 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
packageCache
Description: JDBC driver property: packageCache.
Required: false
Data type: boolean
packageCriteria
Description: JDBC driver property: packageCriteria.
Default value: default
Range:
default
select
Required: false
Data type: string
packageError
Description: JDBC driver property: packageError.
Default value: warning
Range:
exception
warning
none
Required: false
Data type: string
packageLibrary
Description: JDBC driver property: packageLibrary.
Default value: QGPL
Required: false
Data type: string
prefetch
Description: JDBC driver property: prefetch.
Default value: true
Required: false
Data type: boolean
prompt
Description: JDBC driver property: prompt.
Required: false
Data type: boolean
proxyServer
Description: JDBC driver property: proxyServer.
Required: false
Data type: string
qaqqiniLibrary
Description: JDBC driver property: qaqqiniLibrary.
Required: false
Data type: string
queryOptimizeGoal
Description: JDBC driver property: queryOptimizeGoal. Values are: 1
(*FIRSTIO) or 2 (*ALLIO).
Default value: 0
Required: false
Data type: int
receiveBufferSize
Description: JDBC driver property: receiveBufferSize.
Required: false
Data type: int
remarks
Description: JDBC driver property: remarks.
Default value: system
Range:
sql
system
Required: false
Data type: string
rollbackCursorHold
Description: JDBC driver property: rollbackCursorHold.
Required: false
Data type: boolean
savePasswordWhenSerialized
Description: JDBC driver property: savePasswordWhenSerialized.
Required: false
Data type: boolean
secondaryUrl
Description: JDBC driver property: secondaryUrl.
Required: false
Data type: string
secure
Description: JDBC driver property: secure.
Required: false
Data type: boolean
sendBufferSize
Description: JDBC driver property: sendBufferSize.
Required: false
Data type: int
serverTraceCategories
Description: JDBC driver property: serverTraceCategories.
Default value: 0
Required: false
Data type: int
soLinger
Description: JDBC driver property: soLinger. Specify a positive integer
seconds.
Required: false
Data type: string
soTimeout
Description: JDBC driver property: soTimeout. Specify a positive integer
Required: false
Data type: string
sort
Description: JDBC driver property: sort.
Default value: hex
Range:
hex
language
table
Required: false
Data type: string
sortLanguage
Description: JDBC driver property: sortLanguage.
Required: false
Data type: string
sortTable
Description: JDBC driver property: sortTable.
Required: false
Data type: string
sortWeight
Description: JDBC driver property: sortWeight.
Range:
shared
unqiue
unique
Required: false
Data type: string
tcpNoDelay
Description: JDBC driver property: tcpNoDelay.
Required: false
Data type: boolean
threadUsed
Description: JDBC driver property: threadUsed.
Default value: true
Required: false
Data type: boolean
timeFormat
Description: JDBC driver property: timeFormat.
Range:
eur
hms
iso
jis
usa
Required: false
Data type: string
timeSeparator
Description: JDBC driver property: timeSeparator.
Range:
: The colon character (:).
The space character ( ).
Required: false
Data type: string
toolboxTrace
Description: JDBC driver property: toolboxTrace.
Range:
none
datastream
diagnostic
error
information
warning
conversion
proxy
pcml
jdbc
all
thread
Required: false
Data type: string
trace
Description: JDBC driver property: trace.
Required: false
Data type: boolean
translateBinary
Description: JDBC driver property: translateBinary.
Required: false
Data type: boolean
translateBoolean
Description: JDBC driver property: translateBoolean.
Default value: true
Required: false
Data type: boolean
translateHex
Description: JDBC driver property: translateHex.
Default value: character
Range:
binary
character
Required: false
Data type: string
trueAutoCommit
Description: JDBC driver property: trueAutoCommit.
Required: false
Data type: boolean
xaLooselyCoupledSupport
Description: JDBC driver property: xaLooselyCoupledSupport.
Default value: 0
Required: false
Data type: int
properties.db2.jcc
Data 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 complex
type dataSource.
Attributes
driverType
Description: JDBC driver property: driverType.
Default value: 4
Range:
2 Type 2 JDBC driver.
4 Type 4 JDBC driver.
Required: false
Data type: int
databaseName
Required: false
Data type: string
serverName
Required: false
Data type: string
portNumber
Required: false
Data type: int
user
Required: false
Data type: string
password
Required: false
activateDatabase
Description: JDBC driver property: activateDatabase.
Required: false
Data type: int
alternateGroupDatabaseName
Description: JDBC driver property: alternateGroupDatabaseName.
Required: false
Data type: string
alternateGroupPortNumber
Description: JDBC driver property: alternateGroupPortNumber.
Required: false
Data type: string
alternateGroupServerName
Description: JDBC driver property: alternateGroupServerName.
Required: false
Data type: string
blockingReadConnectionTimeout
Description: JDBC driver property: blockingReadConnectionTimeout.
Required: false
Data type: string
clientAccountingInformation
Description: JDBC driver property: clientAccountingInformation.
Required: false
Data type: string
clientApplicationInformation
Description: JDBC driver property: clientApplicationInformation.
Required: false
Data type: string
clientRerouteServerListJNDIName
Description: JDBC driver property: clientRerouteServerListJNDIName.
Required: false
Data type: string
clientUser
Description: JDBC driver property: clientUser.
Required: false
Data type: string
clientWorkstation
Description: JDBC driver property: clientWorkstation.
Required: false
Data type: string
connectionCloseWithInFlightTransaction
Description: JDBC driver property:
connectionCloseWithInFlightTransaction.
Range:
1 CONNECTION_CLOSE_WITH_EXCEPTION
2 CONNECTION_CLOSE_WITH_ROLLBACK
Required: false
Data type: int
currentAlternateGroupEntry
Description: JDBC driver property: currentAlternateGroupEntry.
Required: false
Data type: int
currentFunctionPath
Description: JDBC driver property: currentFunctionPath.
Required: false
Data type: string
currentLocaleLcCtype
Description: JDBC driver property: currentLocaleLcCtype.
Required: false
Data type: string
currentLockTimeout
Description: JDBC driver property: currentLockTimeout. Specify a
Required: false
Data type: string
currentPackagePath
Description: JDBC driver property: currentPackagePath.
Required: false
Data type: string
currentPackageSet
Description: JDBC driver property: currentPackageSet.
Required: false
Data type: string
currentSQLID
Description: JDBC driver property: currentSQLID.
Required: false
Data type: string
currentSchema
Description: JDBC driver property: currentSchema.
Required: false
Data type: string
cursorSensitivity
Range:
0 TYPE_SCROLL_SENSITIVE_STATIC
1 TYPE_SCROLL_SENSITIVE_DYNAMIC
2 TYPE_SCROLL_ASENSITIVE
Required: false
Data type: int
deferPrepares
Description: JDBC driver property: deferPrepares.
Default value: true
Required: false
Data type: boolean
enableAlternateGroupSeamlessACR
Description: JDBC driver property: enableAlternateGroupSeamlessACR.
Required: false
Data type: boolean
enableClientAffinitiesList
Description: JDBC driver property: enableClientAffinitiesList. Values are:
1 (YES) or 2 (NO).
Range:
1 YES
2 NO
Required: false
Data type: int
enableExtendedDescribe
Description: JDBC driver property: enableExtendedDescribe.
Range:
1 YES
2 NO
Required: false
Data type: int
enableExtendedIndicators
Description: JDBC driver property: enableExtendedIndicators.
Range:
1 YES
2 NO
Required: false
Data type: int
enableNamedParameterMarkers
Description: JDBC driver property: enableNamedParameterMarkers.
Values are: 1 (YES) or 2 (NO).
Range:
1 YES
2 NO
Required: false
Data type: int
enableSeamlessFailover
Description: JDBC driver property: enableSeamlessFailover. Values are: 1
(YES) or 2 (NO).
Range:
1 YES
2 NO
Required: false
Data type: int
enableSysplexWLB
Description: JDBC driver property: enableSysplexWLB.
Required: false
Data type: boolean
fetchSize
Description: JDBC driver property: fetchSize.
Required: false
Data type: int
fullyMaterializeInputStreams
Description: JDBC driver property: fullyMaterializeInputStreams.
Required: false
Data type: boolean
fullyMaterializeInputStreamsOnBatchExecution Description: JDBC driver property:
fullyMaterializeInputStreamsOnBatchExecution.
Range:
1 YES
2 NO
Required: false
Data type: int
fullyMaterializeLobData
Description: JDBC driver property: fullyMaterializeLobData.
Required: false
Data type: boolean
implicitRollbackOption
Description: 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
interruptProcessingMode
Description: 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
keepAliveTimeOut
Description: JDBC driver property: keepAliveTimeOut. Specify a positive
seconds.
Required: false
Data type: string
keepDynamic
Description: JDBC driver property: keepDynamic.
Required: false
Data type: int
kerberosServerPrincipal
Description: JDBC driver property: kerberosServerPrincipal.
Required: false
Data type: string
loginTimeout
seconds.
Required: false
Data type: string
maxConnCachedParamBufferSize
Description: JDBC driver property: maxConnCachedParamBufferSize.
Required: false
Data type: int
maxRetriesForClientReroute
Description: JDBC driver property: maxRetriesForClientReroute.
Required: false
Data type: int
profileName
Description: JDBC driver property: profileName.
Required: false
Data type: string
queryCloseImplicit
Description: 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
queryDataSize
Description: JDBC driver property: queryDataSize.
Required: false
Data type: int
queryTimeoutInterruptProcessingMode
queryTimeoutInterruptProcessingMode.
Range:
1 INTERRUPT_PROCESSING_MODE_STATEMENT_CANCEL
2 INTERRUPT_PROCESSING_MODE_CLOSE_SOCKET
Required: false
Data type: int
readOnly
Description: JDBC driver property: readOnly.
Required: false
Data type: boolean
recordTemporalHistory
Description: recordTemporalHistory.desc
Range:
1 YES
2 NO
Required: false
Data type: int
resultSetHoldability
Description: 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
resultSetHoldabilityForCatalogQueries
resultSetHoldabilityForCatalogQueries. Values are: 1
Range:
Required: false
Data type: int
retrieveMessagesFromServerOnGetMessage
retrieveMessagesFromServerOnGetMessage.
Default value: true
Required: false
Data type: boolean
retryIntervalForClientReroute
Description: JDBC driver property: retryIntervalForClientReroute. Specify
Required: false
Data type: string
securityMechanism
Description: 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
sendDataAsIs
Description: JDBC driver property: sendDataAsIs.
Required: false
Data type: boolean
sessionTimeZone
Description: JDBC driver property: sessionTimeZone.
Required: false
Data type: string
sqljCloseStmtsWithOpenResultSet
Description: JDBC driver property: sqljCloseStmtsWithOpenResultSet.
Required: false
Data type: boolean
sqljEnableClassLoaderSpecificProfiles
Description: JDBC driver property: sqljEnableClassLoaderSpecificProfiles.
Required: false
Data type: boolean
sslConnection
Description: JDBC driver property: sslConnection.
Required: false
Data type: boolean
streamBufferSize
Description: JDBC driver property: streamBufferSize.
Required: false
Data type: int
stripTrailingZerosForDecimalNumbers
stripTrailingZerosForDecimalNumbers.
Range:
1 YES
2 NO
Required: false
Data type: int
sysSchema
Description: JDBC driver property: sysSchema.
Required: false
Data type: string
timerLevelForQueryTimeOut
Description: JDBC driver property: timerLevelForQueryTimeOut.
Range:
-1 QUERYTIMEOUT_DISABLED
1 QUERYTIMEOUT_STATEMENT_LEVEL
2 QUERYTIMEOUT_CONNECTION_LEVEL
Required: false
Data type: int
traceDirectory
Description: JDBC driver property: traceDirectory.
Required: false
Data type: string
traceFile
Description: JDBC driver property: traceFile.
Required: false
Data type: string
traceFileAppend
Description: JDBC driver property: traceFileAppend.
Required: false
Data type: boolean
traceFileCount
Description: JDBC driver property: traceFileCount.
Required: false
Data type: int
traceFileSize
Description: JDBC driver property: traceFileSize.
Required: false
Data type: int
traceLevel
Description: 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
traceOption
Description: JDBC driver property: traceOption
Range:
0
1
Required: false
Data type: int
translateForBitData
Description: JDBC driver property: translateForBitData.
Range:
1 HEX_REPRESENTATION
2 SERVER_ENCODING_REPRESENTATION
Required: false
Data type: int
updateCountForBatch
Description: JDBC driver property: updateCountForBatch.
Range:
1 NO_UPDATE_COUNT
2 TOTAL_UPDATE_COUNT
Required: false
Data type: int
useCachedCursor
Description: JDBC driver property: useCachedCursor.
Required: false
Data type: boolean
useIdentityValLocalForAutoGeneratedKeys
useIdentityValLocalForAutoGeneratedKeys.
Required: false
Data type: boolean
useJDBC4ColumnNameAndLabelSemantics
useJDBC4ColumnNameAndLabelSemantics. Values are: 1 (YES) or 2
(NO).
Range:
1 YES
2 NO
Required: false
Data type: int
useJDBC41DefinitionForGetColumns
Description: JDBC driver property: useJDBC41DefinitionForGetColumns.
Range:
1 YES
2 NO
Required: false
Data type: int
useTransactionRedirect
Description: JDBC driver property: useTransactionRedirect.
Required: false
Data type: boolean
xaNetworkOptimization
Description: JDBC driver property: xaNetworkOptimization.
Required: false
Data type: boolean
properties.derby.client
Data source properties for Derby Network Client JDBC driver. PID is
com.ibm.ws.jdbc.dataSource.properties.derby.client, and it is the child of complex
type dataSource.
Attributes
createDatabase
Description: JDBC driver property: createDatabase.
Range:
create When the first connection is established, automatically create the
database if it doesn't exist.
false Do not automatically create the database.
Required: false
Data type: string
databaseName
Required: false
Data type: string
serverName
Required: false
Data type: string
portNumber
Default value: 1527
Required: false
Data type: int
user
Required: false
Data type: string
password
Required: false
connectionAttributes
Description: JDBC driver property: connectionAttributes.
Required: false
Data type: string
loginTimeout
seconds.
Required: false
Data type: string
retrieveMessageText
Description: JDBC driver property: retrieveMessageText.
Default value: true
Required: false
Data type: boolean
securityMechanism
(STRONG_PASSWORD_SUBSTITUTE_SECURITY), 9
(ENCRYPTED_USER_AND_PASSWORD_SECURITY).
Default value: 3
Range:
8 STRONG_PASSWORD_SUBSTITUTE_SECURITY
Required: false
Data type: short
shutdownDatabase
Description: JDBC driver property: shutdownDatabase.
Range:
shutdown
Shut down the database when a connection is attempted.
false Do not shut down the database.
Required: false
Data type: string
ssl
Description: JDBC driver property: ssl.
Range:
basic
peerAuthentication
off
Required: false
Data type: string
traceDirectory
Required: false
Data type: string
traceFile
Required: false
Data type: string
traceFileAppend
Required: false
Data type: boolean
traceLevel
TRACE_XA_CALLS=2048, TRACE_ALL=-1.
Required: false
Data type: int
properties.derby.embedded
Data source properties for Derby Embedded JDBC driver. PID is
com.ibm.ws.jdbc.dataSource.properties.derby.embedded, and it is the child of
complex type dataSource.
Attributes
createDatabase
Description: JDBC driver property: createDatabase.
Range:
create When the first connection is established, automatically create the
database if it doesn't exist.
false Do not automatically create the database.
Required: false
Data type: string
databaseName
Required: false
Data type: string
user
Required: false
Data type: string
password
Required: false
connectionAttributes
Description: JDBC driver property: connectionAttributes.
Required: false
Data type: string
loginTimeout
seconds.
Required: false
Data type: string
shutdownDatabase
Description: JDBC driver property: shutdownDatabase.
Range:
shutdown
Shut down the database when a connection is attempted.
false Do not shut down the database.
Required: false
Data type: string
properties.informix
Data source properties for the Informix
JDBC driver. PID is

com.ibm.ws.jdbc.dataSource.properties.informix, and it is the child of complex type
dataSource.
Attributes
databaseName
Required: false
Data type: string
ifxIFXHOST
Description: JDBC driver property: ifxIFXHOST.
Required: false
Data type: string
serverName
Required: false
Data type: string
portNumber
Default value: 1526
Required: false
Data type: int
user
Required: false
Data type: string
password
Required: false
ifxCLIENT_LOCALE
Description: JDBC driver property: ifxCLIENT_LOCALE.
Required: false
Data type: string
ifxCPMAgeLimit
Description: JDBC driver property: ifxCPMAgeLimit. Specify a positive
seconds.
Required: false
Data type: string
ifxCPMInitPoolSize
Description: JDBC driver property: ifxCPMInitPoolSize.
Required: false
Data type: int
ifxCPMMaxConnections
Description: JDBC driver property: ifxCPMMaxConnections.
Required: false
Data type: int
ifxCPMMaxPoolSize
Description: JDBC driver property: ifxCPMMaxPoolSize.
Required: false
Data type: int
ifxCPMMinAgeLimit
Description: JDBC driver property: ifxCPMMinAgeLimit. Specify a
Required: false
Data type: string
ifxCPMMinPoolSize
Description: JDBC driver property: ifxCPMMinPoolSize.
Required: false
Data type: int
ifxCPMServiceInterval
Description: JDBC driver property: ifxCPMServiceInterval. Specify a
Required: false
Data type: string
ifxDBANSIWARN
Description: JDBC driver property: ifxDBANSIWARN.
Required: false
Data type: boolean
ifxDBCENTURY
Description: JDBC driver property: ifxDBCENTURY.
Required: false
Data type: string
ifxDBDATE
Description: JDBC driver property: ifxDBDATE.
Required: false
Data type: string
ifxDBSPACETEMP
Description: JDBC driver property: ifxDBSPACETEMP.
Required: false
Data type: string
ifxDBTEMP
Description: JDBC driver property: ifxDBTEMP.
Required: false
Data type: string
ifxDBTIME
Description: JDBC driver property: ifxDBTIME.
Required: false
Data type: string
ifxDBUPSPACE
Description: JDBC driver property: ifxDBUPSPACE.
Required: false
Data type: string
ifxDB_LOCALE
Description: JDBC driver property: ifxDB_LOCALE.
Required: false
Data type: string
ifxDELIMIDENT
Description: JDBC driver property: ifxDELIMIDENT.
Required: false
Data type: boolean
ifxENABLE_TYPE_CACHE
Description: JDBC driver property: ifxENABLE_TYPE_CACHE.
Required: false
Data type: boolean
ifxFET_BUF_SIZE
Description: JDBC driver property: ifxFET_BUF_SIZE.
Required: false
Data type: int
ifxGL_DATE
Description: JDBC driver property: ifxGL_DATE.
Required: false
Data type: string
ifxGL_DATETIME
Description: JDBC driver property: ifxGL_DATETIME.
Required: false
Data type: string
ifxIFX_AUTOFREE
Description: JDBC driver property: ifxIFX_AUTOFREE.
Required: false
Data type: boolean
ifxIFX_DIRECTIVES
Description: JDBC driver property: ifxIFX_DIRECTIVES.
Required: false
Data type: string
ifxIFX_LOCK_MODE_WAIT
Description: JDBC driver property: ifxIFX_LOCK_MODE_WAIT. Specify
Default value: 2s
Required: false
Data type: string
ifxIFX_SOC_TIMEOUT
Description: JDBC driver property: ifxIFX_SOC_TIMEOUT. Specify a
Required: false
Data type: string
ifxIFX_USEPUT
Description: JDBC driver property: ifxIFX_USEPUT.
Required: false
Data type: boolean
ifxIFX_USE_STRENC
Description: JDBC driver property: ifxIFX_USE_STRENC.
Required: false
Data type: boolean
ifxIFX_XASPEC
Description: JDBC driver property: ifxIFX_XASPEC.
Default value: y
Required: false
Data type: string
ifxINFORMIXCONRETRY
Description: JDBC driver property: ifxINFORMIXCONRETRY.
Required: false
Data type: int
ifxINFORMIXCONTIME
Description: JDBC driver property: ifxINFORMIXCONTIME. Specify a
Required: false
Data type: string
ifxINFORMIXOPCACHE
Description: JDBC driver property: ifxINFORMIXOPCACHE.
Required: false
Data type: string
ifxINFORMIXSTACKSIZE
Description: JDBC driver property: ifxINFORMIXSTACKSIZE.
Required: false
Data type: int
ifxJDBCTEMP
Description: JDBC driver property: ifxJDBCTEMP.
Required: false
Data type: string
ifxLDAP_IFXBASE
Description: JDBC driver property: ifxLDAP_IFXBASE.
Required: false
Data type: string
ifxLDAP_PASSWD
Description: JDBC driver property: ifxLDAP_PASSWD.
Required: false
Data type: string
ifxLDAP_URL
Description: JDBC driver property: ifxLDAP_URL.
Required: false
Data type: string
ifxLDAP_USER
Description: JDBC driver property: ifxLDAP_USER.
Required: false
Data type: string
ifxLOBCACHE
Description: JDBC driver property: ifxLOBCACHE.
Required: false
Data type: int
ifxNEWCODESET
Description: JDBC driver property: ifxNEWCODESET.
Required: false
Data type: string
ifxNEWLOCALE
Description: JDBC driver property: ifxNEWLOCALE.
Required: false
Data type: string
ifxNODEFDAC
Description: JDBC driver property: ifxNODEFDAC.
Required: false
Data type: string
ifxOPTCOMPIND
Description: JDBC driver property: ifxOPTCOMPIND.
Required: false
Data type: string
ifxOPTOFC
Description: JDBC driver property: ifxOPTOFC.
Required: false
Data type: string
ifxOPT_GOAL
Description: JDBC driver property: ifxOPT_GOAL.
Required: false
Data type: string
ifxPATH
Description: JDBC driver property: ifxPATH.
Required: false
Data type: string
ifxPDQPRIORITY
Description: JDBC driver property: ifxPDQPRIORITY.
Required: false
Data type: string
ifxPLCONFIG
Description: JDBC driver property: ifxPLCONFIG.
Required: false
Data type: string
ifxPLOAD_LO_PATH
Description: JDBC driver property: ifxPLOAD_LO_PATH.
Required: false
Data type: string
ifxPROTOCOLTRACE
Description: JDBC driver property: ifxPROTOCOLTRACE.
Required: false
Data type: int
ifxPROTOCOLTRACEFILE
Description: JDBC driver property: ifxPROTOCOLTRACEFILE.
Required: false
Data type: string
ifxPROXY
Description: JDBC driver property: ifxPROXY.
Required: false
Data type: string
ifxPSORT_DBTEMP
Description: JDBC driver property: ifxPSORT_DBTEMP.
Required: false
Data type: string
ifxPSORT_NPROCS
Description: JDBC driver property: ifxPSORT_NPROCS.
Required: false
Data type: boolean
ifxSECURITY
Description: JDBC driver property: ifxSECURITY.
Required: false
Data type: string
ifxSQLH_FILE
Description: JDBC driver property: ifxSQLH_FILE.
Required: false
Data type: string
ifxSQLH_LOC
Description: JDBC driver property: ifxSQLH_LOC.
Required: false
Data type: string
ifxSQLH_TYPE
Description: JDBC driver property: ifxSQLH_TYPE.
Required: false
Data type: string
ifxSSLCONNECTION
Description: JDBC driver property: ifxSSLCONNECTION.
Required: false
Data type: string
ifxSTMT_CACHE
Description: JDBC driver property: ifxSTMT_CACHE.
Required: false
Data type: string
ifxTRACE
Description: JDBC driver property: ifxTRACE.
Required: false
Data type: int
ifxTRACEFILE
Description: JDBC driver property: ifxTRACEFILE.
Required: false
Data type: string
ifxTRUSTED_CONTEXT
Description: JDBC driver property: ifxTRUSTED_CONTEXT.
Required: false
Data type: string
ifxUSEV5SERVER
Description: JDBC driver property: ifxUSEV5SERVER.
Required: false
Data type: boolean
ifxUSE_DTENV
Description: JDBC driver property: ifxUSE_DTENV.
Required: false
Data type: boolean
loginTimeout
seconds.
Required: false
Data type: string
roleName
Description: JDBC driver property: roleName.
Required: false
Data type: string
properties.informix.jcc
Data source properties for the IBM Data Server Driver for JDBC and SQLJ for
Informix. PID is com.ibm.ws.jdbc.dataSource.properties.informix.jcc, and it is the
child of complex type dataSource.
Attributes
databaseName
Required: false
Data type: string
serverName
Required: false
Data type: string
portNumber
Default value: 1526
Required: false
Data type: int
user
Required: false
Data type: string
password
Required: false
currentLockTimeout
Description: JDBC driver property: currentLockTimeout. Specify a
Default value: 2s
Required: false
Data type: string
DBANSIWARN
Description: JDBC driver property: DBANSIWARN.
Required: false
Data type: boolean
DBDATE
Description: JDBC driver property: DBDATE.
Required: false
Data type: string
DBPATH
Description: JDBC driver property: DBPATH.
Required: false
Data type: string
DBSPACETEMP
Description: JDBC driver property: DBSPACETEMP.
Required: false
Data type: string
DBTEMP
Description: JDBC driver property: DBTEMP.
Required: false
Data type: string
DBUPSPACE
Description: JDBC driver property: DBUPSPACE.
Required: false
Data type: string
DELIMIDENT
Description: JDBC driver property: DELIMIDENT.
Required: false
Data type: boolean
deferPrepares
Description: JDBC driver property: deferPrepares.
Required: false
Data type: boolean
driverType
Default value: 4
Required: false
Data type: int
enableNamedParameterMarkers
Description: JDBC driver property: enableNamedParameterMarkers.
Values are: 1 (YES) or 2 (NO).
Required: false
Data type: int
enableSeamlessFailover
Description: JDBC driver property: enableSeamlessFailover. Values are: 1
(YES) or 2 (NO).
Required: false
Data type: int
enableSysplexWLB
Description: JDBC driver property: enableSysplexWLB.
Required: false
Data type: boolean
fetchSize
Description: JDBC driver property: fetchSize.
Required: false
Data type: int
fullyMaterializeLobData
Description: JDBC driver property: fullyMaterializeLobData.
Required: false
Data type: boolean
IFX_DIRECTIVES
Description: JDBC driver property: IFX_DIRECTIVES.
Range:
ON
OFF
Required: false
Data type: string
IFX_EXTDIRECTIVES
Description: JDBC driver property: IFX_EXTDIRECTIVES.
Range:
ON
OFF
Required: false
Data type: string
IFX_UPDDESC
Description: JDBC driver property: IFX_UPDDESC.
Required: false
Data type: string
IFX_XASTDCOMPLIANCE_XAEND
Description: JDBC driver property: IFX_XASTDCOMPLIANCE_XAEND.
Range:
0
1
Required: false
Data type: string
INFORMIXOPCACHE
Description: JDBC driver property: INFORMIXOPCACHE.
Required: false
Data type: string
INFORMIXSTACKSIZE
Description: JDBC driver property: INFORMIXSTACKSIZE.
Required: false
Data type: string
keepDynamic
Description: JDBC driver property: keepDynamic.
Required: false
Data type: int
loginTimeout
seconds.
Required: false
Data type: string
NODEFDAC
Description: JDBC driver property: NODEFDAC.
Range:
yes
no
Required: false
Data type: string
OPTCOMPIND
Description: JDBC driver property: OPTCOMPIND.
Range:
0
1
2
Required: false
Data type: string
OPTOFC
Description: JDBC driver property: OPTOFC.
Range:
0
1
Required: false
Data type: string
PDQPRIORITY
Description: JDBC driver property: PDQPRIORITY.
Range:
HIGH
LOW
OFF
Required: false
Data type: string
progressiveStreaming
Description: JDBC driver property: progressiveStreaming. Values are: 1
(YES) or 2 (NO).
Range:
1 YES
2 NO
Required: false
Data type: int
PSORT_DBTEMP
Description: JDBC driver property: PSORT_DBTEMP.
Required: false
Data type: string
PSORT_NPROCS
Description: JDBC driver property: PSORT_NPROCS.
Required: false
Data type: string
queryDataSize
Description: JDBC driver property: queryDataSize.
Required: false
Data type: int
resultSetHoldability
Description: JDBC driver property: resultSetHoldability. Values are: 1
Range:
Required: false
Data type: int
resultSetHoldabilityForCatalogQueries
resultSetHoldabilityForCatalogQueries. Values are: 1
Range:
Required: false
Data type: int
retrieveMessagesFromServerOnGetMessage
retrieveMessagesFromServerOnGetMessage.
Default value: true
Required: false
Data type: boolean
securityMechanism
(ENCRYPTED_USER_AND_PASSWORD_SECURITY).
Range:
Required: false
Data type: short
STMT_CACHE
Description: JDBC driver property: STMT_CACHE.
Range:
0
1
Required: false
Data type: string
traceDirectory
Required: false
Data type: string
traceFile
Required: false
Data type: string
traceFileAppend
Required: false
Data type: boolean
traceLevel
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
useJDBC4ColumnNameAndLabelSemantics
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 is
the child of complex type activationSpec.
Attributes
destinationType
Description: The type of the destination, which can be either
javax.jms.Queue or javax.jms.Topic
Default value: javax.jms.Queue
Required: true
Data type: string
destinationRef
Description: Reference to a JMS destination
Required: false
Data type: Configuration ID of type jmsQueue (string).
userName
Description: User Name
Default value: CF1USER
Required: false
Data type: string
password
Description: Password
Required: false
Data type: string
readAhead
Description: Read ahead is an optimization that preemptively assigns
messages to consumers. This processes the consumer requests faster
Default value: Default
Range:
Default
AlwaysOn
AlwaysOff
Required: false
Data type: string
connectionName
Description: A comma-separated list of endpoint triplets, with the syntax
hostName: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 not
specified, the default is 7276. If chainName is not specified, the default is
BootstrapBasicMessaging. Refer to the information center for more
information
Required: false
Data type: string
targetTransport
Description: Specify whether the client connects to the messaging engine
through in-process or TCP/IP
Default value: BINDING_THEN_CLIENT
Range:
BINDING
CLIENT
BINDING_THEN_CLIENT
Required: false
Data type: string
Sub-elements
destination
Description: 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 JMS
provider of JMS destinations, for both point-to-point and publish/subscribe
messaging. PID is properties.jms.ConnectionFactory, and it is the child of complex
type jmsConnectionFactory.
Attributes
userName
Required: false
Data type: string
clientID
Description: The JMS client identifier needed for durable topic
subscriptions on all connections created using this connection factory.
This identifier is required if the application is doing durable
publish/subscribe messaging.
Default value: clientId
Required: false
Data type: string
password
Required: false
Data type: string
nonPersistentMapping
Description: The reliability applied to Non-persistent JMS messages sent
using this connection factory.
Default value: ExpressNonPersistent
Range:
Required: false
Data type: string
persistentMapping
Description: The reliability applied to persistent JMS messages sent using
this connection factory.
Default value: ReliablePersistent
Range:
ReliablePersistent
AssuredPersistent
Required: false
Data type: string
readAhead
messages to consumers. This processes the consumer requests faster.
Range:
Default
AlwaysOn
AlwaysOff
Required: false
Data type: string
connectionName
Description: The Connection Name that has triplets separated by a
comma, with the syntax hostName:portNumber:chainName, used to
connect to a bootstrap server. For example,
Merlin:7276:BootstrapBasicMessaging. If hostName is not specified, the
default is localhost. If portNumber is not specified, the default is 7276. If
chainName is not specified, the default is BootstrapBasicMessaging. Refer
to the information center for more information
Required: false
Data type: string
targetTransport
through in-process or TCP/IP.
Range:
BINDING
CLIENT
BINDING_THEN_CLIENT
Required: false
Data type: string
temporaryQueueNamePrefix
Description: The prefix of up to twelve characters used for the temporary
queues 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
queueName
Description: The name of the associated Queue
Default value: Default.Queue
Required: false
Data type: string
deliveryMode
Description: 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
timeToLive
Description: The default time in milliseconds from its dispatch time that
the system must keep the messages live in the destination.
Default value: 0
Required: false
Data type: long
readAhead
Default value: AsConnection
Range:
AsConnection
AlwaysOn
AlwaysOff
Required: false
Data type: string
priority
Description: The relative priority for messages sent to this destination, in
the range 0 to 9, with 0 as the lowest priority and 9 as the highest
priority.
Default value: 1
Required: false
Data type: int
properties.jms.QueueConnectionFactory
A JMS queue connection factory is used to create connections to the associated JMS
provider of JMS queues, for point-to-point messaging. PID is
properties.jms.QueueConnectionFactory, and it is the child of complex type
jmsQueueConnectionFactory.
Attributes
userName
Required: false
Data type: string
clientID
subscriptions on all connections created using this connection factory.
This identifier is required if the application is doing durable
pubish/subscribe
Required: false
Data type: string
password
Required: false
Data type: string
Range:
Required: false
Data type: string
persistentMapping
Range:
ReliablePersistent
AssuredPersistent
Required: false
Data type: string
readAhead
Range:
Default
AlwaysOn
AlwaysOff
Required: false
Data type: string
connectionName
Description: The Connection Name that has triplets, with the syntax
hostName:portNumber:chainName, used to connect to a bootstrap server.
For example Merlin:7276:BootstrapBasicMessaging. If hostName is not
specified, the default is localhost. If portNumber is not specified, the
default is 7276. If chainName is not specified, the default is
BootstrapBasicMessaging. Refer to the information center for more
information.
Required: false
Data type: string
targetTransport
Range:
BINDING
CLIENT
BINDING_THEN_CLIENT
Required: false
Data type: string
Description: The prefix used at the start of temporary topics created by
applications 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 defined
by the Topic space property. PID is properties.jms.Topic, and it is the child of
complex type jmsTopic.
Attributes
topicSpace
Description: A topic space is a location for publish/subscribe messaging.
Default value: Default.Topic.Space
Required: false
Data type: string
topicName
Description: The name of the topic that this JMS topic is assigned to, in
the topic space defined by the Topic space property.
Default value: Default.Topic
Required: false
Data type: string
deliveryMode
Description: 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
timeToLive
Description: The default time in milliseconds from its dispatch time that
the system must keep the messages live in the destination.
Default value: 0
Required: false
Data type: long
readAhead
Default value: AsConnection
Range:
AsConnection
AlwaysOn
AlwaysOff
Required: false
Data type: string
priority
Description: The relative priority for messages sent to this destination, in
the range 0 to 9, with 0 as the lowest priority and 9 as the highest
priority.
Default value: 1
Required: false
Data type: int
properties.jms.TopicConnectionFactory
Topic Connection Factory. PID is properties.jms.TopicConnectionFactory, and it is
the child of complex type jmsTopicConnectionFactory.
Attributes
userName
Required: false
Data type: string
clientID
subscriptions on all connections that are created using this connection
factory.
Required: false
Data type: string
password
Required: false
Data type: string
Range:
Required: false
Data type: string
persistentMapping
Range:
ReliablePersistent
AssuredPersistent
Required: false
Data type: string
readAhead
Range:
Default
AlwaysOn
AlwaysOff
Required: false
Data type: string
connectionName
Description: The Connection Name that has triplets separated by a
comma, with the syntax hostName:portNumber:chainName, used to
connect to a bootstrap server. For example
Merlin:7276:BootstrapBasicMessaging. If hostName is not specified, the
default is localhost. If portNumber is not specified, the default is 7276. If
chainName is not specified, the default is BootstrapBasicMessaging. Refer
to the information center for more information.
Required: false
Data type: string
targetTransport
Range:
BINDING
CLIENT
BINDING_THEN_CLIENT
Required: false
Data type: string
Description: The prefix used at the start of temporary topics created by
applications using this connection factory.
Required: false
Data type: string
properties.microsoft.sqlserver
Data source properties for Microsoft SQL Server JDBC Driver. PID is
com.ibm.ws.jdbc.dataSource.properties.microsoft.sqlserver, and it is the child of
complex type dataSource.
Attributes
databaseName
Required: false
Data type: string
instanceName
Description: JDBC driver property: instanceName.
Required: false
Data type: string
serverName
Required: false
Data type: string
portNumber
Default value: 1433
Required: false
Data type: int
user
Required: false
Data type: string
password
Required: false
applicationIntent
Description: JDBC driver property: applicationIntent.
Range:
ReadOnly
ReadWrite
Required: false
Data type: string
applicationName
Description: JDBC driver property: applicationName.
Required: false
Data type: string
authenticationScheme
Description: JDBC driver property: authenticationScheme.
Range:
JavaKerberos
NativeAuthentication
Required: false
Data type: string
encrypt
Description: JDBC driver property: encrypt.
Required: false
Data type: boolean
failoverPartner
Description: JDBC driver property: failoverPartner.
Required: false
Data type: string
hostNameInCertificate
Description: JDBC driver property: hostNameInCertificate.
Required: false
Data type: string
integratedSecurity
Description: JDBC driver property: integratedSecurity.
Required: false
Data type: boolean
lastUpdateCount
Description: JDBC driver property: lastUpdateCount.
Required: false
Data type: boolean
lockTimeout
Description: JDBC driver property: lockTimeout. Specify a positive
Required: false
Data type: string
loginTimeout
seconds.
Required: false
Data type: string
multiSubnetFailover
Description: JDBC driver property: multiSubnetFailover.
Required: false
Data type: boolean
packetSize
Description: JDBC driver property: packetSize.
Required: false
Data type: int
responseBuffering
Description: JDBC driver property: responseBuffering.
Range:
adaptive
full
Required: false
Data type: string
selectMethod
Description: JDBC driver property: selectMethod.
Range:
cursor
direct
Required: false
Data type: string
sendStringParametersAsUnicode
Description: JDBC driver property: sendStringParametersAsUnicode.
Required: false
Data type: boolean
sendTimeAsDatetime
Description: JDBC driver property: sendTimeAsDatetime.
Required: false
Data type: boolean
trustServerCertificate
Description: JDBC driver property: trustServerCertificate.
Required: false
Data type: boolean
trustStore
Description: JDBC driver property: trustStore.
Required: false
Data type: string
trustStorePassword
Description: JDBC driver property: trustStorePassword.
Required: false
URL
Description: URL for connecting to the database. Example:
jdbc:sqlserver://localhost:1433;databaseName=myDB.
Required: false
Data type: string
workstationID
Description: JDBC driver property: workstationID.
Required: false
Data type: string
xopenStates
Description: JDBC driver property: xopenStates.
Required: false
Data type: boolean
properties.oracle
Data source properties for Oracle JDBC driver. PID is
com.ibm.ws.jdbc.dataSource.properties.oracle, and it is the child of complex type
dataSource.
Attributes
driverType
Default value: thin
Range:
thin
oci
Required: false
Data type: string
databaseName
Required: false
Data type: string
serverName
Required: false
Data type: string
portNumber
Default value: 1521
Required: false
Data type: int
URL
Description: 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
user
Required: false
Data type: string
password
Required: false
connectionProperties
Description: JDBC driver property: connectionProperties.
Required: false
Data type: string
loginTimeout
seconds.
Required: false
Data type: string
networkProtocol
Required: false
Data type: string
ONSConfiguration
Description: JDBC driver property: ONSConfiguration.
Required: false
Data type: string
serviceName
Description: JDBC driver property: serviceName.
Required: false
Data type: string
TNSEntryName
Description: JDBC driver property: TNSEntryName.
Required: false
Data type: string
properties.sybase
Data source properties for Sybase JDBC driver. PID is
com.ibm.ws.jdbc.dataSource.properties.sybase, and it is the child of complex type
dataSource.
Attributes
databaseName
Required: true
Data type: string
serverName
Required: false
Data type: string
portNumber
Default value: 5000
Required: false
Data type: int
user
Required: false
Data type: string
password
Required: false
connectionProperties
Description: JDBC driver property: connectionProperties.
Default value: SELECT_OPENS_CURSOR=true
Required: false
Data type: string
loginTimeout
seconds.
Required: false
Data type: string
networkProtocol
Range:
socket
SSL
Required: false
Data type: string
resourceManagerName
Description: JDBC driver property: resourceManagerName.
Required: false
Data type: string
SERVER_INITIATED_TRANSACTIONS
SERVER_INITIATED_TRANSACTIONS.
Range:
true
false
Required: false
Data type: string
version
Description: JDBC driver property: version.
Required: false
Data type: int
quickStartSecurity
Simple administrative security configuration. PID is
com.ibm.ws.security.quickStartSecurity.
Attributes
userName
Description: Single user defined as part of the quick start security
configuration. This user is granted the Administrator role.
Required: true
Data type: string
userPassword
Description: Password for the single user defined as part of the quick
start security configuration. It is recommended that you encode this
password. 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
name
Description: Name of the realm.
Required: true
Data type: string
participatingBaseEntryRef
Description: The Base Entry that is part of this realm.
Required: false
Data type: List of configuration IDs of type baseEntry (comma-separated
string).
delimiter
Description: Delimiter used for this realm
Default value: /
Required: false
Data type: string
enabled
Description: Specifies whether the realm is enabled for security use.
Default value: true
Required: false
Data type: boolean
allowOpIfRepoDown
Description: Specifies whether to allow operation if a repository is down.
The default value is false.
Required: false
Data type: boolean
uniqueUserIdMappingRef
Description: The property mapping for uniqueUserId (default:
uniqueName).
Required: false
Data type: Configuration ID of type uniqueUserIdMapping (string).
userSecurityNameMappingRef
Description: The property mapping for userSecurityName (default:
principalName).
Required: false
Data type: Configuration ID of type userSecurityNameMapping (string).
userDisplayNameMappingRef
Description: The property mapping for userDisplayName (default:
principalName).
Required: false
Data type: Configuration ID of type userDisplayNameMapping (string).
uniqueGroupIdMappingRef
Description: The property mapping for uniqueGroupId (default:
uniqueName).
Required: false
Data type: Configuration ID of type uniqueGroupIdMapping (string).
groupSecurityNameMappingRef
Description: The property mapping for groupSecurityName (default: cn).
Required: false
Data type: Configuration ID of type groupSecurityNameMapping (string).
groupDisplayNameMappingRef
Description: The property mapping for groupDisplayName (default: cn).
Required: false
Data type: Configuration ID of type groupDisplayNameMapping (string).
Sub-elements
participatingBaseEntry
Description: The Base Entry that is part of this realm.
Required: false
Data type: Element of type baseEntry.
uniqueUserIdMapping
Description: The property mapping for uniqueUserId (default:
uniqueName).
Required: false
Data type: Element of type uniqueUserIdMapping.
userSecurityNameMapping
Description: The property mapping for userSecurityName (default:
principalName).
Required: false
Data type: Element of type userSecurityNameMapping.
userDisplayNameMapping
Description: The property mapping for userDisplayName (default:
principalName).
Required: false
Data type: Element of type userDisplayNameMapping.
uniqueGroupIdMapping
Description: The property mapping for uniqueGroupId (default:
uniqueName).
Required: false
Data type: Element of type uniqueGroupIdMapping.
groupSecurityNameMapping
Description: The property mapping for groupSecurityName (default: cn).
Required: false
Data type: Element of type groupSecurityNameMapping.
groupDisplayNameMapping
Description: The property mapping for groupDisplayName (default: cn).
Required: false
Data type: Element of type groupDisplayNameMapping.
remoteAccess
Remote Access configuration. PID is
com.ibm.ws.management.command.remoteAccess.
Attributes
enableTrace
Description: Indicates whether the trace for remote access is enabled. The
default value is false.
Required: false
Data type: boolean
connTimeout
Description: Amount of time to wait for obtaining a remote connection to
remote targets. The default value is 180 seconds.
Default value: 180
Required: false
Data type: int
intConnTimeout
Description: Amount of time to wait for internal operations while
obtaining a remote connection to remote targets. Default is "infinite" or 0
second, meaning that there is no internal timeout limit.
Default value: 20
Required: false
Data type: int
useSftp
Description: Indicates whether to use sftp to transfer file. Te default value
is 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 is
com.ibm.ws.messaging.security.role.
Attributes
name
Description: The name of the role.
Required: true
Data type: string
permissionRef
Description: The permission for a destination for the set of users and
groups that are defined for the particular role.
Required: false
Data type: List of configuration IDs of type permission (comma-separated
string).
userRef
Description: The users that are assigned to the particular role.
Required: false
Data type: List of configuration IDs of type user (comma-separated
string).
groupRef
Description: The groups that are assigned to the role.
Required: false
Data type: List of configuration IDs of type group (comma-separated
string).
Sub-elements
permission
Description: The permission for a destination for the set of users and
groups that are defined for the particular role.
Required: false
Data type: Element of type permission.
user
Description: The users that are assigned to the particular role.
Required: false
Data type: Element of type user.
group
Description: The groups that are assigned to the role.
Required: false
Data type: Element of type group.
safAuthorization
Controls the operation of the SAF Authorization Service. PID is
com.ibm.ws.security.authorization.saf.
Attributes
roleMapper
Description: OSGi component name of the SAF Role Mapper service
provider.
Default value:
com.ibm.ws.security.authorization.saf.internal.SAFRoleMapperImpl
Required: false
Data type: string
safCredentials
Controls the operation of the SAF Credentials Service. PID is
com.ibm.ws.security.credentials.saf.
Attributes
unauthenticatedUser
Description: SAF user ID of the unauthenticated user.
Default value: WSGUEST
Required: false
Data type: string
profilePrefix
Description: Profile prefix used to specify the SAF APPL-ID when
creating SAF credentials and authorizing users against SAF resource
profiles.
Default value: BBGZDFLT
Required: false
Data type: string
safRegistry
Configuration properties for a SAF user registry. PID is
com.ibm.ws.security.registry.saf.config.
Attributes
realm
Required: false
Data type: string
safRoleMapper
Defines how to generate SAF EJBROLE resource profile names from application
role names. PID is
com.ibm.ws.security.authorization.saf.internal.SAFRoleMapperImpl.
Attributes
profilePattern
Description: Pattern to use for generating EJBROLE resource profile
names from application role names.
Default value: %profilePrefix%.%resource%.%role%
Required: false
Data type: string
toUpperCase
Description: Convert the EJBROLE resource profile name to upper-case.
Required: false
Data type: boolean
securewayLdapFilterProperties
Specifies the list of default IBM SecureWay Directory Server LDAP filters. PID is
com.ibm.ws.security.registry.ldap.internal.filters.secureway.
Attributes
userFilter
users.
Required: true
Data type: string
groupFilter
groups.
Default value:
(objectclass=groupOfUniqueNames)))
Required: true
Data type: string
userIdMap
entry.
Required: true
Data type: string
groupIdMap
entry.
Default value: *:cn
Required: true
Data type: string
groupMemberIdMap
Default value:
Required: true
Data type: string
serverCommand
Server Command MBean configuration. PID is
com.ibm.ws.management.command.serverCommand.
Attributes
startServerTimeout
Description: Amount of time to wait for remote server to start. The
default value is 60 seconds.
Default value: 60
Required: false
Data type: int
stopServerTimeout
Description: Amount of time to wait for remote server to stop. The
Default value: 60
Required: false
Data type: int
ssl
An SSL configuration repertoire with an ID, a defined keystore, and an optional
truststore. PID is com.ibm.ws.ssl.repertoire.
Attributes
keyStoreRef
Description: A keystore containing key entries for the SSL configuration
repertoire. This attribute is required.
Required: true
Data type: string
trustStoreRef
Description: A keystore containing trusted certificate entries used by the
SSL configuration repertoire for signing verification. This attribute is
optional. If unspecified, the same keystore is used for both key and
trusted certificate entries.
Default value: ${keyStoreRef}
Required: false
Data type: string
sslDefault
The default configuration repertoire for SSL services. PID is com.ibm.ws.ssl.default.
Attributes
sslRef
Description: The default SSL configuration repertoire. The default value
is defaultSSLSettings.
Default value: defaultSSLConfig
Required: false
Data type: string
sslOptions
The SSL protocol configuration for a transport. PID is
com.ibm.ws.sslchannel.options.
Attributes
sessionTimeout
Description: Amount of time to wait for a read or write request to
complete on a socket. This value is overridden by protocol-specific
timeouts. Specify a positive integer followed by a unit of time, which can
Default value: 1d
Required: false
Data type: string
suppressHandshakeErrors
Description: Disable logging of SSL handshake errors. SSL handshake
errors can occur during normal operation, however these messages can be
useful when SSL is behaving unexpectedly.
Required: false
Data type: boolean
sslRef
Description: The default SSL configuration repertoire. The default value
is defaultSSLSettings.
Required: false
Data type: string
supportedEntityType
The Supported entity type configuration. PID is
com.ibm.ws.wim.core.config.supportedEntityType.
Attributes
name
Description: The name of the supported entity type.
Required: true
Data type: string
Sub-elements
rdnProperty
Description: The Relative distinguished name property for the supported
entity.
Required: true
Data type: string
syncToOSThread
Enabled and configures the Sync-to-OS-thread Service. PID is
com.ibm.ws.security.thread.zos.internal.ThreadIdentityServiceImpl.
Attributes
appEnabled
Description: Enable sync-to-OS-thread for applications.
Required: false
Data type: boolean
j2cEnabled
Description: Enable sync-to-OS-thread for J2C connectors that support
native thread identity.
Required: false
Data type: boolean
tcpOptions
Defines TCP protocol settings. PID is com.ibm.ws.tcpchannel.options.
Attributes
inactivityTimeout
Description: Amount of time to wait for a read or write request to
complete on a socket. This value is overridden by protocol-specific
timeouts. Specify a positive integer followed by a unit of time, which can
be hours (h), minutes (m), seconds (s), or milliseconds (ms). For example,
Default value: 60s
Required: false
Data type: string
soReuseAddr
Description: 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 log
options. The HPEL text log can be viewed using any text editor. PID is
com.ibm.ws.logging.textLog, and it is the child of complex type logging.
Attributes
dataDirectory
Description: Specifies the location on the local file system to store the log
records.
Inherits: com.ibm.hpel.text.dataDirectory
Default value:
Required: false
Data type: string
outputFormat
Description: 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
includeTrace
Description: Include trace records in the Text Log
Inherits: com.ibm.hpel.text.includeTrace
Required: false
Data type: boolean
purgeMaxSize
Description: Specifies the maximum size for all log files.
Inherits: com.ibm.hpel.text.purgeMaxSize
Default value: 50
Required: false
Data type: int
purgeMinTime
record.
Inherits: com.ibm.hpel.text.purgeMinTime
Default value: -1
Required: false
Data type: int
fileSwitchTime
Inherits: com.ibm.hpel.text.fileSwitchTime
Required: false
Data type: int
bufferingEnabled
Inherits: com.ibm.hpel.text.bufferingEnabled
Default value: true
Required: false
Data type: boolean
outOfSpaceAction
Inherits: com.ibm.hpel.text.outOfSpaceAction
Range:
StopServer
Stop Server
PurgeOld
Remove old records
StopLogging
Stop Logging
Required: false
Data type: string
transaction
Configuration properties for the Transaction Manager service. PID is
com.ibm.ws.transaction.
Attributes
recoverOnStartup
Description: Specifies whether the server should begin transaction
recovery at server startup.
Required: false
Data type: boolean
waitForRecovery
Description: Specifies whether the server should wait for transaction
recovery to complete before accepting new transactional work.
Required: false
Data type: boolean
acceptHeuristicHazard
Description: Specifies whether all applications on this server accept the
possibility of a heuristic hazard occurring in a two-phase transaction that
contains a one-phase resource.
Default value: true
Required: false
Data type: boolean
clientInactivityTimeout
Description: Maximum duration between transactional requests from a
remote client. Any period of client inactivity that exceeds this timeout
results in the transaction being rolled back in this application server.
Default value: 60s
Required: false
Data type: string
heuristicRetryInterval
Description: Amount of time that the application server waits before
retrying a completion signal, such as commit or rollback, after a transient
exception from a resource manager or remote partner. Specify a positive
seconds.
Default value: 60s
Required: false
Data type: string
heuristicRetryWait
Description: The number of times that the application server retries a
completion signal, such as commit or rollback. Retries occur after a
transient exception from a resource manager or remote partner.
Default value: 5
Required: false
Data type: int
propogatedOrBMTTranLifetimeTimeout
Description: Upper limit of the transaction timeout for transactions that
run in this server. This value should be greater than or equal to the value
specified for the total transaction timeout. Specify a positive integer
seconds.
Default value: 0
Required: false
Data type: string
totalTranLifetimeTimeout
Description: Default maximum time allowed for transactions started on
this server to complete. Any such transactions that do not complete
before this timeout occurs are rolled back. Specify a positive integer
seconds.
Default value: 12000s
Required: false
Data type: string
transactionLogDirectory
Description: A directory for this server where the transaction service
stores log files for recovery.
Default value: ${server.config.dir}/tranlog/
Required: false
Data type: string
transactionLogSize
Description: Specifies the size of transaction log files in Kilobytes.
Default value: 1024
Required: false
Data type: int
enableLoggingForHeuristicReporting
Description: Specifies whether the application server logs
about-to-commit-one-phase-resource events from transactions that involve
both a one-phase commit resource and two-phase commit resources.
Required: false
Data type: boolean
timeoutGracePeriodEnabled
Description: Specifies whether there is a delay between a transaction
timeout and the abnormal ending of the servant region that was running
the transaction.
Required: false
Data type: boolean
lpsHeuristicCompletion
Description: Specifies the direction that is used to complete a transaction
that has a heuristic outcome; either the application server commits or
rolls back the transaction, or depends on manual completion by the
administrator. Allowed values are: COMMIT, ROLLBACK and MANUAL
Default value: ROLLBACK
Range:
ROLLBACK
COMMIT
MANUAL
Required: false
Data type: string
defaultMaxShutdownDelay
Description: Default maximum shutdown delay. Specify a positive
seconds.
Default value: 2s
Required: false
Data type: string
trustAssociation
Controls the operation of the trust association interceptor (TAI) service. PID is
com.ibm.ws.security.authentication.tai.
Attributes
invokeForUnprotectedURI
Description: Controls whether the TAI is invoked for an unprotected URI.
Required: true
Data type: boolean
failOverToAppAuthType
Description: Allow an interceptor to fall back to the application
authentication mechanism.
Required: true
Data type: boolean
Sub-elements
interceptors
Required: true
Data type: Defines a trust association interceptor.
enabled
Description: Enables or disables the interceptor.
Default value: true
Required: true
Data type: boolean
className
Description: Fully-qualified package name of the interceptor class.
Required: true
Data type: string
invokeBeforeSSO
Description: Invoke an interceptor before single sign-on (SSO).
Default value: true
Required: true
Data type: boolean
invokeAfterSSO
Description: Invoke an interceptor after single sign-on (SSO).
Required: true
Data type: boolean
libraryRef
Required: false
library
Required: false
properties
Required: false
uniqueGroupIdMapping
The property mapping for uniqueGroupId(default: uniqueName). PID is
com.ibm.ws.wim.uniqueGroupIdMapping.
Attributes
propertyForInput
types.
Default value: uniqueName
Required: true
Data type: string
propertyForOutput
Description: The that maps to the user registry attribute for output. The
valid values are: uniqueId, uniqueName, externalId, externalName and
the attributes of PersonAccount and Group entity types.
Required: true
Data type: string
uniqueUserIdMapping
The property mapping for uniqueUserId(default: uniqueName). PID is
com.ibm.ws.wim.uniqueUserIdMapping.
Attributes
propertyForInput
types.
Required: true
Data type: string
propertyForOutput
Required: true
Data type: string
user
The user that is defined as part of the registry. PID is
com.ibm.ws.messaging.security.user.
Attributes
name
Description: The name of the user.
Required: true
Data type: string
userDisplayNameMapping
The property mapping for userDisplayName(default: principalName). PID is
com.ibm.ws.wim.userDisplayNameMapping.
Attributes
propertyForInput
types.
Default value: principalName
Required: true
Data type: string
propertyForOutput
Required: true
Data type: string
userSecurityNameMapping
The property mapping for userSecurityName(default: principalName). PID is
com.ibm.ws.wim.userSecurityNameMapping.
Attributes
propertyForInput
types.
Required: true
Data type: string
propertyForOutput
Required: true
Data type: string
variable
Declare a new variable by specifying the name and value for the variable.
Attributes
name
Description: The name of the variable.
Required: true
Data type: string
value
Description: The value to be assigned to the variable.
Required: true
Data type: string
virtualHost
Virtual host configuration. PID is com.ibm.ws.http.virtualhost.
Attributes
enabled
Description: Enable this virtual host.
Default value: true
Required: false
Data type: boolean
webAppSecurity
Configures web container application security. PID is
com.ibm.ws.webcontainer.security.WebAppSecurityCollaboratorImpl.
Attributes
allowFailOverToBasicAuth
Description: Specifies whether to fail over to basic authentication when
certificate authentication fails. The equivalent custom property in the full
application server profile is
com.ibm.wsspi.security.web.failOverToBasicAuth.
Required: false
Data type: boolean
allowLogoutPageRedirectToAnyHost
Description: Warning, security risk: Setting this property to true may
open your systems to potential URL redirect attacks. If set to true, any
host can be specified for the logout page redirect. If set to false, and the
logout page points to a different host, or one not listed in the logout page
redirect domain list, then a generic logout page is displayed. The
equivalent custom property in the full application server profile is
com.ibm.websphere.security.allowAnyLogoutExitPageHost.
Required: false
Data type: boolean
displayAuthenticationRealm
Description: Warning, security risk: if this property is set to true, and the
user registry's realm name contains sensitive information, it is displayed
to the user. For example, if an LDAP configuration is used, the LDAP
server hostname and port are displayed. This configuration controls what
the HTTP basic authentication login window displays when the realm
name is not defined in the application web.xml. If the realm name is
defined in the application web.xml file, this property is ignored. If set to
true, the realm name displayed will be the user registry realm name for
the LTPA authentication mechanism or the Kerberos realm name for the
Kerberos authentication mechanism. If set to false, the realm name
displayed will be "Default Realm". The equivalent custom property in the
full application server profile is
com.ibm.websphere.security.displayRealm.
Required: false
Data type: boolean
httpOnlyCookies
Description: Specifies whether the HTTP only (HttpOnly) cookies option
is enabled.
Default value: true
Required: false
Data type: boolean
logoutOnHttpSessionExpire
Description: Specifies whether users will be logged out after the HTTP
session timer expires. If set to false, the user credential will stay active
until the Single Sign-On token timeout occurs. The equivalent custom
property in the full application server profile is
com.ibm.ws.security.web.logoutOnHTTPSessionExpire.
Required: false
Data type: boolean
logoutPageRedirectDomainNames
Description: A pipe (|) separated list of domain names that are allowed
for the logout page redirect (localhost is implied). The equivalent custom
com.ibm.websphere.security.logoutExitPageDomainList.
Required: false
Data type: string
postParamCookieSize
Description: Size of the POST parameter cookie. If the size of the cookie
is larger than the browser limit, unexpected behavior may occur. The
value of this property must be a positive integer and represents the
maximum size of the cookie in bytes. The equivalent custom property in
the full application server profile is
com.ibm.websphere.security.util.postParamMaxCookieSize.
Required: false
Data type: int
postParamSaveMethod
Description: 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 (POST
parameters are not preserved). The equivalent custom property in the full
com.ibm.websphere.security.util.postParamSaveMethod.
Default value: Cookie
Range:
Cookie
Session
None
Required: false
Data type: string
preserveFullyQualifiedReferrerUrl
Description: Warning, security risk: Setting this to true may open your
systems to potential URL redirect attacks. This property specifies whether
the fully qualified referrer URL for form login redirects is preserved. If
false, the host for the referrer URL is removed and the redirect is to
localhost. The equivalent custom property in the full application server
profile is com.ibm.websphere.security.util.fullyQualifiedURL
Required: false
Data type: boolean
singleSignonEnabled
Description: Specifies whether single sign-on is enabled.
Default value: true
Required: false
Data type: boolean
ssoCookieName
Description: Customizes the SSO cookie name. A custom cookie name
allows you to logically separate authentication between SSO domains and
to enable customized authentication to a particular environment. Before
setting this value, consider that setting a custom cookie name can cause
an authentication failure. For example, a connection to a server that has a
custom cookie property set sends this custom cookie to the browser. A
subsequent connection to a server that uses either the default cookie
name or a different cookie name, is not able to authenticate the request
via a validation of the in-bound cookie. The equivalent custom property
in the full application server profile is
com.ibm.websphere.security.customSSOCookieName.
Default value: LtpaToken2
Required: false
Data type: string
ssoDomainNames
Description: A pipe (|) separated list of domain names that SSO Cookies
should be presented. The equivalent custom property in the full
com.ibm.ws.security.config.SingleSignonConfig
Required: false
Data type: string
ssoRequiresSSL
Description: Specifies whether a SSO cookie is sent over SSL. The
com.ibm.websphere.security.customSSOCookieName
Required: false
Data type: boolean
ssoUseDomainFromURL
Description: Specifies whether to use the domain name from the request
URL for the cookie domain.
Required: false
Data type: boolean
useAuthenticationDataForUnprotectedResource
Description: Specifies whether authentication data can be used when
accessing an unprotected resource. The unprotected resource can access
validated authenticated data that it previously could not access. This
option enables the unprotected resource to call the getRemoteUser,
isUserInRole, and getUserPrincipal methods to retrieve an authenticated
identity. The equivalent custom property in the full application server
profile is com.ibm.wsspi.security.web.webAuthReq=persisting.
Default value: true
Required: false
Data type: boolean
webAlwaysLogin
Description: Specifies whether the login() method will throw an
exception when an identity has already been authenticated.
Required: false
Data type: boolean
webContainer
Configuration for the web container. PID is com.ibm.ws.webcontainer.
Attributes
listeners
Description: A comma separated list of listener classes.
Default value:
Required: false
Data type: string
decodeUrlAsUtf8
Description: Decode URL using the an encoding setting of UTF-8.
Default value: true
Required: false
Data type: boolean
fileServingEnabled
Description: Enable file serving if this setting was not explicitly specified
for the application.
Default value: true
Required: false
Data type: boolean
disallowAllFileServing
Description: Disables all file serving by applications. The equivalent
custom property in the full application server profile is
com.ibm.ws.webcontainer.disallowAllFileServing.
Required: false
Data type: boolean
directoryBrowsingEnabled
Description: Enable directory browsing of an application.
Required: false
Data type: boolean
serveServletsByClassnameEnabled
Description: Enable servlets to be accessed in a web application using a
class name if not explicitly specified.
Required: false
Data type: boolean
disallowServeServletsByClassName
Description: Disallows the use of serveServletsByClassnameEnabled on
the application server level. The equivalent custom property in the full
com.ibm.ws.webcontainer.disallowserveservletsbyclassname.
Required: false
Data type: boolean
doNotServeByClassName
Description: A semi-colon delimited list of classes to be completely
disallowed from being served by classname. The equivalent custom
com.ibm.ws.webcontainer.donotservebyclassname.
Default value:
Required: false
Data type: string
trustHostHeaderPort
Description: Set this property to true and the
com.ibm.ws.webcontainer.extractHostHeaderPort custom property to true
to return the port number from the request host header first.
Required: false
Data type: boolean
trusted
Description: Enables the application server to use inbound private
headers from the web server plug-in.
Default value: true
Required: false
Data type: boolean
extractHostHeaderPort
Description: The web container will return a port number from the host
header, if any, or the URL port on which the client connection was
accepted. The equivalent custom property in the full application server
profile is com.ibm.ws.webcontainer.extracthostheaderport.
Required: false
Data type: boolean
httpsIndicatorHeader
Description: For SSL offloading, set to the name of the HTTP header
variable inserted by the SSL accelerator/proxy/load balancer.
Default value:
Required: false
Data type: string
exposeWebInfOnDispatch
Description: If true, a servlet can access files in the WEB-INF directory. If
false (default), a servlet cannot access files the WEB-INF directory.
Required: false
Data type: boolean
decodeUrlPlusSign
Description: Decode the plus sign when it is part of the URL. The
com.ibm.ws.webcontainer.decodeurlplussign.
Required: false
Data type: boolean
channelWriteType
Description: When set to 'sync', responses will be written synchronously;
otherwise, responses will be written asychronously. The equivalent
com.ibm.ws.webcontainer.channelwritetype.
Default value: async
Required: false
Data type: string
suppressHtmlRecursiveErrorOutput
Description: Suppresses the HTML output of a recursive error that cannot
be handled by an application's configured error page. The equivalent
com.ibm.ws.webcontainer.suppressHtmlRecursiveErrorOutput.
Required: false
Data type: boolean
fileWrapperEvents
Description: Web container will generate SMF and PMI data when
serving the static files. The equivalent custom property in the full
application server profile is com.ibm.ws.webcontainer.fileWrapperEvents.
Required: false
Data type: boolean
defaultTraceRequestBehavior
Description: Restore HTTP TRACE processing. The equivalent custom
com.ibm.ws.webcontainer.DefaultTraceRequestBehavior.
Required: false
Data type: boolean
defaultHeadRequestBehavior
Description: Restore the behavior where the HEAD request is not subject
to the security constraint defined for the GET method. The equivalent
com.ibm.ws.webcontainer.DefaultHeadRequestBehavior.
Required: false
Data type: boolean
tolerateSymbolicLinks
Description: Enables the web container to support the use of symbolic
links. The equivalent custom property in the full application server profile
is com.ibm.ws.webcontainer.TolerateSymbolicLinks.
Required: false
Data type: boolean
symbolicLinksCacheSize
Description: Initial size of the symbolic link cache. The equivalent custom
com.ibm.ws.webcontainer.SymbolicLinksCacheSize.
Default value: 1000
Required: false
Data type: int
enableErrorExceptionTypeFirst
Description: Web container is updated to search and use the
exception-type before the error-code. The equivalent custom property in
com.ibm.ws.webcontainer.enableErrorExceptionTypeFirst.
Required: false
Data type: boolean
enableMultiReadOfPostData
Description: Retain post data for multiple read accesses. The equivalent
com.ibm.ws.webcontainer.enablemultireadofpostdata.
Required: false
Data type: boolean
copyAttributesKeySet
Description: Web container will return an enumeration of a copy of the
list attributes to the servlet to avoid a concurrent access error by the
servlet. The equivalent custom property in the full application server
profile is com.ibm.ws.webcontainer.copyattributeskeyset.
Required: false
Data type: boolean
dispatcherRethrowsEr
Description: Web container will re-throw errors allowing interested
resources to process them. The equivalent custom property in the full
com.ibm.ws.webcontainer.dispatcherRethrowser.
Default value: true
Required: false
Data type: boolean
ignoreSessiononStaticFileRequest
Description: Improves performance by preventing the web container
from accessing a session for static file requests involving filters. The
com.ibm.ws.webcontainer.IgnoreSessiononStaticFileRequest.
Required: false
Data type: boolean
invokeFilterInitAtStartup
Description: Web container will call the filter's init() method at
application startup. The equivalent custom property in the full application
server profile is com.ibm.ws.webcontainer.invokeFilterInitAtStartup.
Default value: true
Required: false
Data type: boolean
enableJspMappingOverride
Description: Allow the JSP mapping to be overridden so that the
application can serve the JSP contents itself. The equivalent custom
com.ibm.ws.webcontainer.enablejspmappingoverride.
Required: false
Data type: boolean
enableDefaultIsElIgnoredInTag
Description: Correct the default behavior of the EL expression's
evaluation in the tag files. The equivalent custom property in the full
application server profile is com.ibm.ws.jsp.enabledefaultiselignoredintag.
Required: false
Data type: boolean
parseUtf8PostData
Description: Web container will detect non URL encoded UTF-8 post data
and include it in the parameter values. The equivalent custom property in
com.ibm.ws.webcontainer.parseutf8postdata.
Required: false
Data type: boolean
logServletContainerInitializerClassLoadingErrors
Description: Log servlet container class loading errors as warnings rather
than logging them only when debug is enabled. The equivalent custom
com.ibm.ws.webcontainer.logservletcontainerinitializerclassloadingerrors.
Required: false
Data type: boolean
allowIncludeSendError
Description: Allow RequestDispatch to send errors on Include methods.
The equivalent custom property in the full application server profile is
com.ibm.ws.webcontainer.allowincludesenderror.
Required: false
Data type: boolean
skipMetaInfResourcesProcessing
Description: Do not search the meta-inf directory for application
resources. The equivalent custom property in the full application server
profile is com.ibm.ws.webcontainer.skipmetainfresourcesprocessing.
Required: false
Data type: boolean
metaInfResourcesCacheSize
Description: Initial size (number of entries) of the meta-inf resource
cache. The equivalent custom property in the full application server
profile is com.ibm.ws.webcontainer.metainfresourcescachesize.name.
Default value: 20
Required: false
Data type: int
xPoweredBy
Description: Alternative string for the X-Powered-By header setting. The
com.ibm.ws.webcontainer.xpoweredby.
Required: false
Data type: string
disableXPoweredBy
Description: Disable setting of the X-Powered-By header. The equivalent
com.ibm.ws.webcontainer.disablexpoweredby.
Required: false
Data type: boolean
deferServletLoad
Description: 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 before
automatically purging canceled tasks. The equivalent custom property in
com.ibm.ws.webcontainer.asyncmaxsizetaskpool.
Default value: 5000
Required: false
Data type: int
asyncPurgeInterval
Description: Time interval to wait between each required purge of the
cancelled task pool. The equivalent custom property in the full
application server profile is com.ibm.ws.webcontainer.asyncpurgeinterval.
Required: false
Data type: int
asyncTimeoutDefault
Description: Async servlet timeout value used when a timeout value has
not been explcitly specified. The equivalent custom property in the full
com.ibm.ws.webcontainer.asynctimeoutdefault.
Required: false
Data type: int
asyncTimerThreads
Description: Maximum number of threads to use for async servlet
timeout processing. The equivalent custom property in the full
application 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 is
com.ibm.ws.wim.registry.config.
Attributes
realm
Description: The realm name that represents the user registry.
Default value: WIMRegistry
Required: false
Data type: string
wlmClassification
Contains, as child elements, the classification rules WLM will use when classifying
requests. PID is com.ibm.ws.zos.wlm.classification.
Attributes
classificationName
Description: optional classification name
Default value: null
Required: false
Data type: string
wsSecurityClient
Web Services Security default configuration. PID is
com.ibm.ws.wssecurity.client.config.
Attributes
ws-security.username
Description: User information to create Username Token.
Required: false
Data type: string
ws-security.password
Description: User password information needed to create Username
Token.
Required: false
ws-security.callback-handler
Description: Password callback handler implementation class.
Required: false
Data type: string
ws-security.encryption.username
Description: Alias used for accessing encryption keystore.
Required: false
Data type: string
ws-security.signature.username
Description: Alias used for accessing signature keystore.
Required: false
Data type: string
Sub-elements
signatureProperties
Description: Required Signature configuration.
Required: false
Data type: Config information such as keystore type, keystore password.
org.apache.ws.security.crypto.merlin.keystore.type
Description: JKS, JCEKS or PKCS11
Required: false
Data type: string
org.apache.ws.security.crypto.merlin.keystore.password
Description: Password to access keystore file.
Required: false
org.apache.ws.security.crypto.merlin.file
Description: The location of the keystore
Required: false
Data type: string
org.apache.ws.security.crypto.merlin.truststore.file
Description: The location of the truststore
Required: false
Data type: string
org.apache.ws.security.crypto.merlin.truststore.password
Description: The truststore password.
Required: false
org.apache.ws.security.crypto.merlin.truststore.type
Description: The truststore type.
Required: false
Data type: string
org.apache.ws.security.crypto.provider
Description: 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.provider
Description: The provider used to load keystores. Defaults to
installed provider.
Required: false
Data type: string
org.apache.ws.security.crypto.merlin.cert.provider
Description: The provider used to load certificates. Defaults to
keystore provider.
Required: false
Data type: string
org.apache.ws.security.crypto.merlin.x509crl.file
Description: The location of an (X509) CRL file to use.
Required: false
Data type: string
org.apache.ws.security.crypto.merlin.keystore.private.password
Description: The default password used to load the private key.
Required: false
encryptionProperties
Description: Required Encryption configuration.
Required: false
Required: false
Data type: string
Required: false
Required: false
Data type: string
Required: false
Data type: string
installed provider.
Required: false
Data type: string
keystore provider.
Required: false
Data type: string
Required: false
Data type: string
Required: false
wsSecurityProvider
Web Services Security default configuration for provider. PID is
com.ibm.ws.wssecurity.config.
Attributes
ws-security.username
Description: User information to create Username Token.
Required: false
Data type: string
ws-security.callback-handler
Description: Password callback handler implementation class.
Required: false
Data type: string
ws-security.encryption.username
Description: Alias used for accessing encryption keystore.
Required: false
Data type: string
ws-security.signature.username
Description: Alias used for accessing signature keystore.
Required: false
Data type: string
callerToken
Description: Caller token.
Required: false
Data type: string
ws-security.enable.nonce.cache
Description: Whether to cache UsernameToken nonces.
Default value: true
Required: false
Data type: boolean
Sub-elements
signatureProperties
Description: Required Signature configuration.
Required: false
Required: false
Data type: string
Required: false
Required: false
Data type: string
org.apache.ws.security.crypto.merlin.truststore.file
Description: The location of the truststore
Required: false
Data type: string
org.apache.ws.security.crypto.merlin.truststore.password
Description: The truststore password.
Required: false
org.apache.ws.security.crypto.merlin.truststore.type
Description: The truststore type.
Required: false
Data type: string
Required: false
Data type: string
installed provider.
Required: false
Data type: string
keystore provider.
Required: false
Data type: string
Required: false
Data type: string
Required: false
encryptionProperties
Description: Required Encryption configuration.
Required: false
Required: false
Data type: string
Required: false
Required: false
Data type: string
Required: false
Data type: string
installed provider.
Required: false
Data type: string
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 the
server editor.
Procedure
1. 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 the
interaction between the workbench and the server.
Editing the Liberty profile configuration by using developer
tools
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 are
enabled, and logging and tracing settings.
Before you begin
For a description of the underlying process of configuring a server, and detailed
information about specific aspects of server configuration, see Administering the
Liberty profile manually on page 351.
Procedure
1. 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 configuration
are displayed.
3. Under the Feature Manager Details section the details for the currently
selected element are displayed.
4. To add new elements, select Server Configuration under the Configuration
Structure section then click Add.
5. To add child elements, select the parent element under the Configuration
Structure section and then click Add.
6. You can remove or move elements by selecting the element and using the
Remove, Up, and Down buttons.
Starting and stopping a server by using developer tools
You can start and stop a server by using the Liberty profile developer tools.
Procedure
v 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, click
to 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 library
You can define a utility project as a shared library and associate defined shared
libraries with an application or web project.
Before you begin
To use the shared library function in the workbench, you must create a utility
project and define it as a shared library. The utility project is the only project type
that 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 more
applications. Using shared libraries enables multiple application published on a
server 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 classes
available 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) into
that 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 can
add 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. The
file name convention of the JAR file is utilityProjectName.jar, where
utilityProjectName is the name of the utility project.
d. In the Liberty Profile Shared Library page, click Apply to confirm your
changes. Click OK to close the Properties window.
4. Add the utility project to the server.
For more details
see Adding and running an application on the Liberty profile by using
developer 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 previous
example, 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 defined
shared libraries with a web project.
Before you begin
v 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 more
applications. Using shared libraries enables multiple application published on a
server 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 make those classes
available to the application or module.
Procedure
1. To set a web project to use shared libraries:
a. In the Project Explorer view, right-click your web project that you want to
associate 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 a
comma-separated list. For example: ID1, ID2, ID3
Tip: The shared library identifier is the value specified in the Shared Libary
ID field from the Defining a utility project as a shared library task. You can
set 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 for
compilation-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 in
a web project that references classes in the shared libraries.
4. Add the web project to the server.
For more details
see Adding and running an application on the Liberty profile by using
developer 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 tools
You can use the WebSphere Runtime Explorer view to browse the available
servers as well as any shared configurations and applications for a runtime
environment. This view shows all of the available servers for the runtime
environment as opposed to the Servers view which shows only those servers that
are configured in the workspace. In both the WebSphere Runtime Explorer and
Servers 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 the
WebSphere Application Server Liberty profile.
About this task
You can use the WebSphere Runtime Explorer view to complete the following
tasks:
v View the servers defined in a runtime environment
v View the shared applications defined in a runtime environment
v View the shared configurations files defined in a runtime environment
v Create a new runtime environment
v 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 view
You can use the Merged Configuration view to see a flattened view of the server
configuration and any recursively included configuration files.
About this task
In the Server Configuration editor, under the Configuration Structure section, you
can use the Include element to import files that contain additional configuration
settings. The Include element can embed multiple layers of configuration files
within the server.xml file, which can make the configuration difficult to read
without tools. The Merged Configuration view provides a flattened view of the
server configuration and any recursively included configuration files. This is a
read-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 Merged
View.
Example
Here is an example of the source code for the server.xml file. Look at the include
tag which imports the common.xml file:
<server>
<featureManager>
</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 the
Server Configuration editor and Merged Configuration view. The Merged
Configuration view replaces the Include: common.xml element from the Server
Configuration editor with Application: Setup element.
Viewing the schema documentation for the server
configuration
You can view the schema documentation for the server configuration (server.xml
file) within the workbench. The documentation provides information about the
configuration elements that are available, the default settings, and details for each
of the elements.
Procedure
In the Servers view, right-click on the server configuration and select Open
Schema Reference.
Generating a Liberty profile server dump using developer
tools
Using the Liberty profile Utilities menu, you can generate a server dump for
support.
About this task
You can use the Utilities menu of your Liberty profile to generate a server dump to
capture all service-related information for support.
Procedure
1. 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 in
D:\LibertyUnzip\wlp\usr\servers\TestServer\TestServer.dump-12.03.22_15.00.11.zip.
Packaging a Liberty profile server by using developer tools
You can create a compressed file containing a server runtime environment, server
configuration, and applications using the packaging wizard.
About this task
Because a Liberty server is lightweight, you might find it useful to package up
your 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 or
to another machine, or even embed it in your product distribution.
Procedure
1. 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. This
filename can include a full path name. If the full path is omitted, a compressed
file 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 tools
You can add a data source to your application using the developer tools.
Procedure
1. In the Project Explorer view, expand liberty_profile_name > servers >
server_name > server.xml, and select Open With > Liberty Profile
Configuration 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 that
you want to include.
- In the Excludes field, type the archives that you want to exclude, or
click Browse to locate the data source archive file that you want to
exclude. Click Okay
Click Okay
v Click Okay
6. Your JDBC data source has been added to your application.
Administering the Liberty profile manually
You can administer the Liberty profile from the command prompt, configure it
with web server plug-ins, and capture its status. You can package a Liberty server
configuration along with the applications that it runs, for distribution to colleagues,
or installation on other systems. If available, you can use the Equinox OSGi
console to aid with debugging.
About this task
The server.xml file is the primary configuration file for the server. You can edit
this file, and the files it includes, in a text editor. You can also change the location
of the server.xml file. However, for most configurations you do not need to do
this.
The bootstrap.properties file is used to specify properties that need to be
available before the main configuration is processed. If you update the
bootstrap.properties file, you must restart the server with the --clean option for
the changes to take effect.
Example
All the elements that can be configured in the server.xml file, and the files it
includes, are described in Liberty profile: Configuration elements in the server.xml
file on page 97. However, the only required element is a server definition:
<server/>
Beyond this server definition, you only specify overrides and additions to the
default 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 to
define the features that are to be provided by the server:
<server>
<featureManager>
</featureManager>
</server>
See also Adding and removing Liberty features on page 368.
Where multiple instances of a resource type can be configured, for example
applications or data sources, you need only provide the attributes that are unique
for the resource. You can let the other attributes use the default values, or override
them as needed. Therefore the contents of the server.xml file can be brief. For
example, 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 the
subtopics.
Customizing the Liberty profile environment
You can customize the Liberty profile environment by using certain specific
variables to support the placement of product binary files and shared resources in
read-only file systems.
About this task
The following Liberty profile specific variables can be used to customize the
Liberty profile environment:
v ${wlp.install.dir}
This configuration variable has an inferred location. The installation directory is
always set to the parent of the directory containing the launch script, or the
parent 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 is
specified, the runtime environment looks for shared resources and server
definitions 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 for
server 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. If
this 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 in
server.env files. You can also specify JVM options in jvm.options files.
Procedure
v Specify environment variables by using server.env files.
You can use server.env files at the installation and server levels to specify
environment variables such as JAVA_HOME, WLP_USER_DIR, and WLP_OUTPUT_DIR.
For example:
# Use a specific Java binary
JAVA_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 the
remaining configuration is located. After the remaining configuration is found
and merged, no further configuration in a different location is expected, or
supported.
The server management script searches for server.env files in two locations:
${wlp.install.dir}/etc/server.env and ${server.config.dir}/server.env. If
both files are present, the contents of the two files are merged; values in the
server-level file take precedence over values in the runtime-level file.
You can also specify these environment variables in the shell environment, but
the 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 specify
additional server startup options, for example, -X arguments. The options are
applied when the start, run, and debug actions are started through the server
management 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. If
both files are present, the options in the ${server.config.dir}/jvm.options file
are 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 prompt
You can use the server and ws-launch.jar commands to create a server, to start, or
stop 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 the
server 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 a
debugger 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 an
archive file for further tuning and diagnosis.
javadump
A command that creates a snapshot of the server JVM and saves the result
into files. Each dump type creates a file in ${server.output.dir}, but not
all dump types are supported by all virtual machines.
package
A 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.
version
A command that displays the version information of current server and
Java runtime environment.
help A command that gets command-line script help, including details of
additional options.
Note: If a server is not specified on the command line, the action is performed
against the default server instance, defaultServer, if it exists.
You can also carry out similar actions by using the executable JAR file
ws-launch.jar that is in the wlp/lib directory.
Example
To run the server script on Windows systems:
server.bat create server_name
server.bat package server_name
server.bat run server_name
server.bat help server_name
To run the server script on other systems:
server create server_name
server package server_name
server run server_name
server 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 --create
java -javaagent:lib/bootstrap-agent.jar -jar lib/ws-launch.jar server_name
java -javaagent:lib/bootstrap-agent.jar -jar lib/ws-launch.jar --help
The --help option provides information about additional command-line
parameters for the executable JAR file ws-launch.jar , such as --stop, --version,
--clean, --include.
Liberty profile: server command options
The server command supports starting, stopping, creating, packaging, and
dumping a Liberty profile server. This topic describes all available options and exit
codes that you can use with the server command and the equivalent executable jar
file ws-launch.jar.
Syntax
server action serverName [options]
where the value of action represents the operation that you can perform on a
Liberty profile server. See available administration operations for the Liberty
profile 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 be
either a relative path, which is relative to the installation root directory of
the Liberty profile, or an absolute path. The default archive target is a
compressed file with the server name, which will be stored in the
installation root directory. Use quotation marks if the value contains
spaces. You can use this option for both package and dump operations.
--clean
Cleans 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 the
action 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 in
the server.env file, the files under them are packaged. This value only
applies to the package operation.
v usr specifies to package the files in the ${WLP_USER_DIR} directory. This
value only applies to the package operation.
v heap is used to help diagnose the excessive memory consumption and
memory leaks, which shows live objects in the memory and references
between them. On IBM J9 virtual machines, the resulting file is named
heapdump.date.time.processID.sequenceNumber.phd. On HotSpot virtual
machines, the resulting file is named
java.date.time.processID.sequenceNumber.hprof. This value applies to
both the dump and javadump operations
v system is also used to help diagnose the excessive memory consumption
and memory leaks, but they are also useful for finding defects in the
virtual machine. These dumps are only supported on IBM J9 virtual
core.date.time.processID.sequenceNumber.dmp. This value applies to
both the dump and javadump operations.
v thread is used to help diagnose hung threads, deadlocks, and can
sometimes be used for diagnose excessive CPU issues. These dumps are
always created with the server javadump command. On IBM J9 virtual
javacore.date.time.processID.sequenceNumber.txt. On HotSpot virtual
javadump.date.time.processID.sequenceNumber.txt. This value can also
be applied to the dump operation.
Note: The thread dump type is only supported when the server is
running on the Java SDK. If the server is started with a JRE, an error
will be reported indicating that the server does not support the dump
type. This restriction only applies to HotSpot virtual machines; the
thread 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 equivalent
executable JAR file ws-launch.jar:
0 OK. 0 indicates successful completion of the requested operation. For
server status, 0 indicates that the server is running.
1 For server status, 1 indicates that the server is not running. For other
operations, it indicates invocation of a redundant operation. For example,
starting a started server or stopping a stopped server. This code might also
be 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, the
server is running when the package action is called.
4 An unsupported action was called on a stopped server. For example, the
server is not running when the dump action is called
5 Unknown server status. For example, the workarea directory is missing, or
the Attach API fails to work.
>=20 Return codes greater than or equal to 20 indicates that an error occurred
while performing the requested . Messages will be printed and captured in
log files with more information about the error.
Usage
The following examples demonstrate the correct syntax:
server run
server start myserver --clean
server package myserver --archive="c:\mybackup\" --include=all
server dump myserver --archive="c:\mybackup\" --include=thread
server javadump myserver
server javadump myserver --include=heap,system
Generating a Liberty profile server dump from the command
prompt
From the command prompt you can use the server dump or server javadump
command to capture status information for a Liberty profile server.
About this task
The server dump command is useful for problem diagnosis of a Liberty profile
server because the result file contains server configuration, log information, and
details of the deployed applications in the workarea directory. The command can
be 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 server
v Wiring information for each OSGi bundle in the server
v Component list managed by the Service Component Runtime (SCR) environment
v Detailed information of each component from SCR
v Configuration administration data of each OSGi bundle
v Information about registered OSGi services
v Runtime environment settings such as JVM, heap size, operating system, thread
information, and network status
The server javadump command is useful for
diagnosing problems at the JVM level, such as hung threads, deadlocks, excessive
processor, excessive memory consumption, memory leaks, and defects in the
virtual machine. The command can only be used on a running server. Each dump
type creates a file in ${server.output.dir}, but not all dump types are supported
by all virtual machines. See Liberty profile: server command options on page
354.
Procedure
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.

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. This
file name can include a full path name. If the full path is omitted, a
compressed file called package_file_name.dump.zip is created in the
${server.output.dir} directory.
The --include parameter is optional. You can
request additional memory dump types. For example, --include=heap option
requests a heap dump; --include=thread,heap,system option requests a
thread dump, a heap dump, and a system dump.
v To create a snapshot of the JVM status, use
server javadump command.

server javadump server_name --include=heap
The --include parameter is optional. You can request additional memory
dump types. For example, --include=heap option requests a thread dump
and a heap dump; --include=heap,system option requests a thread dump, a
heap dump, and a system dump.
Note: The resulting file is created by using UTF-8 encoding for entry names, so
you must use a tool capable of opening the file by using UTF-8 encoding for
entry 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 the
specified server exists, a result file is created that contains the status information of
the server.
Packaging a Liberty profile server from the command prompt
From the command prompt you can create a compressed file containing a Liberty
profile runtime environment, the files in the shared resources directory, a specific
server, and the applications that are embedded in the server. You can also choose
to exclude the runtime binaries from the compressed file.
About this task
The Liberty server is lightweight, therefore you can easily package a server
installation in a compressed file. You can then store this package, distribute it to
colleagues, use it to deploy the installation to a different location or to another
machine, or even embed the installation in a product distribution.
Note:
The resulting file is created by using UTF-8
encoding for entry names, so you must use a tool capable of opening the file by
using UTF-8 encoding for entry names. The jar command in a Java SDK uses this
format.
Procedure
To package a Liberty profile server from the command prompt, complete the
following steps:
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 value
of server_name is used for package_file_name, and the compressed file is created
in the ${server.output.dir} directory.
v
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 name
can include a full path name. If the full path is omitted, a compressed file
called 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 in
the ${WLP_USER_DIR} directory; the --include=usr option packages only
relevant files in the ${WLP_USER_DIR} directory, effectively excluding the runtime
binaries from the compressed file.
Starting and stopping a server from the command prompt
You 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 the
server process. The syntax of this script is as follows:
server action serverName [options]
For available values of [options], see Liberty profile: server command options on
page 354.
Procedure
v 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 profile
Apache Ant is a Java library tool for automating the build process. You can use
Ant 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 of
the server image. This plug-in contains a set of Ant tasks. If you want to use these
tasks in your build script, you must make sure the plug-in is available on the Ant
classpath. One way of doing this is to copy the plug-in file wlp-anttasks.jar to
the /lib directory of the Ant installation, and declare the antlib namespace in the
build.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. For
example, 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 test
your application on the Liberty profile.
Procedure
v 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 Liberty
profile 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 of
each attribute, and the third column states whether this attribute is required.
Attribute Description Required
installDir Location of the Liberty
profile server.
Yes
operation Server operations available
as options: create, start,
stop, status, and package.
Yes
serverName Name of the Liberty profile
server instance. The default
value 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
${serverName}
No
clean Attributes that determines
whether to operate the server
using the clean option.
No
timeout Waiting time before the
server starts or stops. The
The unit is milliseconds.
No
Table 11. The attributes of the server task (continued).
archive Location of the compressed
file when packaging a server.
The value must be a file
name and only works for the
package option.
No
ref Reference to an existing
server task definition to
reuse its server
configuration. The value can
be null when other required
attributes 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 Liberty
profile server.
Attributes
The following table describes attributes of the deploy task.
Table 12. The attributes of the deploy task.
profile server.
Yes
No
${serverName}.
No
Table 12. The attributes of the deploy task (continued).
${serverName}.
No
file Location of a single
application to be deployed.
See file attribute in Apache
Ant. The application type
can be war, eba, zip, rar , or
jar.
Yes, only when the fileset
attribute is not specified.
fileset Location of multiple
applications to be deployed.
See fileset attribute in
Apache Ant.
Yes, only when the file
attribute is not specified.
deployment completes
successfully. The default
value is 30 seconds. The unit
is milliseconds.
No
reuse its server
attributes are set.
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 Liberty
profile server.
Attributes
The following table describes attributes of the undeploy task.
Table 13. The attributes of the undeploy task.
each attribute, and the third column represents whether this attribute is required.
profile server.
Yes
No
${serverName}.
No
${serverName}.
No
file Name of application to be
removed. The application
type can be war, eba, zip,
rar, or jar.
Yes
undeployment completes
successfully. The default
value is 30 seconds. The unit
is milliseconds.
No
reuse its server
attributes are set.
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 profile
Apache Maven is a software project management tool based on the concept of a
project object model (POM). You can use the Maven plug-in provided by the
Liberty 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 your
Maven project, you must make sure the plug-in repository is specified in the
pom.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 create
a Liberty profile server, and test your application on the Liberty profile. Each task
is represented by a specific goal in Maven.
Procedure
v 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 to
install a Liberty profile server from a compressed archive or a directory that has
the server installation files. Additionally, you can assemble a Liberty profile server
into 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 existing
directory.
mvn liberty:install-server -DserverHome=/path/to/server_home -DserverName=[server_instance_name]
Example: installing the server from an existing directory
This is the code snippet that you can use in the pom.xml file of your
project.
<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 the
Liberty 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 artifact
project.
<plugin>

<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-install-plugin</artifactId>
<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>
<packaging>zip</packaging>
</configuration>
</execution>
<!install the liberty server as maven artifact<plugin>
<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>
<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 the
Liberty 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 archive
project.
<plugin>
<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 to
start a Liberty profile server in the file system. If the server does not exist, this task
can 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 server
project.
<plugin>
<executions>
<execution>
<id>start-server</id>
<phase>pre-integration-test</phase>
<goals>
<goal>start-server</goal>
</goals>
<configuration>
</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 to
create 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 server
project.
<plugin>
<executions>
<execution>
<id>create-liberty-server</id>
<goals>
<goal>create-server</goal>
</goals>
<configuration>
<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 to
package 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 server
project.
<plugin>
<executions>
<execution>
<id>package-server</id>
<phase>post-integration-test</phase>
<goals>
<goal>package-server</goal>
</goals>
<configuration>
<serverHome>${project.build.directory}/was4d</serverHome>
<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 stop
a 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 server
project.
<plugin>
<executions>
<execution>
<id>stop-server</id>
<phase>post-integration-test</phase>
<goals>
<goal>stop-server</goal>
</goals>
<configuration>
</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 deploy
applications on a Liberty profile server.
Usage: This is the Maven goal that you can use to deploy an application from the
server.
mvn liberty:deploy -DserverHome=/path/to/server_home
-DserverName=[server_name] -DappArchive=/appname
Example: deploying an application
project.
<plugin>
<executions>
<execution>
<id>deployapp</id>
<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 remove
an application from the Liberty profile server.
Usage: This is the Maven goal that you can use to remove an application from the
server.
mvn liberty:undeploy -DserverHome=/path/to/server_home
-DserverName=[server_name] -DappArchive=/appname
Example: undeploying an application
project.
<plugin>
<executions>
<execution>
<id>undeploy</id>
<goals>
<goal>undeploy</goal>
</goals>
<configuration>
<appArchive>foo.ear</appArchive>
</configuration>
</execution>
</executions>
</plugin>
Using an OSGi console
Eclipse Equinox currently provides an OSGi console that you can use to aid with
debugging. This console is not available by default. When you work with the
Liberty 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 core
specification. 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 the
bootstrap.properties file. Then you can use Telnet to connect to the console on
that 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 set
this 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 features
runtime environment that are loaded into a particular server. To add or remove a
Liberty feature, you add or remove an XML snippet in the <feature> subelement
of the server.xml configuration file. When you add or remove Liberty features, the
changes are applied dynamically.
Before you begin
You can add and remove Liberty features as described in this topic, or as described
in 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 the
wab-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 on
page 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 the
configuration root document file is usr/servers/server_name/server.xml.
However, you can change the path. See Customizing the Liberty profile
environment on page 352.
2. Add or remove features in the configuration file.
The set of features is enclosed within the <featureManager> element, and each
feature within the <feature> subelement. For example:
<server>
<featureManager>
</featureManager>
</server>
The matching of feature names is not case-sensitive; the following example is
also a valid server configuration:
<featureManager>
<feature>Servlet-3.0</feature>
</featureManager>
3. Save the changes to the configuration file.
Results
Your changes are applied. If the server is running, the changes are applied
dynamically.
Using include elements, variables, and Ref tags in
configuration files
You can keep all your configuration settings in a single server.xml file, or you can
use include elements to consolidate configuration settings from separate files. You
can use variables in the configuration to avoid hardcoding values that might not
be appropriate when the configuration is reused in different environments. You can
use Ref tags to refer to (and thereby reuse) existing code blocks that are defined
elsewhere in the configuration.
Procedure
v Using include elements in configuration files
v Using variables in configuration files on page 372
v Using Ref tags in configuration files on page 373
Using include elements in configuration files
You can keep all your configuration in a single server.xml file, or you can use
include elements to consolidate configurations from separate files to create the
structure that is most useful to you.
About this task
It can be easier to maintain a complex configuration by splitting it across a set of
files. 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 optional
attribute 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 order
shown.
1. in a location specified relative to the parent file
2. in the shared configuration directory
3. in a location specified as an absolute path
4. on a web server
To ensure that your include configuration behaves predictably, you need to be
aware 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 override
previous ones. This is also true for configuration instances, for example an
application 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 includes
the contents of the blogDS.xml configuration file, which is located in the shared
configuration directory. The blogDS.xml file contains a data source definition. This
definition has been put in a separate configuration file so that it can be included in
several different server.xml files, and thereby used across multiple server
instances.
Here is example code from the server.xml file:
<server>
<featureManager>
</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 files
You can use variables in the configuration to avoid hard coding values that might
not 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 file
v in the bootstrap.properties file
v 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 port
numbers, are usually specified in the bootstrap.properties file, allowing the
server.xml to be shared across multiple servers while keeping those values
different in each server. Variables that are shared across a group of servers, for
example database configuration for a particular host, is better specified in an xml
file that is included into the parent configuration file.
Procedure
v Specify a variable in a configuration file.
Variables defined in the configuration files are scoped to the configuration
elements by which they are used. For example, the following code fragment
creates a variable called updateTrigger_var to be used in applicationMonitor
configuration elements:
<applicationMonitor updateTrigger_var="mbean" />
To create a variable that is used in a particular configuration instance (such as an
application or resource entry), you must also specify the instance identifier. For
example:
<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 particular
configuration 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 particular
configuration elements. You enter the variables as Java system properties. For
example:
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 the
HTTP_default_var variable, add the following code fragment to the configuration
file:
httpPort="${HTTP_default_var}">
</httpEndpoint>
v Use variable element in the configuration
You can use the variable element to define a variable globally in the server
configuration. If the same variable is defined in an included file, it is overridden
by 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 configuration
You can override the default values of inheritable attributes in the configuration.
The inheritable attributes are listed on the Liberty profile: Configuration
elements in the server.xml file on page 97 page with an Inherits type. For
example, the onError attribute is one of inheritable attributes. You can define a
variable name for the onError attribute globally by either setting it in the
bootstrap.properties or server.xml file with a variable element. If the same
variable 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 back
to the global value defined in bootstrap.properties or server.xml file or the
default 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 files
You can define a common configuration element, then reuse that definition by
referring to it (using a Ref tag) from elsewhere in the configuration. Ref tags can be
used in the same configuration file that contains the element definition, or in an
included configuration file.
About this task
Different approaches are used to specify relationships between the required
configuration elements. For example, the following data source definitions are all
valid. The first uses no Ref tags, the second uses a combination of direct element
definition 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">
<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 only
permitted as nested).
<dataSource id="blogDS" jndiName="jdbc/blogDS"
connectionManagerRef="derbyPool" jdbcDriverRef="derbyEmbedded">
</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 updates
There are three types of dynamic update that can be controlled through
configuration: changing the server configuration; adding and removing
applications; updating installed applications. For all deployed applications, you can
configure whether application monitoring is enabled 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 choose whether to deploy the applications
that are in the directory.
About this task
By default, deployed applications are monitored for updates, and the updates are
dynamically applied to the running application. This applies both to applications
that are deployed through configuration entries, and those deployed from the
dropins directory. You can change these default behaviors by setting the config
and applicationMonitor elements in the server.xml configuration file. You can use
a text editor to do this, or you can use the developer tools and select
Configuration Admin Service or Application Monitor in the server configuration
design 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 the
timing interval specified by the monitorInterval property.
mbean
The runtime environment only looks for updates when prompted to do
so through a call to an MBean. This is the mode that is used by the
developer tools to update the server.xml file, unless you override it.
disabled
The updates are not dynamically applied.
v When you specify the pollingRate property, you include the unit of time after
the 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 the
applications in the dropins directory are deployed.
Procedure
v Configure dynamic changes to the server configuration.
Changes to the server.xml file, or any files it includes, are detected by the
runtime environment and applied to the active configuration. You can disable
this 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, on
page 517, applications can be dynamically added to and removed from the
server 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 the
previous step, then adding or removing application entries has no effect on a
running server. Your changes are only applied at the next server restart. The
changes are picked up immediately, if you update application entries using
the developer tools.
By moving application files into and out of the dropins directory.
This behavior can be controlled by setting the applicationMonitor element in
the server.xml file. For example, to disable dynamic installation of
applications 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 deployed
application, or you replace the whole application with an updated version, the
previous version is automatically stopped and the new version is started. This
process applies for any deployed application, whether the application is in the
dropins directory or at a location defined in the server.xml file. You can
control this behavior by setting the applicationMonitor element in the
server.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 can
change this by setting the applicationMonitor element in the server.xml file.
For the location, you can use any known variable, or a property in the
bootstrapping.properties file, or an absolute path, or a path relative to the
server directory. For example, both the following settings point to the same
location:
<applicationMonitor dropins="${server.config.dir}/applications" />
<applicationMonitor dropins="applications" />
Configuring class loaders and libraries for Java EE
applications
By default, each application can access a set of provided APIs and its own internal
classes and libraries. You can override the default settings, and configure class
loading for each application.
About this task
Each Java EE application has its own class loader in a running Liberty profile
server. The Liberty profile assumes some default settings for all Java EE
applications, so that they can access the supported specification APIs (for example
the 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 classes
and libraries. If you have to override the default settings and configure class
loading for your application, complete one or more of the following tasks.
Note: If you use configuration to override the default settings, you cannot deploy
the application by dropping it into the dropins directory.
Procedure
v Using a Java library with a Java EE application
v Sharing a library across multiple Java EE applications on page 377
v Accessing third-party APIs from a Java EE application on page 379
v Removing access to third-party APIs for a Java EE application on page 380
v Overriding a provided API with an alternative version on page 380
v Providing global libraries for all Java EE applications on page 378
Using a Java library with a Java EE application
One way of using Java libraries with an application is to include them in the
application itself. This might not always be desirable or appropriate, especially if
the 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 and
v commons-lang.jar
An application called Scholar, running on a server called Academy, needs access to
this library.
Procedure
1. 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 new
folder.
3. Configure class loading for the application, so that the Alexandria library is
loaded.
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 with
a comma-separated list of <fileset> element IDs.
Sharing a library across multiple Java EE applications
Libraries can be shared across multiple Java EE applications. All the applications
can use the same classes at run time, or each application can use its own separate
copy 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 and
v commons-lang.jar
An application called Scholar and an application called Student are running on a
server called Academy, and both need access to this library.
Procedure
1. 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 new
folder.
3. Configure class loading for the application, so that the Alexandria library is
loaded.
In the server.xml file, or an included file, define the library by adding the
following code:
<library id="Alexandria">
</library>
Note: The <library> element can also take a filesetRef attribute with a
comma-separated list of <fileset> element IDs.
4. Reference the library from the applications, so that both these applications
share a single copy of the library.
<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 of
library IDs.
5. Optional: Configure another application to have its own set of classes loaded
from 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 an
included 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 of
library IDs.
Creating an automatic shared library
Shared libraries can be created automatically, and are given an ID that is the same
as the directory name. When creating an automatic shared library, you provide a
reference to the directory name of the library.
About this task
Under the ${WLP_USER_DIR} directory, there are two locations in which you can
place 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.xml
file:
<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. For
example:
<server_install_dir>\usr\servers\<server_name>\lib\AutomaticSharedLibraryA\
Providing global libraries for all Java EE applications
You can provide global libraries that can be used by any application. You do this
by putting the JAR files for those libraries in a global library directory, then
specifying use of global libraries in the class loader configuration for each
application.
About this task
Under the user directory specified by using the environment variable
WLP_USER_DIR, there are the following locations in which you can place global
libraries:
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, and
that application does not have a <classloader> element configured, the application
uses these libraries. If a class loader configuration is present, these libraries are not
used 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 requires
applications to share the global library class loader in their class loader parent
chain. This breaks the separation of class loaders for each application that is
otherwise possible. So, applications are more likely to have long-lasting effects on
classes loaded in Liberty and on each other, and class space consistency issues are
more likely to arise between applications, especially as features are added and
removed from a running server. None of these considerations apply for
applications that specify a <classloader> element in their configuration, because
they maintain this separation.
Example
In the following example, an application called Scholar is configured to use a
common library called Alexandria, and also to use the global library.
In the server.xml file, or an included file, enable the global library for an
application 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 library
element 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 application
By default, Java EE applications do not have access to the third-party APIs
available in the Liberty profile. To enable this access, the application must be
configured in the server.xml file, or an included file.
About this task
In the following example, an application called Scholar needs access to the
third-party APIs that are available in the Liberty profile.
The application also uses a common library called Alexandria. This library is
located 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.
Procedure
1. 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 by
adding the following code:
<classloader apiTypeVisibility="spec, ibm-api, third-party" commonLibraryRef="Alexandria" />
</application>
2. Optional: If the application uses any common libraries, set those libraries to use
the same API type visibility setting.
<library id="Alexandria" apiTypeVisibility="spec, ibm-api, third-party">
</library>
Removing access to third-party APIs for a Java EE application
By default, Java EE applications do not have access to the third-party APIs
available in the Liberty profile. You can also remove access explicitly in the
server.xml file, or an included file.
About this task
In the following example, an application called Scholar has previously been
configured to access third-party APIs, as described in Accessing third-party APIs
from a Java EE application on page 379. You want to remove this access, and to
make it explicit in the configuration that the application now uses the default
access setting.
The application also uses a common library called Alexandria. This library is in the
${server.config.dir}/mylib/Alexandria directory.
Procedure
1. 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 of
values included for the apiTypeVisibility attribute:
<classloader apiTypeVisibility="spec, ibm-api" commonLibraryRef="Alexandria" />
</application>
2. Optional: If the application uses any common libraries, set those libraries to use
the same API type visibility setting.
<library id="Alexandria" apiTypeVisibility="spec, ibm-api">
</library>
Overriding a provided API with an alternative version
If an application provides (or uses a library that provides) classes that are also
available in the Liberty profile, by default the classes from the Liberty profile are
used. To change this so that the application uses the alternative versions of these
classes, the application must be configured in the server.xml file, or an included
file.
About this task
If a web application includes classes that are also present in the server runtime
environment, you might want to control which copy of each of those classes is
used by the application. For example, if different versions of the classes are present
in both the application and the server runtime environment, you must ensure that
the version packaged in the application is used.
By default, classes from the Liberty profile runtime environment are used by all
Java EE applications. You can override this behavior by using the class loader
configuration delegation attribute. This configuration is specific to a particular
application, 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 it
provides (or that are provided in a library that it uses), rather than using the
copies 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.xml
configuration file or a file that it includes:
<classloader delegation="parentLast" />
</application>
This tells the application class loader to look at the Liberty profile classes only
after looking in the application and its associated libraries for a class.
v When the classes are packaged in a shared library, add the delegation attribute
to the classloader element that configures the use of the shared library as
follows:
<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 an
application. See Sharing a library across multiple Java EE applications on page
377.
Configuring a web server plug-in for the Liberty profile
You can configure a web server plug-in so that, when the web server receives an
HTTP request for dynamic resources, the request is forwarded to the Liberty
profile.
About this task
A web server plug-in is used to forward HTTP requests from a supported web
server to one or more application servers. The plug-in takes a request and checks
the request against configuration data in the plugin-cfg.xml file. The configuration
data 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 the
application server.
Procedure
1. 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.
v Do not copy or run the generated configureWebserver script because this
script is not required with the Liberty profile.
4. Start the server that hosts your applications, and ensure that the
localConnector-1.0 feature and other required features are included in the
server configuration.
In the pluginConfiguration element of the server configuration file, you can
specify the webserverPort and webserverSecurePort attributes to forward
requests from the web server. By default, the value of webserverPort is 80 and
the value of webserverSecurePort is 443. However, you might want to change
these settings. For example for Linux and similar platforms, if you are a
non-root user, you must use port numbers greater than 1024.
For all configurable attributes of the pluginConfiguration element, see Liberty
profile: 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>
</featureManager>
<keyStore id="defaultKeyStore" password="{xor}PGY6bW4wOyw+" />
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 the
ssl-1.0 Liberty feature of the Liberty profile.
v If the web server is using the default ports, you don't have to include the
pluginConfiguration 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. You
cannot use the JKS keystore that is created by the Liberty profile or full
profile for the web server plug-in, though you have to exchange signer
certificates between the web server plug-in keystore and the Liberty profile
keystore.
v To configure the location of the plug-in log file, add the following code
snippet 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 and
applications by calling the
WebSphere: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 to
customize installation root directory and server name before generating the
plugin-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"/>
</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, any
issues with the utility itself must be reported to your Java SDK provider.
v The management interface for the
WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean is
com.ibm.websphere.webcontainer.GeneratePluginConfigMBean. You can use
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 the management interface, see the Java API
document for the Liberty profile. The Java API documentation for each
Liberty profile API is available in a separate JAR file under the
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 file
of 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 web
server by using the LoadModule phrase, and specify the location of
plugin-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 to
more than one Liberty profile server, repeat the previous steps for each
additional server. Make sure that you consolidate all the plug-in configurations
into one plugin-cfg.xml file.
Note:
v If an application programmatically modifies the session cookie configuration
using Servlet 3.0 APIs, then the application needs to be initialized before
generating the plugin-cfg.xml file. Otherwise, the AffinityCookie attribute
defined for that application might be wrong. To avoid this problem, you can
set deferServletLoad to false, start the server, generate the plug-in, and then
remove the deferServletLoad attribute.
v You can use a utility named pluginCfgMerge in the full profile to merge
multiple plugin-cfg.xml files. See Configuring simple load balancing across
multiple application server profiles.
v If you are using the job manager to merge multiple plugin-cfg.xml files. See
Generating a merged plug-in configuration for Liberty profile servers using
the job manager.
Configuring session persistence for the Liberty profile
When session data must be maintained across a server restart or an unexpected
server failure, you can configure the Liberty profile to persist the session data to a
database. 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 a
database, complete the following steps.
Procedure
1. Define a shared session management configuration that you can reuse among
all of your servers. You must complete the following steps, as a minimum
requirement:
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 management
configuration.
<httpSession storageRef="SessionDB" ... />
for details about the httpSession and httpSessionDatabase elements.
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>
</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 same
database, those servers must share the same session management configuration.
Any other configuration is not supported. For example, it is not possible for
one server to use a multi-row schema while another server uses a single-row
schema.
Best Practice: If session affinity is important to your application, explicitly
define a unique clone ID for each server. In that way, you do not have to
depend on the default clone ID generated by the server, and you can be certain
that 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.properties
httpPort=9081
cloneId=s1
v ${wlp.user.dir}/servers/s2/bootstrap.properties
httpPort=9082
cloneId=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 page
97 for details about the httpSessionDatabase element.
v
No additional action is required if your server is
installed on one of the distributed operating systems. The server
automatically creates the table.
v If your server is using DB2 for session persistence, you can increase the
page size to optimize performance for writing large amounts of data to the
database.
5. Optional: If required, integrate HTTP sessions and security in the Liberty
profile. By default, after a session is created and accessed within a protected
resource with security enabled, only the originating owner of that session can
access it. Session security (security integration) is enabled by default.
6. Optional: If required, Install and configure the web server plug-in to route
requests to each of the servers you configured. The session affinity is only
maintained if your plug-in configuration specifies clone IDs that match the
clone IDs defined in the server configuration.
Connecting to the Liberty profile by using JMX
This topic describes how to access Java Management Extensions (JMX) connectors
on the Liberty profile. You can also access the secured JMX connector remotely by
using SSL.
About this task
There are two JMX connectors supported on the Liberty profile, each connector is
enabled through a different Liberty feature: localConnector-1.0 and
restConnector-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 by
the SDK in use. Currently the SDKs require that the client runs on the same host
as 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 administrator
role. In addition, SSL is required to keep the communication confidential. The
restConnector-1.0 feature already includes the ssl-1.0 feature.
Note: An application deployed on the Liberty profile has unrestricted access to its
MBeanServer directory.
Procedure
v Connect to the local JMX connector
v Connect to the REST connector
v Work with JMX MBeans
Configuring local JMX connection to the Liberty profile
You can access the local Java Management Extensions (JMX) connector on the
Liberty profile. The local connector is enabled through the Liberty feature
localConnector-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 the
SDK in use. Currently the SDKs require that the client runs on the same host as
the Liberty profile, and under the same user ID.
The following section describes how to configure and access the local connector on
Procedure
1. Enable the local connector by using the following code in the server.xml file.
<featureManager>
</featureManager>
2. Access the local connector by using the JConsole tool or JMX client that is
installed 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 JMX
MBeans on the Liberty profile on page 391.
Configuring secure JMX connection to the Liberty profile
You can access the secured Java Management Extensions (JMX) connectors on the
Liberty profile by using SSL. The secured JMX connection is enabled by the Liberty
profile feature restConnector-1.0.
About this task
The REST connector is enabled through the Liberty feature restConnector-1.0.
The following section describes how to configure and access the REST connector
on the Liberty profile.
Procedure
1. Enable the REST connector using the following code in the server.xml file.
<featureManager>
</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 profile
4. 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 system
properties as Java options and set the class path to include the connector class
files. The connector class files are packed in the clients/restConnector.jar
file.
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 SSL
configurations:
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 service
URL: service:jmx:rest://<host>:<port>/IBMJMXConnectorREST. The port
number is the HTTPS port. You must also provide the user name and
password.
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 the
administrator role mapping on the Liberty profile.
About this task
All the JMX methods and MBeans accessed through the REST connector are
currently protected by a single role named "administrator". To get started quickly,
use quickStartSecurity element to configure a single user with administrator role
and configure the default SSL configuration.
You can also use any supported user registry. You cannot use quickStartSecurity
element if you have already configured another user registry. In this case, you have
to 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>
</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" administrator
role.
<ldapRegistry id="basic" host="" port="">
<tds.properties ... />
</ldapRegistry>
<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) client
application 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 profile
through JMX programming.
Procedure
v Develop a sample JMX client as follows. The REST connector supports the
standard 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 certificates
installed with the Liberty profile might not contain the host name of where the
server is actually running. If you want to disable host name verification of SSL
certificates, you can set the system property
com.ibm.ws.jmx.connector.client.disableURLHostnameVerification to true,
which disables host name verification for all connections. To disable host name
verification on a per-connection basis, pass the property as a new environment
when creating the JMX connection:
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 environment
Map.
...
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 can
specify settings in the form of constants that have associated key values.
These keys are constants in the
com.ibm.ws.jmx.connector.client.rest.ConnectorSettings interface, and each constant
requires an integer value to specify an amount of time in milliseconds except for
the DISABLE_HOSTNAME_VERIFICATION constant, which accepts the boolean value
only.
The
com.ibm.ws.jmx.connector.client.rest.ConnectorSettings interface is a management
interface. For more information about the management interface, see the Java API
document for the Liberty profile. 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.
DISABLE_HOSTNAME_VERIFICATION
Boolean setting that disables hostname verification on the client
connections when it is enabled. This can be useful for environments where
the hostname used does not match the one specified in the server
certificate. The key for constant DISABLE_HOSTNAME_VERIFICATION is the
String
com.ibm.ws.jmx.connector.client.disableURLHostnameVerification.
MAX_SERVER_WAIT_TIME
Amount of time that the client waits for the server to become available
before the JMX connection fails and a new connection must be created. The
key for constant MAX_SERVER_WAIT_TIME is the String
com.ibm.ws.jmx.connector.client.rest.maxServerWaitTime. If the
connection is restored, any previous notification listeners are registered
again. To disable this behavior, set the value to zero.
NOTIFICATION_DELIVERY_INTERVAL
Maximum amount of time that the server waits for new notifications
before responding to a request for notifications from the client. The key for
constant NOTIFICATION_DELIVERY_INTERVAL is the String
com.ibm.ws.jmx.connector.client.rest.notificationDeliveryInterval. A
larger value results in better notification delivery times because less time is
spent establishing new connections. Normally it is not necessary to adjust
this value.
NOTIFICATION_INBOX_EXPIRY
Amount of time that the server waits before discarding notification
registrations if the client has not checked for new notifications. The key for
constant NOTIFICATION_INBOX_EXPIRY is the String
com.ibm.ws.jmx.connector.client.rest.notificationInboxExpiry.
Normally it is not necessary to adjust this value.
NOTIFICATION_READ_TIMEOUT
The value of timeout for notification fetching. Because the server might
wait up to the value of the NOTIFICATION_DELIVERY_INTERVAL constant
before responding, this value must be somewhat larger, though normally it
is not necessary to adjust this value. The key for constant
NOTIFICATION_READ_TIMEOUT is the String
com.ibm.ws.jmx.connector.client.rest.notificationReadTimeout.
READ_TIMEOUT
The value of timeout for all client communications with the server, except
notification fetching. Adjust this value if the client throws read timeout
exceptions because of a slow connection or client or server process. The
key for constant READ_TIMEOUT is the String
com.ibm.ws.jmx.connector.client.rest.readTimeout.
SERVER_STATUS_POLLING_INTERVAL
Amount of time that the client waits between checks that the server is
available again when the MAX_SERVER_WAIT_TIME value is non-zero.
Normally it is not necessary to adjust this value. The key for constant
SERVER_STATUS_POLLING_INTERVAL is the String
com.ibm.ws.jmx.connector.client.rest.serverStatusPollingInterval.
You can enable the JMX REST connector options using the system properties. For
example, for the MAX_SERVER_WAIT_TIME constant, you can use one of the following
options:
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 setting
environment.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 Management
Extensions (JMX) management beans (MBeans) on the Liberty profile. In addition,
you can register your own MBeans from an application running on the Liberty
profile.
About this task
The primary interfaces for interacting with MBeans on the Liberty profile are as
follows:
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 call
the operations of MBeans.
Procedure
v 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 a
javax.management.MBeanServerConnection instance. See Developing a JMX Java
client for the Liberty profile on page 389.
Liberty profile: List of provided MBeans:
Liberty profile provides a list of MBeans and corresponding management interfaces
that 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 the
Comments entries in this topic.
v The Management interface entries specify the name of the Java interface that
can be used to construct a proxy object for the MBean or MXBean as described
in Liberty profile: Examples of accessing MBean attributes and operations on
page 396. For more information about the management interface, see the Java
API document for the Liberty profile. The Java API documentation for each
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 remotely
invoke the Liberty server command on a target host. It has two operations,
startServer and stopServer. The parameters are explained in the API
documentation.
WebSphere:feature=restConnector,type=FileService,name=FileService
com.ibm.websphere.management.filetransfer.mbean.FileServiceMXBean
v Comments: This MXBean allows you to perform various file-related operations
on 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.jar
liberty_home/dev/ibm-api/javadoc/com.ibm.websphere.appserver.api.restConnector-javadoc.zip
The exposed operations include the ability to query certain metadata (last
modified date, size, and so on) for a given file or directory and also to query all
child files (and corresponding metadata) for a given directory. Support for
archive creation and expansion is also provided, which can be useful to
compress Liberty log files or to extract an application before deploying it.
This MXBean contains two attributes: the read list and the write list. They
represent the lists of locations that users can read or write to when using the
FileService or FileTransfer capabilities provided by Liberty. Through the
MXBean, these attributes can only be read, but they can be configured or
customized 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 a
writeLocation element is not specified, the default is the empty set.
The restConnector-1.0 feature must be included in the server.xml file in order
for this MXBean to be loaded and to honour its configuration elements
Using Liberty-defined variables is allowed with all the server-side parameters
that take a string representing a file path. Such variables are defined on the
liberty_home/README.TXT file.
WebSphere:feature=restConnector,type=FileTransfer,name=FileTransfer
com.ibm.websphere.management.filetransfer.mbean.FileTransferMBean
v Comments: This MBean allows you to perform various file-transfer operations
on 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.jar
liberty_home/dev/ibm-api/javadoc/com.ibm.websphere.appserver.api.restConnector-javadoc.zip
This MBean is registered on the PlatformMBeanServer from the same JVM that
its corresponding Liberty process is running, but it can be accessed only by
using the IBM JMX REST Connector. The connection can be local or remote, but
the REST Connector must be used.
The exposed operations include the ability to download, upload, and delete a
file. Each read and write request on the server is bound to the configurable read
and write lists that are accessed through the FileServiceMXBean. The
FileTransferMBean can also be fully accessed and operated from the built-in Java
JConsole, provided that the JConsole is connected through the IBM JMX REST
Connector.
Using Liberty-defined variables is allowed with all the server-side parameters
that take a string representing a file path. Such variables are defined on the
liberty_home/README.TXT file.
WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig
com.ibm.websphere.webcontainer.GeneratePluginConfigMBean
v Comments: See Configuring a web server plug-in for the Liberty profile on
page 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.ApplicationMBean
v 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.JvmMXBean
v 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.ServletStatsMXBean
v 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 on
page 538.
WebSphere:type=ThreadPoolStats,name=Default Executor
v Management interface: com.ibm.websphere.monitor.jmx.ThreadPoolMXBean
v 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=*
org.apache.cxf.management.counters.ResponseTimeCounterMBean
v Comments: Available when the monitor-1.0 feature is enabled. The
WebServiceStats can be either Performance.Counter.Server or
Performance.Counter.client, where service=* is the qualified name of a service
endpoint, 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.ManagedBus
v 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 each
web module there are two bus instances: one is for server and another is for
client. The instance.id=* is the instance ID of the MBean, where * is the unique
sequence number that is created by JAX-WS engine. The bus.id=* is the name of
the 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.ManagedEndpoint
feature is enabled and the JAX-WS application is accessed at least once. The
instance.id=* is the instance ID of the MBean, where * is the unique sequence
number 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 of
the 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=*
org.apache.cxf.bus.managers.WorkQueueImplMBeanWrapper
feature is enabled and the JAX-WS application is accessed at least once. For each
web module there are two bus instances: one is for server and another is for
client. The instance.id=* is the instance ID of the MBean, where * is the unique
sequence number created by JAX-WS engine. The bus.id=* is the name of the
bus, 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=*
com.ibm.websphere.messaging.mbean.MessagingEngineMBean
v Comments: Available when the wasJMSServer-1.0 feature is enabled. One
messaging engine instance is available for each Liberty profile. The name=* is the
name of the MBean, where * is the unique name of the messaging engine
MBean. See Liberty profile: Messaging on page 48.
side=com.ibm.websphere.messaging.mbean.QueueMBean,name=*
v Management interface: com.ibm.websphere.messaging.mbean.QueueMBean
v 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 the
name of the MBean, where * is the name of the queue MBean. See Liberty
profile: Messaging on page 48.
side=com.ibm.websphere.messaging.mbean.TopicMBean,name=*
v Management interface: com.ibm.websphere.messaging.mbean.TopicMBean
name of the MBean, where * is the name of the topic MBean. See Liberty
profile: Messaging on page 48.
side=com.ibm.websphere.messaging.mbean.SubscriberMBean,name=*
v Management interface: com.ibm.websphere.messaging.mbean.SubscriberMBean
name 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 the
operations of Java Management Extensions (JMX) management beans (MBeans) on
After you obtain an MBeanServer instance (for an application running on the
Liberty profile) or an MBeanServerConnection instance (for an external client), you
can access the attributes or call the operations of MBeans provided by the Liberty
profile. See Working with JMX MBeans on the Liberty profile on page 391.
The following code examples assume the variable mbs is an MBeanServer or
MBeanServerConnection instance. You can use the provided methods to access the
attributes and operations in a similar way to Java reflection. Alternatively, each
MBean has a management interface with getter methods for the attributes and
methods for the operations. You can use these interfaces via one of the
javax.managementJMX.newMBeanProxy methods or one of the
javax.management.JMX.newMXBeanProxy methods for MXBeans to obtain a proxy
object. The name of a management interface ends with MXBean. For the names
of the management interfaces, see Liberty profile: List of provided MBeans on
page 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 object
ApplicationMBean app = JMX.newMBeanProxy(mbs, myAppMBean, ApplicationMBean.class);
state = app.getState();
}
Example 2: Get response time statistics for servlet Example Servlet from
application myApp
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 object
ServletStatsMXBean 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 file
import 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 object
GeneratePluginConfigMBean 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 on
the Liberty profile, so that the MBean instance can then be used by other
applications or external administrators.
Any application can register an MBean by using an MBeanServer instance. Suppose
an application contains a class called org.example.Example that implements the
interface org.example.ExampleMBean, which defines some attributes and operations.
As in the following example, the application might simply instantiate the Example
class then register it using a unique ObjectName. If the ObjectName chosen is already
in use, a javax.management.InstanceAlreadyExistsException is reported.
import org.example.Example;
...
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 extends
java.lang.ClassLoader and provides access to any number of MBean
implementation classes. Then you can use any other JMX client, local or remote, to
create and register MBeans provided by the application. For example, suppose the
application has an MBean class org.example.ApplicationClassLoader that
performs the following tasks:
v Implements any empty interface org.example.ApplicationClassLoaderMBean
v Extends java.lang.Classloader, and
v Provides access to the org.example.Example MBean implementation class
The application can register an instance of ApplicationClassLoader to make the
Example MBean available to other JMX clients as follows:
import org.example.ApplicationClassLoader;
...
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 the
variable mbs is an MBeanServer or MBeanServerConnection instance. See Working
with JMX MBeans on the Liberty profile on page 391.
...
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 to
create the MBean by using non-default constructors.
For more information about the management interface, see the Java API document
for the Liberty profile. 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.
Establishing a JMX MBean Liberty server connection
You can use Jython-based scripts to establish a Java Management Extensions (JMX)
MBean Liberty server connection.
Procedure
1. 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 Liberty
server 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.trustStore
Sets the path to where the SSL key file is stored
JMXRESTConnector.trustStorePassword
Sets the password for the key
JMXRESTConnector.connect(host,port,user,password)
Creates a connector to the Atlas server
JMXRESTConnector.getMBeanServerConnection
Gets 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 the
MBean server by using the invoke(...) method.
Configuring HPEL in the Liberty Profile
You can configure the High Performance Extensible Logging (HPEL) log and trace
framework. Use this information as a guide for configuring HPEL in your Liberty
profile.
About this task
HPEL provides faster log and trace handling capabilities and more flexible ways to
use 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. The
bootstrap.properties file specifies properties that need to be available before the
main configuration is processed, and are kept to a minimum. The server.xml file is
the primary configuration file for the server.
The server.xml file and its associated files use a simple xml format that is suitable
for most text editors. A richer editing experience is provided by the eclipse server
adapter for liberty (WAS4D+ adapter), which uses a generated schema to provide
drop-down lists of available choices, auto-completion, and other editing tools.
The bootstrap.properties file specifies whether the server should use HPEL as the
log and trace framework, or the default log and trace framework.
You can configure HPEL through the server configuration or the
bootstrap.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 you
need to analyze problems that occur early in server start or configuration
processing. In this case, you can configure HPEL in the bootstrap.properties
file.
You can set Logging properties in either the bootstrap.properties or the
server.xml file. Use attributes in the server.xml file, or use equivalent properties
in the bootstrap.properties file. Any settings in the bootstrap.properties file are
used from the time the server reads the bootstrap.properties file until the time the
server.xml file is processed. If the logging properties in the bootstrap.properties
file are not replaced or reset in the server.xml file, the property values in the
bootstrap.properties file will continue to be used.
When HPEL is enabled, the maxFileSize, maxFiles, messageFileName,
traceFileName, and traceFormat logging element attributes are ignored (since
HPEL runs without trace.log and messages.log files). The traceSpecification
and consoleLogLevel attributes continue to be used to set the trace specification
and the level for the console log. The logDirectory attribute is ignored in cases
where the HPEL dataDirectory attribute is explicitly provided -- otherwise the
logDirectory controls the placement of HPEL files.
If you set logging or HPEL attributes in the server.xml file, you can avoid changes
in configuration between startup time and runtime by setting the corresponding
properties in the bootstrap.properties file to the same value. Note that if no logging
or HPEL properties are set in the bootstrap.properties file, the server uses the
default logging and HPEL settings.
Procedure
v 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.xml
file. The following table lists the HPEL attributes that are configurable in the
server.xml file and the equivalent properties that can be set in the
Table 14. HPEL attributes that are configurable in server.xml and the equivalent properties that can be set in
Logging
subelement 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 enable
HPEL:
The following example shows a server.xml file with the HPEL subelements. The
log content is set to expire after 96 hours, the trace content is set to retain a
maximum of 1024MB, and the text log is set for advanced format:
<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: Configuration
Results
After you restart the server, the HPEL log and trace framework will be enabled
and configured.
Setting up the server-management environment for the Liberty
profile
To set up the server-management environment for the Liberty profile, define the
appropriate features in the server.xml file.
About this task
Server management for the Liberty profile includes the following two key features:
v collectiveController-1.0
v collectiveMember-1.0
These features can be combined in various servers to define a custom management
topology.
The collectiveController-1.0 feature enables controller functionality for a
management collective and includes a management repository MBean that is
accessible using the JMX/REST connector that is provided by the
restConnector-1.0 feature. The collective controller acts as a storage and
collaboration mechanism to which collective members can connect.
The collectiveMember-1.0 feature enables a server to be a member of a
management collective, allowing it to be managed by the collective controller.
Procedure
v To enable a server to act as the management repository, define the
collectiveController-1.0 feature in the server.xml file.
<featureManager>
</featureManager>
v The collectiveMember-1.0 feature enables a server that is not a management
repository, but it enables the server to be managed by a management repository.
To enable a server for management, define the collectiveMember-1.0 feature in
the server.xml file.
<featureManager>
</featureManager>
Tip: All collectiveController-1.0-enabled servers are also managed; therefore,
you do not need to specify collectiveMember-1.0 if you already have
collectiveController-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 time
in order to efficiently and accurately deliver application services to your
organization.
About this task
A Liberty collective is a set of Liberty servers that are configured as part of the
same administrative and operational domain.
Configuration and state data about a Liberty collective is housed in an active
operational repository.
Membership in a Liberty collective is optional. Liberty servers join a collective by
registering with a collective controller to become members. Members share
information 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.
Procedure
1. 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>
</featureManager>
host="localhost"
httpPort="9080"
httpsPort="9443" />
<featureManager>
</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>
</featureManager>
host="localhost"
httpPort="9081"
httpsPort="9444" />
<featureManager>
</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 should
look ike this example:
[1/31/13 11:17:47:699 CST] 0000002e nt.repository.member.internal.publisher.ServerPathsPublisher I CWWKX8114I:
The servers 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 servers 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 collective
controller. Most server host information can be automatically detected. In certain
scenarios, however, you must provide additional host information so that the
collective controller can establish a connection to the server.
To enable the host information override, add the following element to the
server.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"/>
rpcUser
This parameter specifies the user ID that the collective controller will use to
connect to the server.
If this value is not specified, the default value is
System.getProperty("user.name").
rpcUserPassword
This parameter specifies the password for the specified user ID.
If this value is not specified, the server will either generate an SSH key pair or
use the SSH key pair for the connection that is specified using the
privateKeyPath and publicKeyPath parameters. If SSH is not installed on the
server (such as on a Windows or OS/400
operating system), the password is

required.
rpcUserHome
This parameter specifies the home directory of the user.
If this value is not specified, the default value is
System.getProperty("user.home").
If userId is specified, you should specify userHome.
sudoUser
If this value is specified, it allows the collective controller to execute
commands as another, or "sudo", user instead of as the user ID used for the
connection.
This parameter is applicable only to servers that have an SSH server installed.
This parameter has no default value.
sudoPassword
This parameter specifies the password for the sudo user specified by the
sudoUser parameter.
This parameter is applicable only to servers that have an SSH server installed.
rpcPort
The 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.
sshPrivateKeyPath
This parameter specifies the path and file name of a user-specified private key
file.
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 be
generated.
sshPublicKeyPath
This parameter specifies the path and file name of a user-specified public key
file.
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 be
generated.
sshPrivateKeyPassword
This 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 to
start or stop a collective member.
Prerequisites
v 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 and
password.
<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 are
used for authentication by default. A pair of RSA keys are generated on server
startup under ${server.config.dir}/resources/security/ssh. The public key is
added to the user's authorized_keys file automatically. The private key is sent to
the controller.
<hostAuthInfo rpcHost="member_host_name"/>
If you would like to use a username and password for authentication, specify them
in 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 a
Liberty collective on page 402.
For information on running the ServerCommands MBean from the controller, see the
API documentation for the ServerCommands MBean.
See Liberty profile: Overriding server host information on page 404 for more
details.
Setting the default host name of a Liberty server
You can add the defaultHostName variable to the server.xml file to set the default
host name by which a Liberty server is identified.
About this task
This variable is available for use by service configurations. Setting this value is
particularly important for multihomed systems (with multiple NICs and multiple
mapped 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 the
defaultHostName 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 null
response.
v A collective member is restricted to modifying only its own information in the
repository. Authenticated administrative users have unrestricted access to
information in the repository except as noted above.
Administering data access applications on the Liberty profile
The Liberty profile provides support to the data access applications using Liberty
features such as jdbc-4.0 and other features.
Procedure
v Configure database connectivity on the Liberty profile.
v Configure connection pooling for database connections
v Configure database transaction recovery
Configuring database connectivity in the Liberty profile
You can configure a data source associated with different JDBC providers for
database connectivity. The JDBC providers supply the driver implementation
classes 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. Data
sources 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 that
enhances connection pooling, and cannot participate as a two-phase capable
resource in transactions involving multiple resources.
v javax.sql.ConnectionPoolDataSource
This type of data source is enabled for connection pooling. It cannot participate
as 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 to
participate as a two-phase capable resource in transactions involving multiple
resources.
In order to be usable in the Liberty profile, your JDBC driver must provide at least
one of these types of data sources. For the commonly used JDBC drivers, the
Liberty profile is already aware of the implementation class names for the various
data source types. You only need to tell the Liberty profile where to find the JDBC
driver.
Procedure
1. 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 of
data source, the Liberty profile chooses in the following order depending on
which 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 vendor
properties 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"/>
<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
4. Optional: Configure data sources for commonly used databases according to
the following examples.
For DB2
<dataSource id="db2" jndiName="jdbc/db2">
</dataSource>
</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>
<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>
<fileset dir="C:/db-derby-10.8.1.2-bin/lib"/>
</library>
For Informix JCC
<dataSource id="informixjcc" jndiName="jdbc/informixjcc">
<properties.informix.jcc databaseName="SAMPLEDB" serverName="localhost" portNumber="1526"/>
</dataSource>
<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"
</dataSource>
<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"
</dataSource>
<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 of
javax.sql.XADataSource named com.ibm.sample.SampleXADataSource.
The JDBC driver also provides vendor-specific data source properties
such 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 different
ways.
You configure a data source by specifying the attributes of the dataSource element
in the server.xml configuration file. If you change these attributes for a running
server, the updates are applied at different times and in different ways, depending
on which attribute is changed. The following table describes, for each attribute of
the 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 the
attributes of the dataSource element. The second column describes, for each attribute, how the configuration update
is 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 data
source is then managed by the new connection manager.
connectionSharing The update is applied with each first connection handle in a
transaction.
isolationLevel The update is applied with new connection requests; current
connections retain their isolation level.
jdbcDriverRef All connections and the connection pool are destroyed. The new
JDBC driver is then used.
jndiName All connections and the connection pool are destroyed. The new
JNDI name is then used.
propertiesRef If the data source is Derby Embedded, all connections and the
connection pool are destroyed before new properties go into
effect. For other JDBC drivers, the new properties go into effect
with new connection requests.
queryTimeout The update is effective immediately.
recoveryAuthDataRef Authentication data for transaction recovery. All connections
and the connection pool are destroyed. The new recovery
authentication data is then used.
statementCacheSize The statement cache is resized upon next use.
supplementalJDBCTrace All connections and the connection pool are destroyed. The new
setting is then used.
syncQueryTimeoutWithTransactionTimeout The update is effective immediately.
transactional The update is applied to new connections and existing
connections not in use from the connection pool.
type All connections and the connection pool are destroyed. The new
setting is then used.
Liberty profile: Application-defined data sources:
You can define a data source within your application, through annotations or in
the deployment descriptor, as defined by the Java EE specification.
This capability is limited to names in java:comp. Other namespaces
such as java:module, java:app, and java:global are not available.
When defining a data source in an application, the JDBC driver must be made
available to the application. This is accomplished by configuring a shared library in
the server.xml for your application.
For example:
<application id="myApp" name="myApp" location="myApp.war" type="war">
<classloader commonLibraryRef="DB2Lib"/>
</application>
<library id="DB2Lib">
</library>
Then, you can define a data source in your application either through annotations
or 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 a
web.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 in
the server.xml files can also be specified on application defined data sources.
However, you cannot specify properties that refer to other elements, such as
connectionManagerRef and jdbcDriverRef, because the application defined data
source implicitly defines the connection manager and JDBC driver. When using
application defined data sources for two-phase commit, you can specify the
recoveryAuthDataRef property to select the authentication data that is used for
transaction recovery. However, it is important to be aware that recovery of
transactions is only possible while the application is running. You can use
variables, encoded passwords, and duration syntax in application defined data
sources.
Note: The duration syntax does not apply to properties that are explicitly defined
in 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 = {
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" }
),
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 a
connection manager for it.
Example
The following example code uses the connectionManager element in the server.xml
file 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 not
defined on the connection manager element. If a connection manager is not
defined 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 for
applications on multi-threaded systems. See Chapter 12, Tuning the Liberty
profile, on page 543.
You can define multiple data sources and associate each with a different connection
manager. However, you cannot associate multiple data sources with a single
connection 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 is
running, the updates to different attributes are applied at different times and in
different ways.
You configure a connection pool by specifying the attributes of the
connectionManager element in the server.xml configuration file. If you change
these attributes for a running server, the updates are applied at different times and
in different ways, depending on which attribute is changed. The following table
describes, for each attribute of the connectionManager element, how a configuration
change is applied at run time.
Table 16. How connection manager configuration updates are applied at run time. The first column of the table lists
the attributes of the connectionManager element. The second column describes, for each attribute, how the
configuration 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 greater
than zero.
Because updates to the connection manager are effective immediately, errors might
occur if you make changes with active connections; including the potential risks
for the connections to be ended prematurely.
Liberty profile: How database transactions are recovered:
Support for transactions is provided by the transaction service. Recovery can occur
either when the transaction service is first used, or at server startup. When
recovering any in-doubt database transactions, the Liberty profile transaction
manager uses either the unique identifier or the JNDI name to locate the current
dataSource element.
By default, transaction recovery after a server failure happens when the transaction
service is first used (at first lookup of a UserTransaction), rather than at server
startup. This behavior can be altered by using a pair of configuration attributes for
the transaction service. These attributes control when recovery happens, and
whether the system waits for recovery to finish before allowing transactional work
to proceed. You set these attributes in the server.xml file. For example, the
following settings specify that recovery should occur at server startup, and that the
server should wait for recovery to finish before allowing transactional work to
proceed:
<transaction
recoverOnStartup="true"
waitForRecovery="true"
/>
You configure a data source by specifying the attributes of the dataSource element
in the server.xml configuration file. You also assign a unique identifier or a
jndiName 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 is
pending for a transaction in which the data source participated. If you make
changes to any other attributes of the dataSource element, those changes are
honored for the recovery. This enables you to, for example, add a
recoveryAuthDataRef attribute that specifies a database user ID and password to
use for recovery.
The database user ID and password to use for recovery are determined according
to 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 and
password from the container managed authentication alias are used. For
example:
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 any
user ID and password, then the behavior is determined by the JDBC driver and
database.
Note: If the transaction recovery is performed by an application-defined data
source, such as an @DataSourceDefinition annotation or a <data-source> element
in the deployment descriptor, you have to make sure the application is running for
the data source when the recovery is happening. Configurations in the server.xml
file 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 a
MongoDB instance, the applications use the MongoDB Java driver and data
sources that you configure for the server.
Before you begin
Note: The Liberty profile provides configuration support for
MongoDB. MongoDB (from humongous) is a scalable, high-performance, open
source 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 the
MongoDB Java driver and a library reference to the shared library in the
server.xml file of the Liberty profile. An application can access MongoDB directly
from the application or through the mongo feature and mongoDB instance
configurations in the server.xml file.
Procedure
1. 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.xml
file 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 application
element 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 Java
Naming and Directory Interface (JNDI) lookup or use resource injection to
access 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>
</featureManager>
b. Configure a library reference for the shared library in the server.xml file.
The library reference creates a connection to MongoDB. The following
example shows a simple library reference:
<mongo id="mongo" libraryRef="MongoLib" />
The following example shows a more complex library reference that
configures 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 runtime
to 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 lookup
DB lookup = (DB) new InitialContext().lookup("java:comp/env/mongo/testdb");
...
d. If you are using JNDI lookup, add a resource environment reference to
the 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 MongoDB
configuration element.
Configuring secure MongoDB connections in the Liberty profile:
You can configure application-managed or container-managed security for
MongoDB connections in the Liberty profile.
Before you begin
Enable your application to use MongoDB. See Creating Liberty applications that
use MongoDB.
About this task
You can secure MongoDB applications by using application-managed security or
container-managed security. For both types of security, the MongoDB server must
be 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 password
attributes, the product assumes that an application is either using
application-managed security or is not using security. To enable
application-managed security, the application must authenticate using the
MongoDB 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 specify
a user and password. Only one user is allowed for each mongo configuration. All
MongoDB instances use the specified user and password. For example, all
MongoDB instances that reference mongo1 in the following example use
mongoUserName 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 call
com.mongodb.DB.authenticate(user, pass).
What to do next
Ensure that the MongoDB server is running, and then test the MongoDB security
from your application.
Connecting to a distributed set of MongoDB instances:
Accessing data that is stored in a distributed set of MongoDB instances is nearly
the same procedure as connecting to a single MongoDB instance.
Before you begin
Enable your application to use MongoDB. See Creating Liberty applications that
use MongoDB.
About this task
When you configure the mongo feature in your server.xml file, you can pass a
collection of hostNames and ports that are either replica set members or sharded
mongos servers.
If the host:port combinations are replica set members, the client finds all members
and 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 the
closest 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 profile
The Liberty profile provides support to the web applications using Liberty features
such as servlet-3.0, jsp-2.2, and other features.
Procedure
Specify when servlets are loaded and initialized.
Specifying when servlets are loaded and initialized
By default, the Liberty profile defers servlet loading until a request is received for
the associated web application. You can override this default behavior by
specifying the web container deferServletLoad attribute to false.
About this task
The servlet specification defines the load-on-startup servlet attribute, which is
specified in the web.xml file of a web application. If a servlet has a non-negative
value for the load-on-startup attribute, the servlet must be loaded and initialized
when the web application is deployed. The Liberty profile optimizes server start
time and memory use by not starting a servlet until a request is received for the
web application. You can override this deferral so that your servlets are loaded and
initialized when the web application is installed, rather that waiting for the first
request for the application.
Example
To configure the server to load servlets when a web application is installed, add
the 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 Liberty
profile 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 to
install features to the built-in usr product extension, and how to use your
features in an application server. The Liberty profile provides various System
Programming Interfaces (SPIs) that you can use to extend the runtime
environment; you can also use more advanced features such as operating the
Liberty profile server from your Java applications programmatically. The Java API
documentation 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 Liberty
profile: 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 capability
when 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. This
example makes a library available to applications so that the external packages are
visible on the default application class path. By copying the feature manifest into
the ${wlp.user.dir}/extension/lib/features directory, and the OSGi bundle into
the ${wlp.user.dir}/extension/lib directory, the feature can be installed to the
Liberty 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 manifest
files 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 a
Liberty 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 that
you want to expose to applications. Bundle-SymbolicName is the only required
header; this entry specifies a unique identifier for a bundle, based on the
reverse domain name convention. It is good practice to specify a version for the
bundle, and in this example some Java packages are exported for application
use:
Bundle-SymbolicName: com.usr.samplebundle
Bundle-Version: 1.0.1
Export-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 the
feature 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 any
other feature that is installed to the user product extension. To make one or
more SPI packages available to features in other product extensions, list the
packages in the IBM-SPI-Package header.
Subsystem-ManifestVersion: 1.0
Subsystem-SymbolicName: sample-1.0; visibility:=public
Subsystem-Version: 1.0.0.qualifier
Subsystem-Type: osgi.subsystem.feature
Subsystem-Content: samplebundle; version="[1,1.0.100)"
IBM-Feature-Version: 2
IBM-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 the
feature 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 name
to 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 OSGi
bundles that provide classes and services corresponding to a particular capability
in the Liberty profile runtime environment. You can find the introduction of the
format 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 metadata
format in the OSGi Enterprise R5 specification. A feature is defined by a feature
manifest file (.mf file) that is stored in the lib/features directory, and must use a
custom 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 first
column shows a list of headers, the second column shows the description of each header.
Header Description Required?
Subsystem-ManifestVersion The version format for the
feature manifest file. Must be set
to 1.
Yes
Subsystem-SymbolicName The symbolic name of the
feature and any attributes or
directives.
Yes
Subsystem-Version The version of the feature. See
the OSGi core specification
section 3.2.5 for the details of
how this is defined.
Yes
Subsystem-Type The subsystem type for the
feature. All features are currently
of the same subsystem type:
osgi.subsystem.feature.
Yes
Subsystem-Content The subsystem content of the
feature. This is a comma
separated list of bundles and
subsystems that are required to
run this feature. If you want to
allow the auto feature to be
configured in the server.xml
file, you must have the
capability header containing the
required features, and also have
them defined in the subsystem
content.
Yes
IBM-Feature-Version The version of this subsystem
type. Must be set to 2.
Yes
IBM-Provision-Capability The capability header that
describes whether a feature can
be provisioned automatically.
No
IBM-API-Package The API packages that are
exposed to applications by this
feature, features in other product
extensions, and the Liberty
kernel.
No
IBM-API-Service The OSGi services that are
exposed to OSGi applications by
this 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 first
column shows a list of headers, the second column shows the description of each header.
Header Description Required?
IBM-SPI-Package The SPI packages that are
exposed by this feature to
features in other product
extensions, and the Liberty
kernel.
No
Subsystem-SymbolicName
The syntax for this header matches the Bundle-SymbolicName syntax for a bundle. It
has a symbolic name that follows the package names style syntax, and can
optionally 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 features
that 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 the
developer tools, for use in the server.xml file, and output in messages.
protected - Feature considered to be SPI. The feature is not supported by the
developer tools, for use in the server.xml file, or output in messages. The
feature is provided so extenders can make use of it to build higher level
features.
private - (default) The feature is product internals. The feature is not
supported for use in the server.xml file or to be referenced by extender
features. 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. If
the feature is available only to trusted parties, it must be protected. If the feature
is 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 uses
the 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 or
Subsystem-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 to
indicate 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.
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. By
default it maps to a start level of 12.
APPLICATION - This value indicates the latest phase when applications are
started.
Bundles can also be defined to start just before or just after these phases by
adding _LATE to be later, or _EARLY to be earlier than the key phase. So if you
want to run immediately after the container phase, use CONTAINER_LATE, and if
you 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 the
manifest, and they describe other features that must be installed for this feature to
work. When any features are configured in the server.xml file, the FeatureManager
checks to see whether any auto features have had their capabilities satisfied, and
if any have, they are automatically activated.
The format of the IBM-Provision-Capability header uses standard OSGi LDAP
filters.
In the following example, if features requiredFeature1-1.0 and
requiredFeature2-1.0 are configured, then this auto feature must be automatically
activated. 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 and
requiredFeature2-1.0 are configured, then this auto feature must be automatically
activated. When neither of these features is present in 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=requiredFeature2-1.0)))"
IBM-API-Package
This header is used to indicate which API packages are visible to applications. It
matches the Export-Package header syntax. This means it is a comma separated list
of API packages, but each API package can have some attributes.
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 API
package will not be available to applications and, furthermore, none of the API
packages in this feature will be available to OSGi applications.
v type - The type of API package. The type attribute takes one of the following
values:
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 OSGi
applications. The feature must also register the service in the OSGi service registry.
It has the following syntax
IBM-API-Service ::= service ( , service )*
service-name ::= unique-name ( ; unique-name )*
The service-name is the Java class or interface name of the service. The attributes
are interpreted as the service properties for the services.
IBM-SPI-Package
When you create your own Liberty feature, you install it into the user product
extension. All the packages in your feature can be accessed by any other feature
that is installed into the user product extension. However, if you want a package in
your feature to be accessed by a feature that is installed into another product
extension, 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 bundle
in the Liberty feature, by being listed in the Export-Package header of the bundle
manifest 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 version
attribute 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. The
public visibility attribute allows this feature to be directly specified in server
configuration (server.xml) files; it will also be included in the drop down list of
features that are displayed in Server Configuration view of the developer tools
and 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 can
be 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 the
server runtime environment. The single API package, com.example.publicapi, will
be visible to all applications in that server, except for Java EE applications that are
configured to not have visibility to the api package type. OSGi applications must
explicitly 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 feature
code in the server, as will the API package.
IBM-Feature-Version: 2
Subsystem-ManifestVersion: 1.0
Subsystem-SymbolicName: exapmple-1.0;visibility:=public
Subsystem-Version: 1.0.0.qualifier
Subsystem-Type: osgi.subsystem.feature
Subsystem-Content: com.example.bundle1;version="1.0.0"
Manifest-Version: 1.0
IBM-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 own
features and install them into an existing Liberty profile server, or to package them
for 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 Application
Server Liberty profile version 8.5.5 or later.
You add OSGi bundles that contain classes and services that implement the
function provided by your Liberty feature. If your feature provides any API
packages to OSGi applications, or SPI packages to features in other product
extensions, 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 over
an existing WebSphere Application Server Liberty profile to extend its capabilities.
For more information on creating Liberty features, see Liberty profile: Product
extension on page 22.
Creating a Liberty feature by using WebSphere Application Server Developer Tools
is described in more detail in the following subtopics:
Procedure
1. 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 developer
tools, you must create a Liberty feature project in your workspace.
About this task
A Liberty feature project contains classes and services that implement the function
provided 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 your
workspace 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 bundle
projects.
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. The
classes and services implement the functions that the Liberty feature provides. You
can include OSGi bundles in a Liberty feature that was created with the
WebSphere Application Server Developer Tools by adding the bundles to the
corresponding 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 add
to the Liberty feature project. For information on creating an OSGi bundle, see
Creating OSGi bundle projects.
3. (Optional) Specify the version range for the contained bundle by selecting the
bundle, clicking Properties, and entering the required values in the Minimum
Version and Maximum Version fields.
4. (Optional) Use the Location field in the Properties dialog box to specify the
location where you want the bundle to be packaged when exported, relative to
the Liberty profile installation folder. If you want the bundle to be packaged in
more than one location, enter the locations as a comma-separated list. By
default, 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 Liberty
feature, 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 share
as an API or SPI with other applications and features in the Liberty runtime
environment.
About this task
A package cannot be declared as an API or SPI unless it is exported by a bundle in
the Liberty feature, by being listed in the Export-Package header of the bundle
manifest file.
Procedure
To specify API and SPI packages for 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. 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 other
feature that is installed into the user product extension. To make one or more
SPI packages available to features in other product extensions, click Add in the
IBM SPI Packages pane.
4. (Optional) Specify the package version by selecting the package, clicking
Properties, and entering the required value in the Version field.
5. (Optional) For an API package, select the package type from the Type list in the
Properties 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-Package
headers in the feature manifest file. For more information on the headers in the
feature manifest file for a Liberty feature, see Liberty feature manifest files on
page 421.
Installing a Liberty feature to the Liberty profile
When you develop a Liberty feature by using the WebSphere Application Server
Developer Tools, you create a Liberty feature project that packages the Liberty
feature in a compressed file. To install the Liberty feature, you must extract the
contents 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
.
.
.
/features
manifest 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 is
to implement the org.osgi.framework.BundleActivator interface in one of the
classes within your bundle. When the server starts and stops the bundle, the start
and stop methods of the BundleActivator interface are called.
About this task
If you are using the WebSphere Application Server Developer Tools, create an
OSGi bundle project, and create an OSGi BundleActivator class in that project.
Then identify your bundle activator class to the OSGi framework by adding the
Bundle-Activator header to the bundle MANIFEST.MF file. For example:
Bundle-Activator: com.example.bundle.Activator.
Example
package 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 ManagedService
interface
Liberty profile configuration is managed by the OSGi Configuration Admin service
and can be accessed according to the OSGi Configuration Admin service
specification. 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 is
used as the element name, with a component that registers to receive the
properties.
About this task
For an OSGi bundle whose lifecycle is managed by using the BundleActivator
interface, a straightforward way to receive the configuration properties is to
implement the org.osgi.service.cm.ManagedService interface, which specifies the
PID as one its properties.
Example
In this example, the Activator class implements the ManagedService interface in
addition to the BundleActivator interface, and receives configuration properties by
using the updated method. You can provide default property values to simplify
what 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 configuration
ServiceRegistration<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.xml
file, or an included file, by the following entry:
<simpleBundle color=red flavor=raspberry />
Note: The element name in the user configuration, simpleBundle matches the value
of the org.osgi.framework.Constants.SERVICE_PID property used in the
ManagedService registration.
For more advanced configuration use, see Providing descriptions
and default values for configuration metadata on page 439.
Working with the OSGi service registry
You can create an object and register it as an OSGi service for use by third-party
features that are deployed to the Liberty profile.
About this task
Services are the OSGi lightweight and flexible component model. When you create
services and wire them together with Java code, you can use mechanisms such as
ServiceTrackers to help find the services that you want, and Declarative Services
(DS) and Blueprint to specify the wiring declaratively. The Liberty profile has
standardized on using DS for wiring, except for a small number of cases where
extra flexibility is required.
Registering OSGi services:
You can create an object and register it as an OSGi service for use by third-party
features.
About this task
By using plain old Java code, you can create an object, and then register it as a
service using the BundleContext class. Because the code has to run, you typically
register the object in a BundleActivator interface. When you register the object,
you can specify what interfaces it provides, and supply a property map. A
ServiceRegistration object is returned; if necessary, you can use the
ServiceRegistration object to change the properties at any time. When the service
is completed, you use the ServiceRegistration object to unregister the service.
To obtain a service, you query the BundleContext for a service that implements a
required interface and, optionally, supply an LDAP-syntax filter to match the
service properties. Depending on the method you call, you can retrieve the best
match or all the matches. You can then use the returned ServiceReference that
provides the properties to do further matching in your code. You can use the
ServiceReference to get the actual service object. When you have finished using
the 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.
/**
* 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.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 interface
sr = bundleContext.registerService( Foo.class, foo, serviceProperties );
//or
//untyped service registration with one interface
sr = (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 time
sr.setProperties( serviceProperties );
}
public void unregisterFoo() {
//when you are done unregister the service using the service registration
sr.unregister();
}
}
4. Obtain and return the service from another class:
import java.util.Collection;
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 theres 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 {
//were done
bundleContext.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 {
//were done
bundleContext.ungetService( sr );
}
}
}
Using OSGi services:
Services can be registered and unregistered asynchronously at any time. Therefore
you should call a service for as short a time as possible. You can use the
ServiceTracker class to track service availability concurrently.
About this task
If you want to track services, you can create a ServiceTracker object by using your
bundle context, the interface you want, and the properties you want to match, and
then 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 to
tell the tracker you are done; the tracker caches the matching services internally,
and clears them as they are unregistered. When you have finished using the
tracker, use the serviceTracker.close() method to close it.
Example
The following example shows how to use a ServiceTracker object to track a
service:
package com.ibm.foo.tracker;
import com.ibm.foo.simple.Foo;
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 dont use it for long.
}
public void shutdown() {
serviceTracker.close();
}
}
Composing advanced features by using OSGi Declarative
Services
Simple features can be controlled by using bundle activator classes and direct
implementation of interfaces such as ManagedService and ServiceTracker. As
relationships between bundles become more complex, it can be better to use
facilities like OSGi Declarative Services (DS) to decompose a feature into individual
services. 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 of
advantages:
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 start
quickly and to keep resource use to a minimum.
v A reference to the service is placed into the service registry, even when the
service has not been activated, so that dependencies on the service can be
resolved.
v Dependencies on other services can be injected at runtime, and activation of the
various 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 a
number of online resources, including the OSGi Community Wiki.
This task provides simple descriptions of how to declare your services to DS, how
to obtain references to other services, and how to manage configuration properties
for each service.
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 of
which is defined by an XML file in the bundle. When a bundle containing
component declarations is added to the framework, DS reads each component
declaration and registers provided services in the service registry. DS then manages
the lifecycle of the component: controlling its lifecycle based on a combination of
declared attributes and satisfied dependencies.
The XML description of components allows DS to resolve service dependencies
without requiring the component to be instantiated, or its implementation classes
to be loaded. This facilitates late and lazy resource loading, which helps improve
server startup and reduce runtime memory footprint.
The XML files that describe the components are listed in the MANIFEST.MF file of the
bundle 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; the
following examples show the XML itself.
This topic describes a simple OSGi bundle using XML to declare its components to
DS.
Procedure
1. 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 the
bundle is started.
<component>
<service>
<provide interface="com.example.HelloService"/>
</service>
</component>
3. Name the component. The component name also acts as the service persisted
identity, or PID, which is used to associate configuration properties with the
service. Configuration properties with a matching PID will be injected into the
component on activation, and whenever the properties are updated.
<component name="HelloService">
<service>
<provide interface="com.example.HelloService"/>
</service>
</component>
Note: In the Liberty profile, a user can add the following element to the
server.xml configuration file, and the properties will be injected into the
HelloComponent 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, and
you add a header to the bundle manifest MANIFEST.MF file so that DS can locate
the file:
Service-Component: OSGI-INF/HelloService.xml
If multiple components are packaged in the same bundle, the corresponding
XML 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 a
persisted identity, and code the service to receive the data. You can also provide
descriptions and default values for this data, and make the labels and descriptions
available in several languages.
About this task
To enable a service to receive configuration data, there are a number of steps
involved. Only associating the service with a configuration Admin persisted
identity and coding the service to receive configuration properties are mandatory,
and might be considered sufficient for embedded scenarios. The remaining steps
improve the configuration experience for users.
The steps involved in enabling a service to receive configuration data are described
in the following subtopics:
Procedure
1. 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 as
described in the OSGi Configuration Admin specification by using the the
persisted identity (PID).
About this task
The OSGi Configuration Admin specification provides a number of association
mechanisms, of which the following are most commonly used in the Liberty
profile:
Register an implementation of org.osgi.service.cm.ManagedService or
org.osgi.service.cm.ManagedServiceFactory directly with the OSGi Configuration
Admin service (CA)
This is most commonly used in low-level kernel bundles, where service
management through OSGi Declarative Services (DS) or Blueprint is not
available at bundle start time. The registration specifies the PID that
identifies the configuration set to be received.
Define a service to DS
This is the most common way for services in feature bundles to receive
their configuration. The service name is used as the PID to associate
configuration data. DS receives the configuration set from CA and passes it
on 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 developer
instead 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 PID
for the association of configuration data. If this component does not provide any
metadata to describe its configuration, you can specify configuration properties for
the component by using that PID in the server.xml file, or an included file, by
defining 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 and
when the configuration is modified.
Coding the service to receive configuration properties:
Configuration properties are available through the
org.osgi.service.component.ComponentContext object that is provided on the
activation method.
Before you begin
You must complete the task described in Associating a service with a persisted
identity on page 437.
About this task
If properties are updated after activation has occurred, the method used for
injection depends on the context that the service provides in its OSGi Declarative
Services (DS) declaration.
Generally, it is best to declare a method that is to be used specifically for injection
of updated properties by using the modified attribute on the service declaration. If
a modified method is not available, DS deactivates and then reactivates the service
with the new properties.
Deactivating and then activating a service can also cause dependent services to be
recycled, and should be avoided unless specifically required. Using the modified
attribute 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 modified
methods 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 following
mechanisms 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 of
user configuration is not necessary.
v Ignore redundant or unrecognized properties.
The service must be able to operate on the default configuration alone. To provide
a 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 that
complies with the OSGi Metatype Service specification. The resulting XML file is
packaged into the bundle in the OSGI-INF/metatype directory, in accordance with
the specification.
About this task
The metadata for the configuration properties of a service includes the persisted
identity (PID) for the configuration set, and the identifier (unique key), data type
and default value for each property. These attributes are used by the Liberty profile
configuration parser, along with user-provided additions and overrides, to
populate the Configuration Admin service (CA) with the initial configuration.
The metadata can also include user-friendly names and descriptions for each
attribute, which can be used by administrative clients, for example to build an
administrative interface.
The existence of configuration metadata is optional; configuration sets and
individual properties that have no metadata description are fully supported by the
configuration system in the Liberty profile, and are still parsed from the user
configuration file and injected into the owning component. However, it is useful to
provide localized metatype descriptions so that developer tools and administrative
client applications can provide the best possible user configuration experience.
Object component definitions (OCD) can have the ibm:extends attribute. This
attribute takes a string value, which is the factory PID of another OCD. This
attribute is a method of providing a more specialized representation of the
referenced factory. The presence of the ibm:extends attribute means that any
attribute definitions from the extended OCD are inherited on the extending OCD.
It is also possible to override attribute definitions in the extending type. For
example:
<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 factory
PID, but must not register the associated ManagedServiceFactory or DS component,
due to the configuration being delegated to the factory PID defined on the
extended type.
Attribute definitions can have the ibm:rename attribute. This attribute applies to
attribute definitions that are defined in OCD elements that extend another OCD,
by using the ibm:extends attribute for example. The ibm:rename attribute takes a
string value, which is the identifier of the attribute definition on the extended OCD
to be renamed.
Note: An attribute definition cannot be specialized further on other OCDs by
using 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:
<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 appropriate
data types should be specified in the metatype description; for example, a Boolean
data type for disableJspRuntimeCompilation. This provides a better level of
validation of user-entered configuration, and causes the values to be provided to
the consuming service as those data types.
The following example shows a defining webApplication as a specialization of
application:
<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 configuration
properties of attr1=newFixedValue, attr2=10, attr3=3, attr4=anotherValue to
the qualified.id1 factory.
v <mySpecializedConfig attr1="replaceFixedValue"/> would result in passing
configuration properties of attr1=newFixedValue, attr2=1, attr3=3,
attr4=anotherValue to the qualified.id1 factory, and issue a warning that attr1 is
final 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, and
the translated strings packaged into language-specific properties files.
Example
The following example shows how the location of the localized files is specified in
the 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, if
the 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/metatype
directory, the translated files can be in any location that is within the bundle and
specified by the localization attribute. Do not put them in the OSGI-INF/metatype
directory alongside the metatype XML file, because the Equinox implementation of
the Metatype Service specification attempts to parse anything in that location as an
XML file, and although that does not cause a failure, it generates unwanted
exceptions in the console, and wastes time. The Liberty profile convention is to put
them 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 a
percent sign at the start of the value. For example, you might use the following
definition 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 timeout
client.inactivity.timeout.desc=The maximum duration, in seconds, between transactional requests
from a remote client. Any period of client inactivity that exceeds this timeout results in the
transaction being rolled back in this application server.
Liberty profile: Resource location symbols
Liberty user configuration is made more portable through the use of variables that
represent symbolic locations. Use of these variables helps to prevent the coding of
absolute paths that would make the user configuration brittle and less portable.
Feature code that receives configuration properties might have to deal with values
that contain such variables.
The location service of the Liberty profile can be used to resolve symbolic locations
to physical resources. For example, the symbolic location ${wlp.install.dir}/
myFile can be mapped to the local file myFile in the installation directory of the
Liberty profile. Most methods return a WsResource object that wraps the physical
resource, but you can also use the resolveString method to transform the
symbolic location into a String that can be used to obtain a File object.
The name of the location service is
com.ibm.wsspi.kernel.service.location.WsLocationAdmin. The Java API
documentation 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 defines
symbols 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 and
properties on page 89.
Monitoring local files for changes
The Liberty profile has highly dynamic behavior, responding to changes in
configuration, applications and other resources. Much of this dynamic behavior is
based on monitoring of the local file system for changes. The service that performs
this monitoring is available to all Liberty features through the FileMonitor SPI.
About this task
The FileMonitor SPI provides different properties to specify what resources are
monitored and with what frequency. You have to implement the FileMonitor
interface and register the implementation class into the service registry.
The Java API documentation for each Liberty profile SPI is available in a separate
JAR 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 Liberty
profile
You can use the tracing and logging mechanism of the Liberty profile for Liberty
features.
About this task
The Liberty profile provides the following SPIs for integrating tracing and logging
in 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 separate
JAR 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, called
myfeature, 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.TraceComponent
class.
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 the
implementation class with the trace manager that is provided by the Liberty
profile. Then, you can configure the trace manger to track the DS methods of
the 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 the
message 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 the
Liberty profile.
About this task
Security in the Liberty profile supports all the Servlet 3.0 security features and
secured Java JMX connections. The following Liberty features are applicable to
security 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/config
directory of the server image for reference when configuring security for your
applications on the Liberty profile.
Best practice: When you use the developer tools to configure the security on the
Liberty profile, make sure that the configuration created by the tools is similar to
the examples in the ${wlp.install.dir}/templates/config directory of the server
image. This directory includes examples of configuring some of the most common
security features. If you see any differences in the configuration created by the
developer tools and the examples, modify the configuration to fit the configuration
in the examples for that feature.
Procedure
v Use quickStartSecurity for minimal security configuration
v Secure communications with the Liberty profile
v Access a secured JMX connector on the Liberty profile
v Authenticate users in the Liberty profile
v Authorize access to resources in the Liberty profile
v Secure a database access application
v Develop extensions to the Liberty profile security infrastructure
Getting started with security in the Liberty profile
You 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 profile
server and web application. Additionally, configuration actions within the Liberty
profile are dynamic, which means the configuration updates take effect without
having to restart the server.
Procedure
1. Create and start your server.
v
Windows
On Windows systems:
server.bat create MyNewServer
server.bat start MyNewServer
v
Linux
On all systems other than Windows systems:
server create MyNewServer
server 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>
</featureManager>
3. Define the user name and password that is to be granted the Administrator
role for server management activities.
<quickStartSecurity userName="Bob" userPassword="bobpwd" />
Note: Choose a user name and password that are meaningful to you. Never
use the name and password in the example for your applications.
4. Configure the deployment descriptor with the relevant security constraints to
protect 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 the
application is protected by the testing role.
<!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 the
application:
<application type="war" id="myWebApp" name="myWebApp"
location="${server.config.dir}/apps/myWebApp.war">
<application-bnd>
<security-role name="testing">
<user name="Bob" />
</security-role>
</application-bnd>
</application>
6. Access your application and log in with the user name Bob. The default URL
for the myWebApp application is http://localhost:9080/myWebApp
Results
You have now secured your application.
Liberty profile: Quick overview of security
This topic describes some common security terms, along with an example that
helps you understand the basic workflow of security in the Liberty profile.
Security key terms
Authentication
authentication is user name and password, such as through basic
authentication or form login for web applications. When a user is
authenticated, the source of a request is represented as a Subject object at
run time.
Authorization
Authorization determines whether a user has access to a given role within
the system. The Java EE model uses subjects, roles, and role mappings to
determine if access is allowed.
Role A role is defined within the Java EE application. Some roles, such as the
Administrator role, are predefined by the system. Other roles are defined
by the application developer. In Java EE, subjects are usually granted or
denied access to a role based on the roles they perform within the
application.
Subject
A subject is both a general term and a Java object:
javax.security.auth.Subject. Generally, the term subject means active
entities within the system, such as users on the system, and even the
system process itself.
Security workflow example
The following example demonstrates how the security is applied when a user
requests access to a resource. For example, a user Bob wants to access a servlet
myWebApp. See the code samples in Getting started with security in the Liberty
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 access
to the servlet myWebApp is denied.
Another user Alice can log in to the system because Alice is a valid user. But
Alice 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 Liberty
profile
You can configure the Liberty profile to authenticate and authorize users using a
basic user registry.
Before you begin
The Liberty features appSecurity-2.0 and servlet-3.0 must be
enabled 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 configure
more role mapping in the server.xml file for a Liberty profile server.
Procedure
1. 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 the
example 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 to
perform remote system management activities. This step is done automatically
when using the quickStartSecurity element.
<user>Bob</user>
3. Encode the password within the configuration. You can get the encoded value
by using the securityUtility encode task.
4. Add additional users. Make sure that each user name is unique.
</basicRegistry>
5. Create groups for users. Make sure that each group name must be unique.
<group name="myAdmins">
<member name="Bob" />
</group>
<group name="users">
</group>
</basicRegistry>
6. Assign a user group to the 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" />
<group name="users" />
</security-role>
</application-bnd>
</application>
What to do next
Configure security-related elements in the deployment descriptor of your
application. See Getting started with security in the Liberty profile on page 445
for a sample web.xml file.
Securing communications with the Liberty profile
You can configure the Liberty profile server to provide secure communications
between a client and the server.
About this task
To configure secure communications, you can either specify a minimal SSL
configuration or a detailed SSL configuration in the server.xml file. The minimal
configuration only requires the SSL feature and a keystore entry to be specified. In
the ${wlp.install.dir}/templates/config directory of the Liberty profile, there is
an sslConfig.xml file that contains several examples of SSL configurations.
The SSL configuration that is designated as the
default SSL configuration is used to create the process's default SSLContext using
the SSLContext.setDefault() method. The default SSL configuration can be the
minimal SSL configuration, or the configuration identified by the sslRef attribute
on the sslDefault element if multiple SSL configurations are defined. Because the
default SSLContext is set on the process, the javax.net.ssl.keyStore and
javax.net.ssl.trustStore properties will not be recognized.
Procedure
v Enable SSL communications between a client and a Liberty profile server
v Optional: Create a keystore from the command prompt
v Optional: Encode passwords from the command prompt
v Optional: Configure client certificate authentication between your application
and the Liberty profile server
Enabling SSL communication for the Liberty profile
To enable SSL communication for the Liberty profile, there is a minimal set of SSL
configuration options. It assumes most of the SSL options and only requires some
keystore configuration information.
About this task
SSL client authentication occurs during the connection handshake by using SSL
certificates. The SSL handshake is a series of messages that are exchanged over the
SSL protocol to negotiate for connection-specific protection. During the handshake,
the secure server requests that the client send back a certificate or certificate chain
for the authentication. To enable SSL for the Liberty profile, you add the ssl-1.0
Liberty feature to the server.xml file, along with code of the keystore information
for authentication.
Procedure
1. Enable the ssl-1.0 Liberty feature in the server.xml file.
<featureManager>
</featureManager>
Note: If application security is required and security information is redirected
to a secure port, you must add the appSecurity-2.0 Liberty feature to the
server.xml file.
2. Add the keystore service object entry to the server.xml file. The keyStore
element is called defaultKeyStore and contains the keystore password. The
password can be entered in clear text or encoded. The securityUtility encode
option 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 default
keystore using the securityUtility createSSLCertificate option. The server creates
the keystore for you if it does not exist during SSL initialization. The password
must 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 configuration
if the keystore file is already created. Only JKS keystore files are created by the
server if the keystore file does not exist. The certificate has a validity period of
365 days, the CN value of the subjectDN is the host name of the machine where
the server is running, and the signature algorithm of the certificate is SHA1 with
RSA.
The single keystore entry for a minimal SSL configuration can be extended to
include 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 an
absolute path, then the keystore file is assumed to have been already created.
Keystore of other types can also be specified in the minimal SSL configuration
if the keystore file is already created. When the minimal SSL configuration is
used, the SSL configuration defaults are used to create the SSL context for an
SSL handshake. The configuration protocol is SSL_TLS by default. The HIGH
ciphers, 128 bit, and higher cipher suites can be used.
Liberty profile: SSL configuration attributes
SSL configurations contain attributes that you use to control the behavior of the
server SSL transport layer on a Liberty profile. This topic iterates all the settings
available for an SSL configuration.
SSL Feature
To enable SSL on a server, the SSL feature must be included in the server.xml file:
<featureManager>
</featureManager>
SSL Default
You can have multiple SSL configurations configured. If more than one SSL
configuration is configured, then the default SSL configuration must be specified in
the server.xml file using the sslDefault service configuration.
Table 18. Attribute of the sslDefault element. This table describes the attribute of the
sslDefault element.
Attribute Description Default Value
sslRef The sslRef attribute specifies the
SSL configuration to be used as the
default. If this attribute is not
specified, then the value used is
defaultSSLSettings.
The default SSL Configuration
name 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 suit
your needs. These attributes can be set on the ssl service configuration element in
the server.xml file.
Table 19. Attributes of the SSL element. This table describes the attributes of the ssl
element.
id The id attribute assigns a unique
name to the SSL configuration
object.
No default value; a
unique name must be
specified.
keyStoreRef The keyStoreRef attribute names
the keystore service object that
defines the SSL configurations
keystore. The keystore holds the
key required to make an SSL
connection.
No default value; a
keystore reference
must be specified.
trustStoreRef The trustStoreRef attribute
names the keystore service object
that defines the SSL
configurations truststore. The
truststore holds certificates
required for signing verification.
trustStoreRef is an
optional attribute. If
the reference is
missing, the keystore
specified by
keyStoreRef is used.
clientAuthentication The clientAuthentication
attribute determines whether
SSL client authentication is
required.
Default value is
false.
Table 19. Attributes of the SSL element (continued). This table describes the attributes of
the ssl element.
clientAuthenticationSupported The
clientAuthenticationSupported
attribute determines whether
SSL client authentication is
supported. The client does not
have to supply a client
certificate. If the
clientAuthentication attribute
is set to true, the value of the
clientAuthenticationSupported
attribute is overwritten.
Default value is
false.
sslProtocol The sslProtocol attribute
defines the SSL handshake
protocol. The protocol can be
SDK-dependent, so if you
modify the protocol make sure
that the value is supported by
the SDK you are running under.
Default value is
SSL_TLS.
securityLevel The securityLevel attribute
determines the cipher suite
group to be used by the SSL
handshake. The attribute has one
of the following values:
v HIGH (128-bit ciphers and
higher)
v MEDIUM (40-bit ciphers)
v WEAK (for all ciphers without
encryption)
v CUSTOM (if the cipher suite
group is customized).
When you set the enableCiphers
attribute with a specific list of
ciphers, the system ignores this
attribute.
Default value is HIGH.
enableCiphers The enableCiphers attribute is
used to specify a unique list of
cipher suites. Separate each
cipher suite in the list with a
space. If the enableCiphers
attribute is set then the
securityLevel attribute is
ignored.
No default value.
serverKeyAlias The serverKeyAlias attribute
names the key in the keystore to
be used as the SSL
configurations key. This attribute
is only required if the keystore
has more than one key entry in
it. If the keystore has more than
one key entry and this attribute
does not specify a key, then the
JSSE picks a key.
No default value.
Table 19. Attributes of the SSL element (continued). This table describes the attributes of
the ssl element.
clientKeyAlias The clientKeyAlias attribute
names the key in the keystore to
be used as the key for SSL
configuration when
clientAuthentication is
enabled. The attribute is only
required if the keystore contains
more than one key entry.
No default value.
Note:
v The key manager is used by the SSL handshake to determine what certificate
alias to use. The key manager is not configured in the server.xml file, it is
retrieved from the security property ssl.KeyManagerFactory.algorithm of the
SDK.
v The trust manager is used by the SSL handshake to make trust decisions. The
trust manager is not configured in the server.xml file, it is retrieved from the
security 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"
trustStoreRef="defaultTrustStore" />


clientAuthentication="true"
sslProtocol="TLS" />



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.xml
file.
Table 20. Attributes of the keystore element. This table explains the attributes of keystore
element.
id The id attribute defines a unique
identifier of the keystore object.
No default value, a unique name
must be specified.
Table 20. Attributes of the keystore element (continued). This table explains the attributes
of keystore element.
location The location attribute specifies the
keystore file name. The value can
include the absolute path to the
file. If the absolute path is not
provided, then the code looks for
the file in the
${server.config.dir}/resources/
security directory.
In the SSL minimal configuration,
the location of the file is assumed
to be ${server.config.dir}/
resources/security/key.jks.
type The type attribute specifies the
type of the keystore. Check that
the keystore type that you specify
is supported by the SDK you are
running on.
Default value is jks.
password The password attribute specifies the
password used to load the keystore
file. The password can be stored
either in clear text or encoded. For
information about how to encode
the password, see the
securityUtility encode option.
Must be provided.
provider The provider attribute specifies the
provider to be used to load the
keystore. Some keystore types
required a provider other than the
SDK default.
By default no provider is specified.
fileBased The fileBased attribute specifies
whether the keystore is file-based.
Default value is true.
Here is an example of how the keystore element is configured in the server.xml
file:



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 example
has the following SSL configurations:
v defaultSSLSettings
v mySSLSettings
By default, the SSL configuration is set to defaultSSLConfig.
<featureManager>
</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 the
Utilities menu
Using the Liberty profile Utilities menu in the developer tools, you can create an
SSL certificate.
Procedure
1. 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 365
days.
c. Click the Specify subject (DN): field, and provide a value for your SSL
subject.
3. Click Finish.
Creating SSL certificates from the command prompt
You can use the securityUtility command to create a default SSL certificate for
use by the Liberty profile configuration.
Procedure
2. Create an SSL certificate.
Run the following command. If you do not specify a server name or a
password, the command does not run. See Liberty profile: securityUtility
command 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 keystore
file is located under the /resources/security directory of the specified server. If a
default 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 server
configuration by adding the following lines to the server configuration file:
<featureManager>
</featureManager>
<keyStore id="defaultKeyStore" password="keystore_password" />
See Enabling SSL communication for the Liberty profile on page 449.
Liberty profile: securityUtility command
The securityUtility command supports plain text encryption and SSL certificate
creation for a Liberty profile.
Syntax
securityUtility task [options]
where the options are different based on the value of task.
Parameters
The following tasks are available for the securityUtility command:
encode
Encodes the provided text using Base64. If no arguments are specified, the
command enters interactive mode. Otherwise, the provided text is
encoded. Text with spaces must be put in quotation marks if specified as
an argument.
The arguments are:
--encoding=encoding_type
Specifies the type of encoding to be used. Supported encodings are
xor or aes. The default value is xor.
--key=encryption_key
Specifies the key to be used when encoding using AES encryption.
This string is hashed to produce an encryption key that is used to
encrypt and decrypt the password. The key can be provided to the
server by defining the variable wlp.password.encryption.key
whose value is the key. If this option is not provided, a default key
is used.
See also Liberty profile: The limits to protection through password
encryption on page 47.
createSSLCertificate
Creates a default SSL certificate for use in server configuration. Generated
keystore file key.js is placed under /resources/security directory of the
server specified in --server name. The key algorithm is RSA and signature
algorithm is SHA1 with RSA. For more control over the certificate creation,
use keytool directly.
The arguments are:
--server=name
Specifies the name of the Liberty profile server for keystore
creation. This option is required.
--password=passwd
Specifies the password to be used in the keystore, which must be
at least six characters in length. This option is required.
--passwordEncoding=password_encoding_type
Specifies how to encode the keystore password. Supported
encodings are xor or aes. The default value is xor.
--passwordkey=password_encryption_key
Specifies the key to be used when encoding the keystore password
using AES encryption. This string is hashed to produce an
encryption key that is used to encrypt and decrypt the password.
The key can be provided to the server by defining the variable
wlp.password.encryption.key whose value is the key. If this option
is not provided, a default key is used.
--validity=days
Specifies the number of days that the certificate is valid, which
must be equal to or greater than 365. The default value is 365. This
option is optional.
--subject=DN
Specifies the Domain Name (DN) for the certificate subject and
issuer. The default value is CN=localhost,O=ibm,C=us. This option
is optional.
help Prints help information for a specified task.
Usage
The following examples demonstrate correct syntax:
securityUtility encode GiveMeLiberty --encoding=aes
securityUtility createSSLCertificate --server=myserver --password=mypassword --validity=365
--subject=CN=mycompany,O=myOrg,C=myCountry
securityUtility help createSSLCertificate
Configuring your web application and server for client
certificate authentication
You can configure your web application on the Liberty profile using SSL client
authentication.
Before you begin
This topic assumes that you have already created the SSL certificates, for example
as 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-side
send a certificate. A WebSphere server can be configured for client certificate
authentication on the SSL configuration. To do this, you add the ssl-1.0 Liberty
feature to the server.xml file, along with code that tells the server the keystore
information for authentication.
For details of which aspects of SSL are supported, see Liberty features on page
14.
Procedure
1. 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 the
deployment descriptor.
2. Optional: Generate an SSL certificate using the command prompt. See Liberty
profile: securityUtility command on page 456.
3. Configure your server to enable SSL client authentication by adding the
following lines to the server.xml file:
<featureManager>
<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 client
sends a certificate. However, if the client does not have a certificate, or the
certificate is not trusted by the server, the handshake does not succeed.
v If you specify clientAuthenticationSupported="true", the server requests
that a client sends a certificate. However, if the client does not have a
certificate, or the certificate is not trusted by the server, the handshake might
still succeed.
v If you do not specify either clientAuthentication or
clientAuthenticationSupported, or you specify
clientAuthentication="false" or clientAuthenticationSupported="false",
the server does not request that a client send a certificate during the
handshake.
4. Add a client certificate to your browser. See the documentation of your browser
for 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 specify
allowFailOvertoBasicAuth, and the client certificate authentication does not
succeed, the request generates a 403 Authentication error message, and the
client is not prompted for basic authentication.
Authenticating users in the Liberty profile
The Liberty profile server uses a user registry to authenticate a user and retrieve
information 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 Liberty
profile: Authentication on page 29.
The authentication tasks that you can configure might vary depending on your
requirements. Unless you have used the quickStartSecurity element that can
configure only one user, you have to configure the user registry at the least. You
do not have to configure the values for JAAS, authentication Cache and SSO tasks
unless you want to change the default values. Configure TAI configuration only
when you have an implementation of TAI interface to handle authentication.
You can complete one or more of the following authentication tasks:
Procedure
v Configure authentication cache on the Liberty profile
v Configure a custom JAAS login module for the Liberty profile
v Configure SSO on the Liberty profile
v Configure a user registry for the Liberty profile
v Configure RunAS authentication in the Liberty profile
v Configure TAI for the Liberty profile
Configuring a user registry for the Liberty profile
You can store user and group information for authentication in several types of
registry. For example you can use a basic user registry, or an LDAP registry.
Procedure
v Configure a basic user registry for the Liberty profile
v Configure an LDAP user registry for the Liberty profile
Configuring a basic user registry for the Liberty profile
You 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 for
authentication on the Liberty profile server. To do this, you add the
appSecurity-2.0 Liberty feature to the server.xml file, along with user information
in the basicRegistry element.
Procedure
1. 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:
<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" />
</group>
</basicRegistry>
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.
v
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 securityUtility
command-line tool is available in the $INSTALL_ROOT/bin directory. When you
run the securityUtility encode command, you either supply the password
to encode 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
encoded value. Copy the value output by the tool, and use that value for the
password. For example, to encode the password GiveMeLiberty, run the
following 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 profile
You can configure a Lightweight Directory Access Protocol (LDAP) server with the
Liberty profile for authentication.
Before you begin
Ensure that your LDAP server is up and running, and that the host name and port
number 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 Liberty
profile. To do this, you add the appSecurity-2.0 Liberty feature to the server.xml
file and specify, in the server.xml file, the configuration information for connecting
to the LDAP server.
Avoid trouble: You can refer to the sample LDAP configuration ldapRegistry.xml
file in the ${wlp.install.dir}/templates/config directory, and make sure the
configuration in your server.xml file is similar to the one in the sample file.
Procedure
1. 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 certificate
for the LDAP server must be added to the truststore that is referenced by the
sslAlias 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 and
keystore-related lines from the following examples.
You configure the LDAP server in the server.xml file or using the WebSphere
Application Server Developer Tools for Eclipse. For sample configurations of
other 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"
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"
<keyStore id="LDAPTrustStore" location="${server.config.dir}/LdapSSLTrustStore.jks"
If you use the WebSphere Application Server Developer Tools for Eclipse, the
bindPassword password is encoded for you automatically. If you edit the
server.xml file directly, you can use the securityUtility encode command to
encode the bindPassword password for you. The securityUtility
command-line tool is available in the $INSTALL_ROOT/bin directory. When you
run the securityUtility encode command, you either supply the password to
encode 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 encoded
value. Copy the value output by the tool, and use that value for the
bindPassword password.
5. Optional: Configure certificate filter mode for the
LDAP 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}"
userIdMap="*:uid"
groupIdMap="*:cn"
groupMemberIdMap="ibm-allGroups:member;ibm-allGroups: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.
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" />
</failoverServers>
<failoverServers name="failoverLdapServersGroup2">
</failoverServers>
</ldapRegistry>
<idsLdapFilterProperties id="ibm_dir_server"
userIdMap="*:uid" groupIdMap="*:cn"
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"
baseDN="o=tds" ldapType="IBM Tivoli Directory Server" searchTimeout="8m">
<baseEntry baseDN="o=ldap" name="o=ldap"/>
</ldapRegistry>
<ldapRegistry id="LDAP2" realm="SampleLdapIDSRealm"
baseDN="o=ibm,c=us" ldapType="IBM Tivoli Directory Server" searchTimeout="8m">
</ldapRegistry>
For more information about the ldapRegistry elements, see Liberty profile:
Liberty profile: LDAP certificate map mode:
The certificate map mode is used to specify whether to map X.509 certificates into
an 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 user
entry in the LDAP server, including case and spaces. To use the specified certificate
filter for the mapping, you can use the CERTIFICATE_FILTER.
Certificate filter
Specifies the filter certificate mapping property for the LDAP filter. The
filter is used to map attributes in the client certificate to entries in the
LDAP registry.
If more than one LDAP entry matches the filter specification at run time,
authentication fails because the result is an ambiguous match. The syntax
or structure of this filter is:LDAP attribute=${Client certificate
attribute}.
An example of a simple certificate filter is: uid=${SubjectCN}.
You can also specify multiple properties and values as part of the
certificate filter. The left side of the filter specification is an LDAP attribute
that 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 in
your client certificate. The right side must begin with a dollar sign ($) and
open bracket ({) and end with a close bracket (}). The case of the strings is
important.
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:
host="myldap.ibm.com" port="389" ignoreCase="true"
baseDN="o=ibm,c=us"
certificateMapMode="CERTIFICATE_FILTER"
certificateFilter="uid=${SubjectCN}"
userIdMap="*:uid"
groupIdMap="*:cn"
ldapType="IBM Tivoli Directory Server" searchTimeout="8m" />
Liberty profile: Dynamic changes on security
This topic describes some specific information on how dynamic configuration
changes impact security on the Liberty profile.
Dynamically changing the user registries
Changing the user registry can impact both the server configuration and clients
using the server. When you change the user registry dynamically (without
restarting 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 takes
the form of user:realmName/uniqueId or group:realmName/uniqueId. The
realmName in the accessId must match the realmName for the configuration user
registry.
Configuring the authentication cache on the Liberty profile
This topic describes how to modify the way that authenticated users are cached on
About this task
Because the creation of a subject is relatively expensive, the Liberty profile
provides an authentication cache to store a subject after an authentication of a user
is successful. The cache is initialized with a certain number of entries, determined
by the initialSize attribute, and has a maximum number of entries, determined
by the maxSize attribute. If the maximum size is reached, then the earliest entries
that were used are removed from the cache. Also, if a user has been inactive for
more than a certain time period as determined by the timeout attribute, then the
entry for that user is removed from the cache. By default, the cache size is
initialized to 50 entries and a maximum of 25000 entries with a timeout of 600
seconds.
You do not have to configure the values for the authCache element unless you
want 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 the
authentication cache. However, if changes are done to an external user registry
such as LDAP, the authentication cache is unaffected.
v You must consider the following effects of the timeout value on your
configuration:
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 the
authentication cache until the cache is refreshed.
Smaller authentication cache timeout values can affect performance. When
this value is smaller, the Liberty profile server accesses the user registry or
repository more frequently.
Larger numbers of entries in the authentication cache, which is caused by an
increased number of users, increases the memory usage by the authentication
cache. Thus, the application server might slow down and affect performance.
Procedure
1. Enable the appSecurity-2.0 Liberty feature in the server.xml file.
<featureManager>
</featureManager>
2. If you want to change the default options for the authentication cache, add the
authCache element to the server.xml file. In the following example, the initial
size of the authentication cache is changed to 100 entries with a maximum of
50000 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 attribute
cachEnabled to false in the authentication element as follows:
<authentication id="Basic" cacheEnabled="false" />
For more information about the authCache and authentication elements, see
Configuring a JAAS custom login module for the Liberty
profile
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 login
module, which implements the javax.security.auth.spi.LoginModule interface. This
topic also assumes that the JAAS custom login module uses hashtable, callbacks or
shared state variables provided by the Liberty profile server to pass authentication
data to the system login module.
About this task
You can use a custom login module to either make additional authentication
decisions or add information to the Subject to make finer-grained authorization
decisions inside your application. See JAAS configuration on page 31 and JAAS
login modules on page 32 for a more detailed overview.
You can also use the developer tools to configure a
custom JAAS login module. See Configuring JAAS on the Liberty profile by using
developer tools on page 466.
Avoid trouble:
If you use the developer tools to
configure the JAAS custom login module, refer to the sample JAAS configuration
jaasConfig.xml file in the ${wlp.install.dir}/templates/config directory, and
make sure the configuration in your server.xml file is similar to the one in the
sample file. See Configuring JAAS on the Liberty profile by using developer
tools on page 466.
See also Developing JAAS custom login modules for a system login
configuration on page 499.
Procedure
2. Create a class com.ibm.ws.security.authentication.modules.CustomLoginModule
that implements the LoginModule interface and package it into the
CustomLoginModule.jar file.
3. Create a library element that uses a fileset element indicating where the
CustomLoginModule.jar file is. In this example, the library id is customLoginLib.
4. Create a jaasLoginModule element. In this example, the id is custom. Configure
the custom login module to require a successful authentication by setting the
controlFlag attribute to REQUIRED. Set the libraryRef attribute to
customLoginLib, the id of the library element configured in the previous step.
This login module also has two options: UserRegistry is ldap and mapToUser is
user1.
5. Create a jaasLogincontextEntry element with an id and name of the
system-defined JAAS configuration: system.WEB_INBOUND. You can also set
this JAAS configuration to system.DEFAULT, WSLogin, or your own JAAS
configuration. On the loginModuleRef attribute, add custom, the id of the
jaasLoginModule element created in the previous step. Putting this id first in
the list means that it is the first JAAS login module to be called. You must also
list the other default login modules: hashtable, userNameAndPassword,
certificate, and token.
See the following server.xml file as an example:
<featureManager>
</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 in
the 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 custom
login module for the Liberty profile by editing the configuration. You do not have
to configure JAAS unless you want to customize it.
Before you begin
Avoid trouble: The developer tools creates the reference to a JAAS login module
using the loginModuleRef element. You must change it and use the loginModuleRef
attribute of jaasLoginContextEntry element. You can refer to the sample JAAS
configuration jaasConfig.xml file in the ${wlp.install.dir}/templates/config
directory, and make sure the configuration in your server.xml file is similar to the
one in the sample file.
Procedure
1. 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 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 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, click
Browse button in the Includes pattern field to select your JAR file that contains
your custom login module implementation.
6. Optional: If your custom login module needs any options, you can right click
JAAS Login Module, select Add and then select login module options.
7. Save the configuration. You can find the following configuration saved in the
server.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">
</library>
8. Required: To make the configuration work, you must change the
jaasLoginContextEntry element to include the loginModuleRef attribute. You
must remove the loginModuleRef element and add it as an attribute of the
jaasLoginContextEntry 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">
</library>
Configuring LTPA on the Liberty profile
This topic describes how you can configure a Liberty profile server to use a
specific Lightweight Third Party Authentication (LTPA) keys file, user-defined
password, and expiration time.
About this task
The LTPA is configured by default when security is enabled for a Liberty profile
server for the first time. The default location of the automatically generated LTPA
keys file is ${server.output.dir}/resources/security/ltpa.keys. The keys are
encrypted with a randomly generated key and a default password of WebAS is
initially used to protect the keys. The password is required when importing the
keys into another server. Therefore, to protect the security of the LTPA keys, you
must change the password. When the keys are exchanged between the servers, this
password must match across the servers for Single Sign On (SSO) to work.
The default expiration timeout is 120 minutes. The expiration value refers to how
long the LTPA tokens are valid before they expire.
To enable dynamic reload of the LTPA keys when
copying an LTPA keys file from another server, you can specify a file monitor
interval prior to copying the LTPA keys file. The monitor interval value refers to
how often the LTPA keys file is monitored for updates.
See LTPA concept in the Liberty profile.
Procedure
1. 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 by
setting the monitorInterval attribute which is the time interval on how often to
check the lpta.keys file for key changes to be dynamically changed. Specify a
positive 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 value
by using the securityUtility encode command.
4. Optional: Copy an existing LTPA keys file to the
location 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: Configuration
Customizing SSO configuration using LTPA cookies for the
Liberty profile
With single sign-on (SSO) configuration support, web users can authenticate once
when accessing Liberty profile resources such as HTML, JavaServer Pages (JSP)
files, and servlets, or accessing resources in multiple Liberty profile servers that
share the same Lightweight Third Party Authentication (LTPA) keys.
Example
When a user passes authentication on one of Liberty profile servers, authentication
information generated by the server is transported to the browser in a cookie. The
cookie is used to propagate the authentication information to other Liberty profile
servers.
The LTPA is configured and ready for immediate use. The default cookie name
used to store the SSO token is called ltpaToken2. If you want to use a different
name for the cookie, you can customize the cookie name using the ssoCookieName
attribute of webAppSecurity element. If you customize the cookie name, make sure
that 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 session
expires 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 the
same LTPA keys and shared the same user registry.
For details of all the available SSO settings, see the webAppSecurity element in
Configuring RunAs authentication in the Liberty profile
You can delegate to another identity during authentication by configuring RunAs
specification 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 Liberty
features and have a user registry for your application to configure the RunAs role.
See also RunAs() authentication on page 37.
Procedure
1. 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 to
the 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 user
name. If you are using the ibm-application-bnd.xml file, the password is also
required; if you are using the server.xml file, the password is optional. If the
password is present, it is recommended that the password is encoded. For
example, encode the password using the securityUtility encode command in
the /bin directory of the Liberty profile.
Here is an example of using run-as element within the application-bnd
element in the server.xml file, where the Employee role has been mapped to
the RunAs user of user5:
<application-bnd>
<run-as userid="user5" password="{xor}Lz4sLCgwLTs=" />
</security-role>
</application-bnd>
Note:
v Because the password is optional in the server.xml file, you can also use the
following code for a user without a password:
<application-bnd>
<run-as userid="user5" />
</security-role>
</application-bnd>
v If you specify the application-bnd element in the server.xml file, your
application must not be in the dropins folder. If you leave it in the dropins
folder, then you must disable application monitoring by setting the following
in your server.xml file:
<applicationMonitor dropinsEnabled="false" />
For more information about the run-as element, see Liberty profile:
Configuring TAI for the Liberty profile
You can configure the Liberty profile to integrate with a third-party security service
using Trust Association Interceptors (TAI). The TAI can be called before or after
single sign-on (SSO).
Before you begin
This topic assumes that you have already installed a third-party security server as
a reverse proxy server. The third-party security server can act as a front-end
authentication server when the Liberty profile server applies its own authorization
policy onto the resulting credentials, which are passed by the proxy server.
Meanwhile, you have a JAR file that contains the custom TAI class, which
implements 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 and
a Liberty profile server. It inspects the HTTP requests from the third-party security
server to see if there are any security attributes. If the validation for a request is
successful in the interceptor, the Liberty profile server authorizes the request by
checking whether the client user has the required permission to access the
resources.
See also Developing a custom TAI for the Liberty profile on page 498 and
Customizing SSO configuration using LTPA cookies for the Liberty profile on
page 468.
You can also use the developer tools to configure a TAI
service. See Configuring TAI on the Liberty profile by using developer tools
Procedure
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>
</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 perform
authentication for unprotected URIs and does not allow to fallback to
application authentication method if the TAI authentication fails. As shown in
the example, the following configuration elements are available for TAI
support:
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 and
properties elements, see also Liberty profile: Configuration elements in the
server.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 file
in the ${wlp.install.dir}/templates/config directory, and make sure the
configuration in your server.xml file is similar to the one in the sample file.
Procedure
1. 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 click
New 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, click
Browse button in the Includes pattern field to select your jar file that contains
your TAI implementation.
6. Configure Interceptor properties Details by clicking Add button to add
properties for the interceptor.
7. Save the configuration. You can find the following configuration saved in the
server.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 profile
The purpose of authorization is to determine whether a user or group has the
necessary 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 Liberty
profile
Configuring authorization for your application is to verify whether a user or group
belongs to a specified role, and whether this role has the privilege to access a
resource.
About this task
The Liberty profile server extracts user and group mapping information from a
user registry, then checks the authorization configuration for the application to
determine whether a user or group is assigned to one of the required roles. Then
the server reads the deployment descriptor of the application, to determine
whether the user or group has the privilege to access the resource.
Procedure
For example:
<featureManager>
</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 security
constraints and other security related information.
Note: You can also use a tool such as Rational Application Developer to create
the deployment descriptor.
4. Configure the authorization information such as the user and group to role
mapping.
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 to
do 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 is
stored in an ibm-application-bnd.xml file; in older EAR files, this
information is stored in an ibm-application-bnd.xmi file.
v If your EAR file does not already contain an ibm-application-bnd.xm* file, it
is not a straightforward task to create one and you might prefer to add the
authorization configuration to the server.xml file.
v If the authorization configuration for the EAR file is defined in an
ibm-application-bnd.xm* file and also in the server.xml file, then the two
tables are merged. If there are any conflicts, the information from the
server.xml file is used.
v If you modify your user registry, be sure to review the authorization table for
necessary changes. For example, if you are specifying an access-id element
and change the realm name of the registry, you must also change the realm
name in the access-id element.
v If you specify the application-bnd element in the server.xml file, your
application must not be in the dropins folder. If you leave it in the dropins
folder, then you must disable application monitoring by setting the following
in your server.xml file:
<applicationMonitor dropinsEnabled="false" />
A role can be mapped to a user, a group, or a special subject. The two types of
special subject are EVERYONE and ALL_AUTHENTICATED_USERS. When a role is
mapped to the EVERYONE special subject, there is no security because everyone is
allowed access and you are not prompted to enter credentials. When a role is
mapped to the ALL_AUTHENTICATED_USERS special subject, then any user who has
been authenticated by the application server can access the protected resource.
Here is example code for configuring the user and group to role mapping in
the 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 in
the group administrators. The AllAuthenticatedRole is mapped to the special
subject ALL_AUTHENTICATED_USERS, meaning that any user has access as long as
they provide valid credentials for authentication.
OAuth
OAuth is an open standard for delegated authorization. The OAuth authorization
framework allows a user to grant a third-party application access to their
information stored with another HTTP service without sharing their access
permissions or the full extent of their data.
In OAuth, the client, or third-party application, requests access to resources
controlled by the resource owner and hosted by the resource server, and is issued a
different set of credentials than those of the resource owner. Instead of using the
credentials of the resource owner to access protected resources, the client obtains
an access token, which is a string denoting a specific scope, lifetime, and other
access attributes. Access tokens are issued to third-party clients by an authorization
server with the approval of the resource owner. The client uses the access token to
access the protected resources hosted by the resource server.
OAuth 2.0 is the latest OAuth protocol, and it is not compatible with an earlier
version with OAuth 1.0. OAuth 2.0 allows ease of use for client application
developers, while provides authorization flows for different types of client
applications.
WebSphere Application Server supports OAuth 2.0, and plays a role as an OAuth
service provider endpoint and an OAuth protected resource enforcement endpoint.
The OAuth standard specifications supported include:
v The OAuth 2.0 Authorization Framework
v The OAuth 2.0 Authorization Framework: Bearer Token Usage
Summary of features inside WebSphere Application Server
OAuth 2.0 services
The following is a summary of features within WebSphere Application Server
OAuth 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 authorization
service and web resource authorization decision service.
The OAuth 2.0 authorization service provides all OAuth 2.0 protocol endpoint
URLs, and is responsible for client authorization and token issuing.
The web resource authorization decision service is built into the Liberty profile
web authentication code. When a client accesses an OAuth protected web resource,
the OAuth token is validated and mapped to a WebSphere Application Server
platform 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. The
id or name of the provider is specified in the URL of inbound requests to the
authorization and token endpoints. The set of configuration options for that
provider is used when the request is handled. This process allows one server with
one endpoint servlet to effectively provide multiple OAuth configurations.
For example, the following URL is handled by using the set of OAuth
configuration 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 options
that 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 the
server.xml file. You can define an OAuth service provider by editing the
server.xml file or by using the WebSphere Application Server Development Tools
for Liberty Profile.
There are five basic server.xml configuration items you need for a minimal OAuth
configuration:
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 must
supply a keystore password for SSL by using the keyStore element. There is no
default keystore password.
2. Set up the role mapping for the OAuth web application by using the
oauthRoles element.
OAuth is an HTTP-based protocol and a web application is supplied to handle
the authorization and token endpoints. The web application is built in and is
started automatically when you specify the oauth-2.0 feature. However, you
must map the authenticated role to one or more users, groups, or special
subjects. Another role, clientManager, is supplied for managing client
configuration, but it is not necessary to map that role for OAuth authorization
to function.
3. Define one or more providers with the oauthProvider element.
The provider must have at least one client defined. Clients can be defined
locally with the localStore and client elements. Clients can also be defined in
a 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 OAuth
provider with one client:
<server>
<featureManager>
<feature>oauth-2.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>
<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 and
attributes to the equivalent full profile provider parameters in the provider
configuration file.
The following table illustrates the Liberty profile attributes and the equivalent full
profile 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 full
profile 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 an
OAuth service provider.
About this task
You can authorize an OAuth client without the approval of the resource owner by
enabling the auto authorization feature of the WebSphere Application Server
OAuth service provider.
Procedure
Configure auto consent with the autoAuthorizeParam attribute and the
autoAuthorizeClient subelement of the oauthProvider element in the server.xml
file:
<oauthProvider id="OAuthConfigSample" autoAuthorizeParam="autoauthz" ...>
...
<autoAuthorizeClient>client01</autoAuthorizeClient>
<autoAuthorizeClient>client02</autoAuthorizeClient>
</oauthProvider>
Results
The client01 and client02 OAuth clients are now configured for auto
authorization.
OAuth endpoint URLs:
After OAuth 2.0 is enabled, several endpoint URLs are configured on the
WebSphere Application Server so that OAuth clients can communicate with the
OAuth 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
where
v 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 URL
https://<host_name>:<port_number>/oauth2/endpoint/<provider_name>/token
where
Application Server.
3. Authorization endpoint URL of trust association interceptor (TAI) based user
authentication
https://<host_name>:<port_number>/oauth2/declaritiveEndpoint/<provider_name>/authorize
where
Application Server.
By using this authorization endpoint, the applicable user authentication
includes TAI.
Invoking OAuth 2.0 service
A registered OAuth client can invoke the WebSphere Application Server OAuth
service authorization endpoint to request an authorization code. A registered
OAuth client can also invoke the WebSphere Application Server OAuth service
token endpoint to request an access token. The client then can use the access token
to 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 WebSphere
Application Server OAuth 2.0 Authorization Service by adding its client id, client
secret, state, redirect URI, and the optional scopes.
or
https://<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 Server
OAuth 2.0 token endpoint by adding authorization_code grant type,
authorization code, redirect_url, and client_id as request parameters.
The following example shows the constructions of the URIs when using
authorization 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(code, 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 server
BufferedReader 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();
}
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();
}
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();
}
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 Server
OAuth 2.0 authorization endpoint by adding token response_type, redirect_url,
client_id, scope, and state as request parameters.
or
https://<host_name>:<port_number>/oauth2/declarativeEndpoint/<provider_name>/authorize
The following example shows the construction of the URI when using implicit
grant:
if (isImplicit) {
param1 = "token";
String query = String.format("response_type=%s&
client_id=%s&
state=%s&
redirect_uri=%s&
scope=%s",
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();
// send Resource Request using the access token
}
}
Client credential flow
The OAuth client accesses the token endpoint with the client ID and secret, and
exchanges for an access token for future resource requests. In this flow, the client
accesses the token endpoint by adding client_credentials grant type, client_id,
and client_secret as request parameters.
The following example shows the construction of the URI when using client
credential:
if (isClientCredentials){
param1 = "client_credentials";
String query = String.format("grant_type=%s&
scope=%s&
client_id=%s&
client_secret=%s",
URLEncoder.encode(scope, charset),
URLEncoder.encode(clientSecret, charset));
accessToken = sendRequestForAccessToken(query);
//send Resource Request using (accessToken);
}
}
Resource owner password flow
The Resource Owner Password Credentials flow passes the user ID and password
of the resource owner to the token endpoint directly. In this flow, The OAuth client
accesses the token endpoint by adding password grant type, client_id,
client_secret, username, password, scope, and state as request parameters.
The following example shows the construction of the URI when using resource
owner password:
if (isResourceOwnerCredentials) {
param1 = "password";
username=%s&
password=%s&
scope=%s&
client_id=%s&
client_secret=%s",
URLEncoder.encode(resOwnerName, charset),
URLEncoder.encode(resOwnerPassword, charset),
URLEncoder.encode(scope, charset),
URLEncoder.encode(clientSecret, charset));
//send Resource Request using (accessToken);
}
}
If the access token is expired, then the refresh token can be sent to get a valid
access 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 token
param1 = "refresh_token";
client_id=%s&
client_secret=%s&
refresh_token=%s&
scope=%s",
URLEncoder.encode(this.refreshToken, charset),
sendResourceRequest(accessToken);
}
}
}
}
Customizing an OAuth provider
The WebSphere Application Server OAuth service provider has plug-in points for
customization. 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 post
processing 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 message
processing to perform customized post processing.
Write an OAuth20 mediator
To write a mediator, you must implement the interface named
com.ibm.oauth.core.api.oauth20.mediator.OAuth20Mediator You can implement
one 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 and
processing to allow any post custom processing by the component consumer in the
processAuthorization method.
void mediateAuthorizeException(AttributeList attributeList, OAuthException exception)
This method is called by the core component when the protocol exception happens
to allow any post custom processing by the component consumer in the
processAuthorization method.
void mediateResource(AttributeList attributeList)
processResourceRequest method.
void mediateResourceException(AttributeList attributeList, OAuthException exception)
This method is called by the core component when protocol exception happens to
allow any post custom processing by the component consumer in the
processResourceRequest method.
void mediateToken(AttributeList attributeList)
processTokenRequest method.
void mediateTokenException(AttributeList attributeList, OAuthException exception)
This method is called by the core component when protocol exception happens to
allow any post custom processing by the component consumer in the
processTokenRequest method.
Enable OAuth20 mediator for an OAuth provider
To add a customized mediator to a specific OAuth20 service provider, update the
provider definition in the server.xml file. Add the mediatorClassname attribute of
the oauthProvider element and specify the class name for the mediator. You can
also specify multiple class names for mediators by using the mediatorClassname
subelement of the oauthProvider element. If multiple mediators are specified, those
mediators are started in the order they are specified. You must also define a
library element that contains the mediator class and refer to the library with the
libraryRef attribute.
The following example shows a sample custom mediator entry in the provider
definition 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 the
WebSphere Application Server user registry in the resource owner password
credentials 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)
}
public void mediateResource(AttributeList attributeList)
}
public void mediateResourceException(AttributeList attributeList,
}
public void mediateToken(AttributeList attributeList)
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 doesnt exist or the
password doesnt 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,
final String methodName = "mediateTokenException";
LOG.entering(CLASS, methodName, new Object[] {attributeList, exception});
if("password".equals(attributeList.getAttributeValueByName("grant_type"))) {
// clear sensitive data
attributeList.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 consent
information about which OAuth clients are authorized to access the protected
resource in given scopes. The authorization request from the OAuth client shows a
list of requested scopes in the template.
WebSphere Application Server allows the consent form template to be either a
static HTML page or a dynamic web page. In both cases, the template must be
provided as an unprotected web resource. The form retriever in WebSphere
Application Server integration does not perform any authentication when accessing
this template URL.
The WebSphere Application Server OAuth provider includes a simple sample
consent form, and allows customization by using oauthFormData variable.
To customize the consent form, you must edit the oauthFormData variable by using
Javascript. The following variables are included in the form data:
v authorizationUrl - the authorization URL where the form is being submitted
v clientDisplayName - the display name of the client
v nonce - random generated number to prevent cross-site request forgery (CSRF)
v client_id - see the OAuth 2.0 specification
v response_type - see the OAuth 2.0 specification
v redirect_uri - see the OAuth 2.0 specification
v state - see the OAuth 2.0 specification
v scope - see the OAuth 2.0 specification
The developer of a form template is responsible for rendering the template with
what is in the oauthFormData variable with Javascript. The developer must
interpret the scope value to be a meaningful value to a user. When a user
authorizes 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 can
implement their own function to submit the OAuth authorization request.
If globalization is wanted, you can use a dynamic page that returns globalized
content according to the Accept-Language header in the request. When retrieving
the template, the Accept-Language header is forwarded as well, and the template
developer must decide which content to return regarding the preferred language.
Note: The clientDisplayName variable is not escaped in HTML. The template
developer must sanitize the value, as the value is input by a user during client
registration.
To use a custom consent form template page for a specific OAuth20 service
provider, you must update the service provider definition in the server.xml file. In
the provider configuration, you must use the authorizationFormTemplate attribute
of the oauthProvider element and add the template URL as the value. The
following 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:
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 name
var 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 login
page for a user to submit a user name and password.
You can customize your own form login page, but it must be implemented as
required 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 the
user name. The action must also use the j_password input field to get the user
password. The custom form login page must be provided as an unprotected web
resource.
To use the custom form login page for a specific OAuth20 service provider, you
must update the service provider definition in the server.xml file. In the provider
configuration, you must add the customLoginURL attribute and specify the login
page URL as the value.
The following is an example custom login page entry in the provider definition:
customLoginURL="https://acme.com:9043/oath20/login.jsp"
...>
SQL statements for persistent OAuth service
WebSphere Application Server supports persistent OAuth 2.0 service by persisting
OAuth tokens and clients in a database. With persistent OAuth 2.0 services, an
authorized 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 the
oauthProvider element. The only required attribute on the databaseStore
element is dataSourceRef, whose value must be the id of the dataSource.
The following example is a sample server.xml file for an OAuth provider that
uses a Derby database store:
<server>
<featureManager>
</featureManager>
<oauthRoles>
<authenticated>
</authenticated>
</oauthRoles>
<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 database
name 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
(
CLIENTSECRET VARCHAR(256),
DISPLAYNAME VARCHAR(256) NOT NULL,
ENABLED INT
);
----- ADD CONSTRAINTS -----
ALTER TABLE OAuthDBSchema.OAUTH20CACHE
ADD CONSTRAINT PK_LOOKUPKEY PRIMARY KEY (LOOKUPKEY);
ALTER TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG
ADD 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 data
source Java Naming and Directory Interface (JNDI) name to be jdbc/OAuth2DB.
The JNDI name must match the jndiName attribute of the dataSource element in
the server.xml file. Choose a database name to match what you created in the
first 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. The
following SQL statements add the dbclient01 and dbclient02 OAuth clients to
a 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 and
reference purposes, this topic documents the steps you need to configure Derby
database, 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 and
table:
--- 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 (
CREATEDAT BIGINT,
LIFETIME INT,
EXPIRES BIGINT,
);
CREATE TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG (
ENABLED INT
);
----- ADD CONSTRAINTS -----
----- CREATE INDEXES -----
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.
uses a Derby database store:
<server>
<featureManager>
</featureManager>
<oauthRoles>
<authenticated>
</authenticated>
</oauthRoles>
<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 reference
purposes, this topic documents the steps you need to configure DB2 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 and
table:
-- 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
(
CREATEDAT BIGINT,
LIFETIME INT,
EXPIRES BIGINT,
);
CREATE TABLE OAuthDBSchema.OAUTH20CLIENTCONFIG
(
ENABLED INT
);
---- ADD CONSTRAINTS ----
---- CREATE INDEXES ----
---- 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 the
following command and find the value of the SVCENAME parameter. If it is a
number, 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 SVCENAME
Windows: db2 get dbm cfg | findstr SVCENAME
You can create a database and tables in DB2 by running the following
statement:
db2 -tvf createTables.sql
2. Configure the WebSphere Application Server Liberty Profile server.
uses a DB2 store:
<server>
<featureManager>
</featureManager>
<oauthRoles>
<authenticated>
</authenticated>
</oauthRoles>
<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 profile
You can access the secured Java Management Extensions (JMX) connectors on the
Liberty profile by using SSL. The secured JMX connection is enabled by the Liberty
profile feature restConnector-1.0.
About this task
The REST connector is enabled through the Liberty feature restConnector-1.0.
The following section describes how to configure and access the REST connector
on the Liberty profile.
Procedure
1. Enable the REST connector using the following code in the server.xml file.
<featureManager>
</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 profile
4. 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 system
properties as Java options and set the class path to include the connector class
files. The connector class files are packed in the clients/restConnector.jar
file.
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 SSL
configurations:
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 service
URL: service:jmx:rest://<host>:<port>/IBMJMXConnectorREST. The port
number is the HTTPS port. You must also provide the user name and
password.
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 profile
You can configure web security related properties for the Liberty profile, such as
SSO and client certificate authentication.
About this task
You can use the webAppSecurity element to configure web container application
security 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 the
Liberty profile.
For all available attributes in the webAppSecurity element , see Liberty profile:
You can choose to complete one or more of the following tasks according to your
requirements.
Procedure
v Customizing SSO configuration using LTPA cookies for the Liberty profile on
page 468
v Configuring your web application and server for client certificate
authentication on page 457
Customizing SSO configuration using LTPA cookies for the
Liberty profile
With single sign-on (SSO) configuration support, web users can authenticate once
when accessing Liberty profile resources such as HTML, JavaServer Pages (JSP)
files, and servlets, or accessing resources in multiple Liberty profile servers that
share the same Lightweight Third Party Authentication (LTPA) keys.
Example
When a user passes authentication on one of Liberty profile servers, authentication
information generated by the server is transported to the browser in a cookie. The
cookie is used to propagate the authentication information to other Liberty profile
servers.
The LTPA is configured and ready for immediate use. The default cookie name
used to store the SSO token is called ltpaToken2. If you want to use a different
name for the cookie, you can customize the cookie name using the ssoCookieName
attribute of webAppSecurity element. If you customize the cookie name, make sure
that 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 session
expires 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 the
same LTPA keys and shared the same user registry.
For details of all the available SSO settings, see the webAppSecurity element in
Configuring your web application and server for client
certificate authentication
You can configure your web application on the Liberty profile using SSL client
authentication.
Before you begin
This topic assumes that you have already created the SSL certificates, for example
as 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-side
send a certificate. A WebSphere server can be configured for client certificate
authentication on the SSL configuration. To do this, you add the ssl-1.0 Liberty
feature to the server.xml file, along with code that tells the server the keystore
information for authentication.
For details of which aspects of SSL are supported, see Liberty features on page
14.
Procedure
1. 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 the
deployment descriptor.
2. Optional: Generate an SSL certificate using the command prompt. See Liberty
profile: securityUtility command on page 456.
3. Configure your server to enable SSL client authentication by adding the
following lines to the server.xml file:
<featureManager>
<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 client
sends a certificate. However, if the client does not have a certificate, or the
certificate is not trusted by the server, the handshake does not succeed.
v If you specify clientAuthenticationSupported="true", the server requests
that a client sends a certificate. However, if the client does not have a
certificate, or the certificate is not trusted by the server, the handshake might
still succeed.
v If you do not specify either clientAuthentication or
clientAuthenticationSupported, or you specify
clientAuthentication="false" or clientAuthenticationSupported="false",
the server does not request that a client send a certificate during the
handshake.
4. Add a client certificate to your browser. See the documentation of your browser
for 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.
Note: If you specify allowFailOverToBasicAuth="false" or do not specify
allowFailOvertoBasicAuth, and the client certificate authentication does not
succeed, the request generates a 403 Authentication error message, and the
client is not prompted for basic authentication.
Configuring authentication aliases for the Liberty profile
You can configure an authentication data alias to use with a resource reference for
authentication on the Liberty profile.
About this task
You can use an authentication data alias by defining a user and password for
authentication in the Liberty profile. To do this, add the jdbc-4.0 Liberty feature to
the server.xml file and add at least one authData element.
Note: There is no authentication alias principal mapping module support.
Procedure
1. Add the jdbc-4.0 Liberty features in the server.xml file.
<featureManager>
</featureManager>
2. Configure the authData element in the server.xml file as follows. You must use
a 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.xml
file, of your application by using the authentication-alias element in the
resource reference. The name attribute value must match the id attribute defined
<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 is
originated by the National Institute of Standards and Technology (NIST).
About this task
SP800-131 requires longer key lengths and stronger cryptography. The specification
also provides a transition configuration to enable users to move to a strict
enforcement of SP800-131. The transition configuration also enables users to run
with a mixture of settings from both FIPS140-2 and SP800-131. SP800-131 can be
run in two modes, transition and strict. The transition mode is offered to give user
a setting to move their environment to SP800-131 strict mode. In transition mode, it
is optional to use the SP800-131 required certificates and to set the protocol to
SP800-131
Strict enforcement of SP800-131 requirements on the Liberty profile includes the
following:
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
SHA512withECDSA
v SP800-131 approved Cipher suites.
Note: To configure a Liberty profile server to run in SP800-131 mode, users must
be running with a level of the IBM JDK that supports SP800-131. The minimal
levels 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 of
Standards and Technology.
You can configure the Liberty profile to run in SP800-131 strict mode or transition
mode as following:
Procedure
v 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 supports
SP800-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 strict
mode by setting the system property com.ibm.jsse2.sp800-131 to strict. For
example, com.ibm.jsse2.sp800-131=strict. See Customizing the Liberty
profile environment on page 352 for how to set system properties in the
jvm.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 profile
environment on page 352 for how to set system properties in the
jvm.options file.
Note: If you change your protocol to use TLSv1.2, make sure that your browser
supports TLSv1.2.
Developing extensions to the Liberty profile security infrastructure
The Liberty profile server provides various plug points so that you can extend the
security infrastructure.
About this task
The following topics are covered in this section:
Procedure
v Follow the instructions in Developing a custom TAI for the Liberty profile to
develop custom trust association interceptors (TAI) to extend the security
infrastructure of Liberty profile server.
v Follow the instructions in Developing JAAS custom login modules for a
system login configuration on page 499 to develop JAAS custom login modules
to extend the security infrastructure of Liberty profile server.
Developing a custom TAI for the Liberty profile
You can develop a custom trust association interceptor (TAI) class by implementing
the com.ibm.wsspi.security.tai.TrustAssociationInterceptor interface provided in the
Liberty profile server.
About this task
The trust association interface is a service provider API that enables the integration
of third party security services with a Liberty profile server. When processing the
web request, the Liberty profile server calls out and passes the HttpServletRequest
and HttpServletResponse to the trust association interceptors. The
HttpServletRequest calls the isTargetInterceptor method of the interceptor to see
whether the interceptor can process the request. After an appropriate trust
association interceptor is selected, the HttpServletRequest is processed by the
negotiateValidateandEstablishTrust method of the interceptor, and the result is
returned in a TAIResult object. You can add your own logic code to each method
of the custom TAI class.
See also the Java API document for the TAI interface. The Java API documentation
for each Liberty profile API is available in a separate JAR file under the
Avoid trouble:
configure the TAI, refer to the sample TAI configuration taiConfig.xml file in the
${wlp.install.dir}/templates/config directory, and make sure the configuration
in your server.xml file is similar to the one in the sample file. See Configuring
TAI 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 methods
from 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 request
return 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 jar
file available to the Liberty profile server. See Configuring TAI for the Liberty
Developing JAAS custom login modules for a system login
configuration
For a Liberty profile server, multiple Java Authentication and Authorization Service
(JAAS) plug-in points exist for configuring system logins. The Liberty profile uses
system login configurations to authenticate incoming requests. You can develop a
custom JAAS login module to add information to the Subject of a system login
configuration.
About this task
Application login configurations are called by servlet applications for obtaining a
Subject that is based on specific authentication information. When you write a
login module that plugs into a Liberty profile application login or system login
configuration, you must develop login configuration logic that knows when
specific information is present, and how to use the information. See JAAS
configuration 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, follow
the steps in the procedure:
Procedure
v 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 full
profile creates during a login, refer to the following shared state variables. For
more information about these variables, see the System Programming
Interfaces subtopic of Programming Interfaces
com.ibm.wsspi.security.auth.callback.Constants.WSPRINCIPAL_KEY
Specifies an implemented object of the java.security.Principal interface.
This shared state variable is for read-only purposes. Do not set this
variable in the shared state for custom login modules. The default login
module sets this variable.
com.ibm.wsspi.security.auth.callback.Constants.WSCREDENTIAL_KEY
Specifies the com.ibm.websphere.security.cred.WSCredential object. This
shared state variable is for read-only purposes. Do not set this variable
in the shared state for custom login modules. The default login module
will set this variable.
com.ibm.wsspi.security.auth.callback.Constants.WSSSOTOKEN_KEY
Specifies the com.ibm.wsspi.security.token.SingleSignonToken object. Do
not set this variable in the shared state for custom login modules. The
default login module sets this variable.
v Optional: Understand hashtables for custom JAAS login modules in the Liberty
profile. 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 callbacks
and 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;
}
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.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 key
customProperties.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 Java
Authentication and Authorization Service (JAAS) system login configurations of
the 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 profile
server. See Configuring a JAAS custom login module for the Liberty profile on
page 465.
Customizing an application login to perform an identity
assertion 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 an
identity assertion on the Liberty profile.
About this task
By configuring identity assertion with trust validation, an application can use the
JAAS login configuration to perform a programmatic identity assertion. See
IdentityAssertionLoginModule for more detail.
Avoid trouble:
configure the JAAS custom login module, refer to the sample JAAS configuration
jaasConfig.xml file in the ${wlp.install.dir}/templates/config directory, and
make sure the configuration in your server.xml file is similar to the one in the
sample file. See Configuring JAAS on the Liberty profile by using developer
tools on page 466.
To customize the application login to perform an identity assertion with trust
validation, follow these steps:
Procedure
1. Delegate trust validation to a user implemented plug point.
Trust validation is accomplished by a custom login module. This custom login
module performs any trust validation required, then sets the trust and identity
information in the shared state to be passed on to the identity assertion login
module. A map is required in the following shared state key:
If the state is missing then a WSLoginFailedException is reported by the
IdentityAssertionLoginModule.
The map in the shared state key must include a trust key with the following
key 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, then
no trust is established and the IdentityAssertionLoginModule creates a
WSLoginFailedException.
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 the
following key:
com.ibm.wsspi.security.common.auth.module.IdentityAssertionLoginModule.certficates
If both a principal and certificate are supplied, then the principal is used and a
warning is reported.
2. Create a JAAS configuration for application logins. The JAAS configuration will
contain the user implemented trust validation custom login module and the
IdentityAssertionLoginModule. Then to configure an application login
configuration, 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 Identity
Assertion.
3. Perform the programmable identity assertion. A program can now use the
JAAS login configuration to perform a programmatic identity assertion. The
application program can create a login context for the JAAS configuration
created in step 2, then login to that login context with the identity they would
assert to. If the login is successful then that identity can be set in the current
running 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 successful
Subject s = lc.getSubject();
WSSubject.setRunAsSubject(s);
// From here on , the runas identity is "Joe"
Note: The MyPrincipal class is the implementation of java.security.Principal
interface in the example.
Results
Using the JAAS login framework and two user implemented login modules, you
can create a JAAS login configuration that can be used to perform login to an
identity assertion.
Developing a custom user registry for the Liberty profile
You can develop a custom user registry class by implementing the
com.ibm.websphere.security.UserRegistry interface provided in the Liberty profile
server.
About this task
The UserRegistry interface is a Service Programming Interface (SPI) that enables
support to virtually any type of account repository. For a general view of
stand-alone custom registries, read the Stand-alone custom registries topic.
Procedure
1. 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 web
services. 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 Transport
Layer 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 an
HTTP message for a web service.
Securing web services at the message level
Web services message level security (Web services security or WS-Security) is a
security quality of service (QoS) for web services applications. Web services
security standards and profiles describe how to provide security and protection for
SOAP messages that are exchanged in a web services environment.
Web services security is provided as a Liberty feature. The Web
services security run time that is provided in the Liberty profile is based on the
Apache CXF open source services framework. The Web services security feature in
Liberty is limited by the features and function of the Apache CXF framework. Web
services security must be explicitly enabled by enabling the wssecurity-1.0
feature.
Web services security is configured by using the WS-SecurityPolicy inside the
WSDL 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.pdf
v Web Services Security Username Token Profile 1.1: http://docs.oasis-open.org/
wss/v1.1/wss-v1.1-spec-os-UsernameTokenProfile.pdf
v Web Services Security X.509 Certificate Token Profile 1.1: http://docs.oasis-
open.org/wss/v1.1/wss-v1.1-spec-os-x509TokenProfile.pdf
v 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 the
WS-Security policy at run time. The WS-Security configuration follows the CXF
name and value pair style, and preserves the CXF property name. Some of the
properties have default values and some do not.
In the server.xml file, the WebSphere Application Server Liberty profile provides a
server level configuration which is applied to all services. This configuration is
known as the default WS-Security configuration.
There are two default WS-Security configurations in the server.xml file: one for
client applications and one for provider applications. No other WS-Security
configurations can exist in the server.xml file. If you need a custom WS-Security
configuration for your application that deviates from the default, the configuration
must be done programmatically.
The following examples illustrate default client and provider configurations:
<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 the
Liberty 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 properties
in 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 as
attributes of the signatureProperties or encryptionProperties elements. The
following example illustrates the wss4j properties:
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
merlin.cert.provider
defaults to the keystore provider
merlin.x509crl.file
none
The following table illustrates the wss4j keystore properties in the Liberty profile.
Table 26. wss4j keystore properties in the Liberty profile and CXF
merlin.keystore.file
none
merlin.keystore.password
none
merlin.keystore.type
none
merlin.keystore.alias
none
merlin.keystore.private.password
none
The following table illustrates the wss4j truststore properties in the Liberty profile.
Table 27. wss4j truststore properties in the Liberty profile and CXF
Liberty profile property Default value
merlin.truststore.file
none
merlin.truststore.password
none
merlin.truststore.type
none
The following table illustrates the WS-Security miscellaneous properties in the
Liberty 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 Liberty
profile.
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 additional
configuration information to the WS-Security runtime environment. See the
following links for complete information regarding these properties:
v http://cxf.apache.org/docs/ws-securitypolicy.html
v http://ws.apache.org/wss4j/config.html
Any of the additional properties can be specified in the default WS-Security
configuration in the server.xml file.
For example, to specify any additional properties, specify them in either the
wsSecurityClient or wsSecurityProvider sections or both.
<signatureProperties ... />
<encryptionProperties ... />
ws-security.cache.config.file = "${server.config.dir}/resources/ws-security/new_cxf-ehcache.xml"
<signatureProperties ... />
<encryptionProperties ... />
ws-security.username-token.always.encrypted="false"
</wsSecurityClient>
Configuring cache
WS-Security provides a default caching implementation for nonce in a
UsernameToken, the created Timestamp, and security tokens. The default cache
implementation 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 configuration
XML file. Use the ws-security.cache.config.file custom property to specify a file
name with customized properties to deviate from the default settings. You must
put this file somewhere in the server profile. You can find an additional sample
cache 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 Web
Services Security UsernameToken Profile 1.1 specification. The specification
describes how a web services client supplies a UsernameToken as a means of
identifying the requestor by using a user name, and optionally by using a
password or password-equivalent to the web services provider. The Web Services
Security (WS-Security) run time in the Liberty profile that processes the policy for
the web services provider can use this identifying information to authenticate the
user.
The requirement of a UsernameToken is expressed as one of the supporting tokens
in the WS-Security policy. You can add a UsernameToken requirement as a
required 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 UsernameToken
with password text to be sent in the Security header of a SOAP message to a web
services provider:
<sp:SupportingTokens>
<wsp:Policy>
<sp:UsernameToken
sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:WssUsernameToken11 />
</wsp:Policy>
</sp:UsernameToken>
</wsp:Policy>
</sp:SupportingTokens>
In addition to the requirement of providing a user name or a password, you can
configure a policy to include a nonce and created timestamp in a UsernameToken.
The following example is a sample policy fragment that requies a UsernameToken
with password text, nonce, and created timestamp to be sent in the Security
header of a SOAP message to a web services provider:
<wsp:Policy>
<sp:UsernameToken
<wsp:Policy>
<sp13:Created />
<sp13:Nonce />
</wsp:Policy>
</sp:UsernameToken>
</wsp:Policy>
The following example is a sample policy fragment that requires a UsernameToken
with password digest instead of password text:
<wsp:Policy>
<sp:UsernameToken
<wsp:Policy>
<sp:HashPassword />
</wsp:Policy>
</sp:UsernameToken>
</wsp:Policy>
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 more
information 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 one
method for indicating the user name and password for a client application when
generating a UsernameToken. You can set the user name and password
programmatically or in the server.xml file.
A client can generate a UsernameToken with the user name and password
provided in the server.xml file. The user name and password that is in the
server.xml file is considered the default configuration and is overridden by what
is provided on the RequestContext for the client's web service invocation.
The following example illustrates a sample default configuration:
ws-security.username="alice"
ws-security.callback-handler="com.acme.PasswordCallback"
To generate a UsernameToken with the user name and password determined
programmatically, you can set the following CXF properties on the RequestContext
for the client's web service invocation:
ws-security.username: user name
ws-security.password: user password if ws-security.callback-handler is not defined
ws-security.callback-handler: the CallbackHandler implementation class used to obtain passwords
The following code sample illustrates how to provide a user name and password
on 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 Liberty
profile security user registry to validate the user name and password, if the
password is required. If the password type in the UsernameToken is
PasswordDigest, you are required to provide the ws-security.callback-handler
implementation of a password callback handler by configuring it in the server.xml
file. This callback handler must return valid passwords for all expected user names
so that the WS-Security run time can calculate digest values for comparison with
the value in the SOAP message. After the digest value comparison completes
successfully, the user name and password is validated against the user registry.
The following example illustrates a sample configuration in the server.xml file for
password digest:
ws-security.callback-handler="com.acme.PasswordCallback"
Password CallbackHandler
The password CallbackHandler is used by WS-Security to retrieve a user
password. In the Liberty profile, this password CallbackHandler class must be
packaged as a Liberty feature. The following example illustrates a sample
password 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 web
services with an X.509 token for more information on requirements and limitations
of 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 sent
in the message as-is. The following example is a UsernameToken with a password
type 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 consider
additional protections on the message, such as using HTTPS or encrypting the
token using the EncryptedSupportingToken policy assertion. For more information
on 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 Certificate
Token Profile 1.1. An X.509 token can be used to provide message integrity and
confidentiality 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 a
Web Services Description Language (WSDL) must be created first. The web service
must have a WS-Security policy included in the WSDL file. The WS-Security policy
can contain an AsymmetricBinding or SymmetricBinding assertions.
The requirement of an X.509 token is expressed as an X509Token assertion type in
the WS-Security policy. The following example illustrates a sample X509Token
assertion:
<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 message
signature from the initiator (requestor) to the recipient (provider) and message
encryption from the recipient to the initiator. The recipient X509Token is used for
message signature from the recipient to the initiator and message encryption from
the initiator to the recipient.
In a SymmetricBinding assertion, a secret key or ephemeral key that is protected for
an X509Token is shared by both the initiator and the recipient, and the key is used
for both encryption and decryption.
The following example illustrates a sample WS-Security policy with an X509Token
in an AsymmetricBinding assertion:
<wsp:Policy wsu:Id="SampleAsymmetricX509TokensPolicy">
<wsp:ExactlyOne>
<wsp:All>
<sp:AsymmetricBinding>
<wsp:Policy>
<sp:InitiatorToken>
<wsp:Policy>
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
<wsp:Policy>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
<wsp:Policy>
</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 X509Token
in a SymmetricBinding assertion:
<wsp:Policy wsu:Id="SampleSymmetricX509TokensPolicy">
<wsp:ExactlyOne>
<wsp:All>
<sp:SymmetricBinding>
<wsp:Policy>
<sp:ProtectionToken>
<wsp:Policy>
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
<wsp:Policy>
<sp:RequireThumbprintReference />
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:ProtectionToken>
<sp:Layout>
<wsp:Policy>
<sp:Lax />
</wsp:Policy>
</sp:Layout>
<sp:OnlySignEntireHeadersAndBody />
<sp:SignBeforeEncrypting />
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic128 />
</wsp:Policy>
</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 the
token be included in the message. Several token assertions support mechanisms for
referencing tokens in addition to direct references. If a token assertion contains
multiple reference assertions, then the references to that token are required to
contain all the specified reference types. For example, if a token assertion carries an
sp:IncludeToken attribute with a value of ../Always and that token assertion also
contains a nested sp:RequireIssuerSerialReference assertion, then the token must
be included twice in the message. While such combinations are not in error, they
are best avoided for efficiency reasons.
The IncludeToken assertion is enforced in the Liberty profile, but is ignored in the
WS-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/generator
side, and are not enforced on the server/consumer side.
Runtime configuration
The WS-Security feature run time in Liberty provides more configuration options
for message protection with an X509Token than are covered by the WS-Security
policy. The runtime configuration is defined in the server.xml file. The runtime
configuration includes cryptographic properties such as signatureProperties and
encryptionProperties, key, and keystores.
The following example illustrates a client configuration for an X509Token assertion:
ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler">
org.apache.ws.security.crypto.merlin.keystore.alias="x509ClientDefault"
org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.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:
ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler">
org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks" />
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 encryptionProperties
properties are equivalent to the crypto properties in the WSS4J configuration. See
WSS4J configuration for additional details. Many crypto properties have valid
default values so there is no need to specify them. But other properties, such as
keystore and key related properties, must be specified.
Keystores files, keys, and certificates
Message signature and encryption requires the use of public certificates and
private keys. These public certificates and private keys are stored in keystore files.
Keystore files are required when you use X509Token assertions. The client-side
keystore file contains the private key of the client, and a chain of certificates
corresponding to the public key of the server. The server-side keystore file contains
the private key of the server, and a chain of certificates corresponding to the public
key of the client.
When a SOAP message is signed and encrypted, the signatureProperties and
encryptionProperties properties are interpreted by the WS-Security runtime
environment as follows:
v AsymmetricBinding assertion
The key specified by the signatureProperties property is used as the private
key for signing the outbound message, and is also used for decrypting the
inbound message.
The key specified by the encryptionProperties property is used as the public
key for encrypting the outbound message, and is also used for verifying the
signature in the inbound message.
v SymmetricBinding assertion
The key specified by the encryptionProperties properties is used, while the
signatureProperties 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 other
password is for the private key itself. While the password for the keystore is
specified in one of the crypto properties, either signatureProperties or
encryptionProperties, the CallbackHandler is normally used by WS-Security to
access the private key in a keystore. In the Liberty profile, this CallbackHandler
class must be packaged as a Liberty feature and its class name specified as a the
value 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 a
keystore.
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 key
pwcb.setPassword("JoeKeypassword");
}
}
}
}
}
If the password CallbackHandler class is not provided, then the password specified
in the crypto properties is used as that default password for the private key. This
property is configured as
org.apache.ws.security.crypto.merlin.keystore.private.password.
Since there is only one ws-security.callback-handler custom property supported
in each of the wsSecurityClient and wsSecurityProvider sections of the
security.xml file, a single password callback handler must support all of the
required 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 the
ws-security.callback-handler custom property on the RequestContext for the
web service invocation of the client.
If you need to provide passwords for an X.509 private key and a UsernameToken
for a single web service invocation, you cannot provide separate callback handlers
for each use. In this case, you must implement a single callback handler that
handles both kinds of passwords. As illustrated in the previous example, you must
use the WSPasswordCallback.getUsage() method to determine which kind of
password that you should return. See the WSPasswordCallback API documentation
for 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 defined
in the WSDL to ensure that the SOAP message is protected with the HTTPS secure
transport. It is recommended that HTTPS be used when using security tokens such
as UsernameTokens with clear text passwords to ensure confidentiality.
The assertions for the HTTPS transport in the WS-Security policy do not set up the
HTTPS transport between the requestor and provider. They only ensure that the
HTTPS transport is used when the web services application with the defined
policy is invoked.
This topic assumes that HTTPS is set up between the web services client and
provider. The following steps are extra steps that are required.
1. WS-Security must be explicitly enabled by enabling the
wssecurity-1.0 feature.
2. The attached WS-SecurityPolicy must include a TransportBinding assertion,
and must match the HTTPS configuration. The following example illustrates a
sample 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:Basic256 />
</wsp:Policy>
<sp:Layout>
<wsp:Policy>
<sp:Strict />
</wsp:Policy>
</sp:Layout>
</wsp:Policy>
</sp:TransportBinding>
</wsp:Policy>
By completing these extra steps after the HTTPS configuration, the SOAP message
is required to be sent over HTTPS from a web services client to a web services
provider.
Chapter 10. Deploying applications to the Liberty profile
You can deploy web applications or OSGi applications to the Liberty profile. You
deploy 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
You can deploy applications as described in this topic, or
as described in Adding and running an application on the Liberty profile by
using developer tools on page 519.
This topic assumes that you have not disabled dynamic updates to the runtime
configuration, as described in Controlling dynamic updates on page 374.
About this task
By default, the dropins directory is automatically monitored. If you drop an
application into this directory, the application is automatically deployed on the
server. Similarly, if the application is deleted from the directory, the application is
automatically removed from the server. The dropins directory can be used for
applications that do not require additional configuration, such as security role
mapping. If you put your applications in the dropins directory, you must not
include an entry for the application in the server configuration. Otherwise, the
server will try to load the application twice and an error might error. For
applications that are not in the dropins directory, you specify the location using
an application entry in the server configuration. The location can be on the file
system or at a URL.
Your application can be packaged as an archive file or as a directory. For
applications in the dropins directory, the file name and file extension are used by
the application monitor to determine the type of application, and to generate the
application name and the context-root for web applications. For example, if the
archive file or directory is named snoop.war, the application monitor assumes that
the application is a web application, that the application name is snoop, and that
the context-root is also snoop. For configured applications, you specify the
application type and name, and if the application is a web application, the
application name is also used as the context-root.
For more information about the default directory structure and the properties that
are associated with directories (for example server.config.dir), see Liberty
profile: Directory locations and properties on page 89.
Procedure
v Deploy an application by dropping it into the dropins directory.
For example, using the default directory structure, to deploy an application you
drop 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 and
the identifying suffix. For example, ${server.config.dir}/dropins/
myApp.war/WEB-INF/...
Place the archive file or the extracted archive into a subdirectory named with
the 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. You
must 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 name
might be used as the context-root of the application. For more
information 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 are
war, ear, wab and eba.
location
Specifies the location of the application. It can be an absolute path or a
URL which you can download the application from. It can also be the
file name of your application (including file extension if any).
If the application is available on the file system, the location can either be the
full path name or a simple file name. If the location does not include the full
path, the application manager looks for the application in
${server.config.dir}/apps and ${shared.app.dir}. If the application is
available at a URL, the application manager downloads the application to a
temporary folder inside the server work area, then starts the application.
Note: The location that you specify for a configured application should not be in
the 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 to
deploy the application twice.
In the following two examples, the location is the file system. If the location is a
URL, 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 put
the 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 apps
directory is present by default. See Liberty profile: Directory locations and
properties on page 89 for more information about the properties associated
with the server directories.
The application element can be set before or after the server has started. If
the element is set after the server has started, the changes are picked up
dynamically.
v Remove an application.
For applications that are included in the server configuration, remove the
reference to the application from the server.xml file. The application is then
automatically removed from the server.
For applications that are deployed to the dropins directory, delete the
application from the directory. The application is then automatically removed
from the server.
To uninstall all applications that are in the dropins directory, set the
application 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 is
enabled 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 choose
whether to deploy the applications that are in the directory. See Controlling
dynamic updates on page 374.
Adding and running an application on the Liberty profile by using
developer tools
You can add applications to the server by right-clicking on the server in the
Servers 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 Application
Bundles (WAB) feature sections in the Liberty features on page 14 topic. In
addition, for details on restrictions of OSGi applications, see the wab-1.0 feature
restrictions section in the Liberty profile: Runtime environment known restrictions
topic.
This task assumes that your application is in your Eclipse workspace. If you have a
prebuilt application archive file that you want to add and run, you must first
import the file into your Eclipse workspace. Alternatively, you can use the steps
described in Chapter 10, Deploying applications to the Liberty profile, on page
517.
About this task
When you add an application to the server, the workbench tries to determine
which features are required by the application and enables them in the server
configuration for you if they are not already enabled.
Procedure
1. 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 the
applications you want to add then click Add. Or click Add All to add all
available applications to the server.
3. Alternatively, you can right-click on an application in the Project Explorer view
and select Run As > Run on Server, or Debug As > Debug on Server. This
adds the application to the server (if not already added), starts the server (if not
already started) and runs the application.
Results
Tip: If you are using Run on Server or Debug on Server and the server is already
started, the browser might try to load the application before the server has finished
loading it. If this happens, wait for the message in the console view that displays
the application has been started and then refresh the browser if necessary.
Publishing your application by using developer tools
Publishing involves copying files (projects, resource files, and server
configurations) to the correct location for the server to find and use them. In the
test environments, these files might already be in the correct location. In some
cases, temporary copies of the server configurations might be created. You can
either publish your application automatically or manually.
About this task
Automatically publishing to a server
Procedure
1. 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 are
synchronized. If they are not, the project and the files are automatically
updated when the server is either started or restarted.
2. In the workbench, you have several options to choose for the Publishing
settings. 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 Overview
page of the server editor, under the Publishing settings, you are going to find
the 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 are
saved and a full time interval has passed in the Publishing interval setting.
In the workbench, the default setting is the Automatically publish when
resources change option is enabled with a value set in the publishing
interval.
c. Automatically publish after a build event: Specifies the workbench to issue
a publish after changes on a file that requires a build and is associated to
the server are saved, and a full time interval has passed in the Publishing
interval setting.
d. Publishing interval (in seconds): Specifies the number of seconds required
before the workbench calls a publish to happen on the server. However, if
you make a subsequent change to the files before this time interval has
completed, the publish is delayed as the timer is reset. The workbench
makes a publish to the server only after the full time interval has passed. If
you set the publishing interval to 0 seconds, an immediate publish should
happen after changes on a file are saved.
Manually publishing to a server
About this task
If you do not want to wait for the automatic publishing interval to pass or the
Never publish automatically option is enabled, at anytime you can manually
request the workbench to issue a publish command to the server. Each manual
publish command causes a single publishing request to the server. To publish your
application manually you can complete one of the following actions in the Servers
view:
Procedure
v 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.5
Liberty profile
Publishing involves copying files such as application, resource files, and
deployment descriptor files to the correct location for the server to find and use
them. You can choose whether you want to publish your application on the server
or run your application within the development environment without copying the
application 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 the
server to run your application from the workspace.
This publishing option should publish faster when an application contains a single
root, as opposed to containing multiple roots, because the server expects the
structure of an application to have only a single root. As a result, the workbench
might require additional processing time to publish an application with multiple
roots. To determine whether the structure of your application contains a single or
multiple roots, use the Project Structure Validator. For details, see Creating and
configuring Java EE projects using wizards.
CAUTION:
When you are using Run applications directly from the the workspace
publishing option, the server can lose track of your application under the
following 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 control
management and the workspace is deleted, you can lose your application from
your file system.
v If you delete an application from the workspace without removing it from the
server, the server can no longer find your application. As a result, you might
encounter errors when starting the server because the server tries to start the
missing application from the workspace.
Procedure
1. 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 prompt
From the command prompt you can create a compressed file containing a Liberty
profile runtime environment, the files in the shared resources directory, a specific
server, and the applications that are embedded in the server. You can also choose
to exclude the runtime binaries from the compressed file.
About this task
The Liberty server is lightweight, therefore you can easily package a server
installation in a compressed file. You can then store this package, distribute it to
colleagues, use it to deploy the installation to a different location or to another
machine, or even embed the installation in a product distribution.
Note:
The resulting file is created by using UTF-8
encoding for entry names, so you must use a tool capable of opening the file by
using UTF-8 encoding for entry names. The jar command in a Java SDK uses this
format.
Procedure
To package a Liberty profile server from the command prompt, complete the
following steps:
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 value
of server_name is used for package_file_name, and the compressed file is created
in the ${server.output.dir} directory.
v
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 name
can include a full path name. If the full path is omitted, a compressed file
called 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 in
the ${WLP_USER_DIR} directory; the --include=usr option packages only
relevant files in the ${WLP_USER_DIR} directory, effectively excluding the runtime
binaries from the compressed file.
Using JNDI binding for constants from the server configuration files
You can bind constants into the default JNDI namespace from the server
configuration files using the jndiEntry element on the Liberty profile.
About this task
The default JNDI namespace is available in the Liberty profile to provide bindings
to miscellaneous objects required by applications. Any data sources declared in the
server configuration files are available in the default JNDI namespace. Additionally,
you can bind Java strings and primitive data types in the configuration file into
JNDI namespace. These constants are then made available to an application at run
time, providing a simple and portable way to pass configuration values into the
application.
See Naming for more information about JNDI.
The following steps show how to bind the constants and use them in your
application.
Procedure
1. 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>
</featureManager>
2. To bind constants into the JNDI namespace, add jndiEntry elements into the
server.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 the
following 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 the
object is determined by interpreting the value stored in the jndiEntry
element as a Java literal string or primitive data type. If the parsing fails, the
exact 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
unicode escaped sequences (section 3.3), and the octal and character escape
sequences (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" />
for more information about jndiEntry element.
Deploying OSGi applications to the Liberty profile
You can deploy OSGi applications to the Liberty profile by enabling a list of server
features in the server.xml file.
About this task
By providing a list of OSGi-specific server features, Liberty profile provides OSGi
support 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 on
page 14.
Sharing common OSGi bundles for the Liberty profile
You can share common OSGi bundles by placing them in a directory and
configuring the server.xml file for your server, so that those common OSGi
bundles are available to your OSGi applications.
Procedure
v 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 OSGi
bundles.
v Define a dependency on the common bundle using import phrase in the
manifest.mf file of your OSGi application.
Deploying data access applications to the Liberty profile
Deploying a data access application includes more than installing your web
application archive (WAR) or enterprise archive (EAR) file onto a Liberty profile.
Deployment can include tasks for configuring the data access resources of the
server and overall runtime environment.
About this task
This following topics are covered in this section:
Procedure
v Configure a data source and JDBC driver for database connectivity in a Liberty
profile
v Deploy an JDBC application to the Liberty profile
v Optional: Configure connection pooling in the Liberty profile
v Optional: Develop an application-defined data source on the Liberty profile
v Optional: Configure transaction recovery for data sources on the Liberty profile
v Migrating data access applications to the Liberty profile
Deploying an existing JDBC application to the Liberty profile
You 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. To
do this, you add the jdbc-4.0 Liberty feature to the server.xml file. You must also
add code that tells the server the JDBC driver location and specifies properties that
the JDBC driver uses to connect to the database.
This example uses the ImpactWeb sample application. This application includes a
servlet called WorkingServlet. In this example, you extend the servlet with code
that tests that the JDBC application is working as expected.
Procedure
1. 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"/>
<fileset dir="C:/myDerbyLocation/lib" includes="derby.jar"/>
</library>
<dataSource id="ds1" jndiName="jdbc/exampleDS" jdbcDriverRef="DerbyEmbedded">
<properties.derby.embedded
databaseName="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 table
stmt.executeUpdate("create table cities
(name varchar(50) not null primary key, population int, county varchar(30))");
// insert a test record
stmt.executeUpdate("insert into cities values (myHomeCity, 106769, myHomeCounty)");
// select a record
ResultSet 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 the
following 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 profile
JDBC tracing for the Liberty profile is enabled either through a driver-specific
custom trace setting, or using the application server supplemental JDBC tracing
option.
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 tracing
from the application server.
If you enable tracing by using either a custom vendor property or supplemental
JDBC tracing, you must add the logwriter name to the trace specification in the
bootstrap.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 JDBC
com.ibm.ws.informix.logwriter
Microsoft SQL Server JDBC Driver
com.ibm.ws.sqlserver.logwriter
DataDirect Connect for JDBC for Microsoft SQL Server
com.ibm.ws.sqlserver.logwriter
Sybase
com.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.properties
file, you must restart the server for the changes to take effect.
The following examples illustrate the use of the various JDBC trace methods.
Procedure
v Use java.util.logging.
If the driver you are using supports java.util.logging, you can enable it by
appending the driver's trace level to com.ibm.ws.logging.trace.specification
in the bootstrap.properties file. See the JDBC vendor documentation for levels
and 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:
com.ibm.ws.logging.trace.specification=*=audit=enabled:oracle=FINE
For Oracle, you must also enable the tracing using the system property
oracle.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 setting
System.setProperty("oracle.jdbc.Trace","true");
v Use custom trace settings.
If the driver you are using has custom trace settings, you set them as JDBC
driver vendor properties in the server.xml file. You also add the logwriter name
to 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>
com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.db2.logwriter=all=enabled
Here is an example for Derby Network Client:
<dataSource id="derbyNC" jndiName="jdbc/derbyNC" jdbcDriverRef="DerbyNC" >
<properties.derby.client databaseName="myDB" createDatabase="create" traceLevel="1"/>
</dataSource>
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 JCC
connectivity.
<dataSource id="informixJCC" jndiName="jdbc/informixJCC" jdbcDriverRef="InformixDriverJCC" >
<properties.informix.jcc databaseName="myDB" traceLevel="-1"/>
</dataSource>
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, you
can use supplemental JDBC tracing from the application server. The application
server automatically determines whether to enable supplemental JDBC tracing,
based on the JDBC driver being used. To override this, set the data source
property supplementalJDBCTrace to true or false.
1. Enable supplemental tracing.
Here is an example for enabling supplemental tracing with the embedded
Derby database. Supplemental JDBC tracing is enabled by default for this
database, so you only need to set the logwriter in 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.
com.ibm.ws.logging.trace.specification=*=audit=enabled:com.ibm.ws.informix.logwriter=all=enabled
Here is an example for enabling supplemental tracing, and
java.util.logging, with Microsoft SQL Server JDBC Driver:
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 DataDirect
Connect for JDBC for Microsoft SQL Server:
com.ibm.ws.logging.trace.specification=*=audit=enabled:com.microsoft.sqlserver.jdbc=all
Here is an example for enabling supplemental tracing with solidDB.
<dataSource id="soliddb" jndiName="jdbc/soliddb" jdbcDriverRef="solidDBDriver">
<properties databaseName="dba" URL="jdbc:solid://localhost:2315/dba/dba" />
</dataSource>
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.
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:
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 supplementalJDBCTrace
data source property to false in the server.xml file, or remove the logwriter
name from the com.ibm.ws.logging.trace.specification property in the
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 profile
By deploying a helloworld.war application, you can learn how server
configurations change in the Liberty profile.
Before you begin
The helloworld.war application uses a simple servlet to display a message on your
browser. You can create any other messages to be displayed. The coding of the
application 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 up
and running, all configurations related to the application are automatically enabled
in the server.xml file. However, you can also configure the server.xml file
manually by completing the following steps.
This example uses the helloworld.war application and can be accessed via
http://localhost:9090/helloworld. In this example, we create a Liberty profile
server instance and change its default HTTP port to 9090, then deploy the
application on it.
Procedure
1. 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>
</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. The
entry point of a deployed application is determined in the following
precedence:
v context-root in the server.xml file
v application.xml, if an EAR application
v ibm-web-ext.xml, if a web application
v name of the application in the server.xml file, if a web application
v Manifest.MF, if a WAB application
v Directory name or the file name relative to the "dropins" directory of the
Liberty profile
6. 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 profile
To enable the Liberty profile to support an application that uses the Java
Persistence API (JPA), you add the jpa-2.0 feature to the server.xml file. You also
need to define persistence contexts and persistence units, and configure access to
the entity manager and entity manager factory.
Before you begin
This task assumes that you have created a Liberty profile server, on which you
want to deploy an application that uses JPA. See Creating a Liberty profile server
manually on page 95.
About this task
The jpa-2.0 feature provides support for applications that use
application-managed and container-managed JPA written to the JPA 2.0
specification. The support is built on top of Apache OpenJPA with extensions to
support the container-managed programming model.
Procedure
v 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 profile
By configuring Liberty features in the server.xml file, you can deploy web services
applications to the Liberty profile.
Deploying JAX-RS applications to the Liberty profile
You can use Java API for RESTful Web Services (JAX-RS) to develop services that
follow Representational State Transfer (REST) principles. RESTful services are
based on manipulating resources. Resources can contain static or dynamically
updated data. By identifying the resources in your application, you can make the
service more useful and easier to develop. Liberty profile provides a Liberty
feature jaxrs-1.0 to support JAX-RS programming model.
Liberty profile: JAX-RS
This topic provides an overview of Java API for RESTful Web Services (JAX-RS) in
Implementing JAX-RS web applications
You can use JAX-RS to develop services that follow Representational State
Transfer (REST) principles. Using JAX-RS, development of RESTful services
is simplified.
For more information, see the WebSphere Application Server full profile
topic Implementing JAX-RS web applications.
Note: The following sections, and any subtopics are not relevant to the
Liberty 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 web
module, or the user-defined context root found in the EAR file.
v In Assembling JAX-RS web applications, the content in the "About this
task" section is not relevant to the Liberty profile.
Using XML content in JAX-RS application requests and responses
XML is a common media format that RESTful services consume and
produce. To deserialize and serialize XML, you can represent requests and
responses by Java Architecture for XML Binding (JAXB) annotated objects.
topic Using XML content in JAX-RS application requests and responses.
Liberty profile:
Using Atom content in JAX-RS application requests and responses
You can use the Atom Syndication Format (Atom) to format web feeds,
which communicate news and updates of episodic information about
websites. Using Atom content in JAX-RS applications, you can take
advantage of web content syndication that provides the same
decentralized, dynamic mechanisms for adding new metadata and content
supported by RSS, but does so in a way that helps protect core
interoperability between implementations.
topic Using Atom content in JAX-RS application requests and responses.
Liberty profile:
Using custom entity formats
Even though the JAX-RS runtime environment includes several entity
providers for handling serialization from and deserialization to Java types,
it does not support all possible media types. You can develop a custom
entity provider to handle binding Java types to message bodies.
topic Using custom entity formats.
Liberty profile:
Using content negotiation to serve multiple content types in JAX-RS applications
One of the advantages of RESTful applications is the ability to return
different representations of resources. With Representational State Transfer
(REST), clients and servers can exchange resources of the same media type
or use differing media types. Content negotiation enables clients and
servers to agree on the content format that is used to exchange data.
topic Using content negotiation to serve multiple content types in JAX-RS
applications .
Liberty profile:
Using JAX-RS context objects to obtain more information about requests
JAX-RS provides different types of context to resource classes and
providers. You can use context objects to access request information such
as discovering the HTTP headers that are sent as part of the request.
Context objects also provide convenience methods for evaluating a request
and building an appropriate response.
topic Using JAX-RS context objects to obtain more information about
requests.
Liberty profile:
Using handlers to enhance request and response processing
You can implement handlers on the server-side of a JAX-RS application to
enhance request and response processing.
topic Using handlers to enhance request and response processing
Liberty profile:
Using multipart content in JAX-RS application requests and responses
Using multipart messages, servers and clients can transmit multiple
messages using a single message. Multipart messages are useful when both
the client and server need to send multiple requests but want to save the
cost of sending and receiving entire HTTP request and responses for each
part.
topic Using multipart content in JAX-RS application requests and
responses.
Liberty profile:
Using multipart/form-data content in JAX-RS application requests and
responses
A frequently used content type for submitting files through an HTML form
is multipart/form-data. The JAX-RS implementation from IBM greatly
simplifies the processing of such data by automatically splitting the parts
and automatically decoding them. If such automatic processing is not
wanted, the resource can instead receive the parts in an object so
processing of the parts is under the complete control of the resource
method.
topic Using multipart/form-data content in JAX-RS application requests
and responses.
Liberty profile:
Implementing secure JAX-RS applications
The JAX-RS runtime environment from IBM is driven by a servlet derived
from the Apache Wink project. Within the WebSphere Application Server
environment, the lifecycle of servlets is managed in the web container.
Therefore, the security services offered by the web container are applicable
to REST resources that are deployed in WebSphere Application Server.
topic Implementing secure JAX-RS applications.
Liberty profile:
v Secure JAX-RS resources using annotations
v (optional) Secure JAX-RS clients using SSL
v 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 descriptor
is not relevant to the Liberty profile. After you install the
AddressBookApp application in the Liberty profile, the WEB-INF\web.xml
file 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 WAR
file. 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 documentation
Web Application Description Language (WADL) is a description language
for HTTP-based applications. It is currently a World Wide Web Consortium
(W3C) Member Submission. WADL can be used by programs to give
information about the service in a machine-processable method. For
instance, you can use an XSLT document to transform the WADL
documentation by using a custom XSLT and an XSLT processor.
topic Using WADL to generate service documentation.
Liberty profile:
Using the Apache Wink REST client inside server applications to issue requests
You can use the Apache Wink REST client as a client that can be run to
send requests to your JAX-RS application.
topic Using the Apache Wink REST client inside server applications to
issue requests.
Note: Any reference to thin client, unmanaged client, or administrative
console are not relevant to the Liberty profile.
Note: If you use the jaxrs-1.1 feature, you must specify the servlet-3.0 or
jsp-2.2 features separately.
Deploying a messaging application to the Liberty profile
To deploy messaging applications that use the Java Messaging Service (JMS), you
add 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 deploy
the messaging application that uses JMS. For more information, see Creating a
Liberty profile server manually on page 95.
About this task
The wasJMSServer-1.0 feature provides support for applications that use Java
Messaging Service 1.1 specifications.
Procedure
v 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 the
remote 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 feature
The monitor-1.0 feature provides monitoring support for user runtime
components.
v JVM
v Web applications
v Thread pool
v JAX-WS endpoints
v Session management
For more details, see Liberty features on page 14.
Procedure
1. 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 monitoring
This topic provides an overview of the JvmStats MXBean for JVM monitoring in
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 attributes
are 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 started
v 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 Interface
The management interface of JVM monitoring is
com.ibm.websphere.monitor.jmx.JvmMXBean. You can use 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 the management interface, see the Java API
Liberty profile: Web application monitoring
This topic provides an overview of servlet MXBean for web application monitoring
of the Liberty profile.
Performance data is available for each Servlet in the Web Application. Each servlet
has 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 Servlet
WebSphere:type=ServletStats,name=MyApp.MyServlet
This MXBean is responsible for reporting ServletStats for each servlet. Following
key data is available for ServletStats MXBean:
v Request Count
v Response Time
v Servlet Name
v 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.
.
The management interface of web application monitoring is
com.ibm.websphere.webcontainer.ServletStatsMXBean. You can use the
management interface to obtain a proxy object. See Liberty profile:
Examples of accessing MBean attributes and operations on page 396.
Liberty profile: ThreadPool monitoring
This topic provides an overview of ThreadPool MXBean for thread pool monitoring
in the Liberty profile.
All Web Requests executes in the thread pool, named Default Executor thread
pool. You can monitor the usage of Default Executor thread pool using
ThreadPoolMXBean.
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
The management interface of ThreadPool monitoring is
com.ibm.websphere.monitor.jmx.ThreadPoolMXBean. You can use the
management interface to obtain a proxy object. See Liberty profile:
Liberty profile: JAX-WS monitoring
This topic provides an overview of the endpoint MXBean for JAX-WS monitoring
of the Liberty profile.
Performance data is available for each endpoint and operation in the JAX-WS
application. Each web service endpoint has its own MXBean.
The ObjectName for identifying each endpoint MXBean might be in one of the
following 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 endpoint
and 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)..
.
The management interface for web service application monitoring is
org.apache.cxf.management.counters.ResponseTimeCounterMBean. You can
use the management interface to obtain a proxy object. See Liberty profile:
For more information about the
org.apache.cxf.management.counters.ResponseTimeCounterMBean, see the
Apache 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_lite
WebSphere: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 Count
v Live Count
v Active Count
v InvalidatedCount
v 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
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 influence
application performance. You can use these parameters and attributes to achieve
better performance.
Procedure
v Tune the JVM.
Tuning the JVM is a most important tuning step whether you configure a
development or production environment. When you tune the JVM for the
Liberty 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 per
line. See Customizing the Liberty profile environment on page 352 for more
information. 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 maximum
heap size to whatever value is needed for your application. For a production
environment, setting the minimum heap size and maximum heap size to the
same value can provide the best performance by avoiding heap expansion and
contraction.
v Tune transport channel services.
The transport channel services manage client connections, I/O processing for
HTTP, thread pools, and connection pools. For applications on the Liberty
profile, the following attributes are available for different elements that can be
used to improve runtime performance, scalability, or both. For each of these
attributes, see Liberty profile: Configuration elements in the server.xml file on
page 97.
maxKeepAliveRequests of httpOptions
This option specifies the maximum number of persistent requests that
are allowed on a single HTTP connection if persistent connections are
enabled. A value of -1 means unlimited. This option supports low
latency or high throughput applications, and SSL connections for use in
situations where building up a new connection can be costly. Here is an
example of how you code this option in the server.xml file:
<httpOptions maxKeepAliveRequests="-1" />
coreThreads of executor
This option specifies the core number of threads to associate with the
executor of the thread pool. The number of threads associated with the
executor will quickly grow 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 threads on the system.
Tip: Start your tuning with coreThreads="5" for each hardware thread
or logical processor. For example, for a two-core SMT-4 machine, which
represents 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 connectionManager
This option specifies the maximum number of physical connections for
the connection pool. The default value is 50. The optimal setting here
depends on the application characteristics. For an application in which
every thread obtains a connection to the database, you might start with
a 1:1 mapping to the coreThreads attribute. Here is an example of how
you code this option in the server.xml file:
<connectionManager ... maxPoolSize="40" />
purgePolicy of connectionManager
This option specifies which connections to destroy when a stale
connection is detected in a pool. The default value is the entire pool. It
might be better to purge only the failing connection. Here is an example
of how you code this option in the server.xml file:
<connectionManager ... purgePolicy="FailingConnectionOnly" />
numConnectionsPerThreadLocal of connectionManager
This option specifies the number of database connections to cache for
each executor thread. This setting can provide a major improvement on
large multi-core (8+) machines by reserving the specified number of
database connections for each thread.
Using thread local storage for connections can increase performance for
applications on multi-threaded systems. When setting
numConnectionsPerThreadLocal to 1 or more, these connections per
thread are stored in thread local storage. When using
numConnectionsPerThreadLocal, consider two other values:
The number of application threads
The connection pool maximum connections
For best performance, if you have n applications threads, set maximum
pool connections to at least n times the value of
numConnectionsPerThreadLocal attribute. For example, if you use 20
application threads, set the maximum pool connections to 20 or more; If
you set the value of numConnectionPerThreadLocal attribute as 2 and
there are 20 application threads, set the maximum pool connection to 40
or more. Here is an example of how you code this option in the
server.xml file:
<connectionManager ... numConnectionsPerThreadLocal="1" />
statementCacheSize of dataSource
This option specifies the maximum number of cached prepared
statements per connection. To set this option, complete the following
prerequisite:
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.
<dataSource ... statementCacheSize="60" >
isolationLevel of dataSource
The data source isolation level specifies the degree of data integrity and
concurrency, 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_UNCOMMITTED
Dirty reads, non-repeatable reads, and phantom reads can occur.
TRANSACTION_READ_COMMITTED
Dirty reads are prevented; non-repeatable reads and phantom
reads can occur.
TRANSACTION_REPEATABLE_READ
Dirty reads and non-repeatable reads are prevented; phantom
reads can occur.
TRANSACTION_SERIALIZABLE
Dirty reads, non-repeatable reads, and phantom reads are
prevented.
<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 logging
component. See Liberty profile: Trace and logging on page 552. You can also use
the IBM Support Assistant Data Collector (ISADC) command tool in the
${wlp.install.dir}/bin directory to quickly collect diagnostic files, such as log
files, 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.
Details of the main known restrictions that apply when
using 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 JDKs
v Troubleshooting security
v Troubleshooting LDAP on page 549
v Troubleshooting SSL on page 550
v Troubleshooting JAX-WS on page 551
v
v
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 you
are using are compliant with Java Version 6 or later, and are at a current service
level. See Minimum supported Java levels on page 566.
Troubleshooting security
This section describes some common security problems and solutions you can
choose.
SESN0008E: A user authenticated as anonymous has attempted to access a
session owned by user:LdapRegistry/cn=steven,o=myCompany,c=US.
This error happens when an unauthenticated user tries to access a session
created by an authenticated user. Session security that is enabled by default
prevents unauthorized access of the sessions. Only the user who created a
session can access it. See session security for more information.
This error can happen when you use a JSP (login.jsp for example) for
your form-login and the SSO token sent by the browser is expired. Because
the SSO token is expired, the user is prompted to log in again using the
login.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 whose
token is expired. However, the token is expired and the user is not
authenticated, no credentials are established when accessing this session
that results in this error.
To avoid this error, restart the browser that starts a new session, or
configure the login.jsp file to not create the session by default. If you
choose to update the login.jsp file, set <%@ page session="false" %>.
CWWKS9104A: Authorization failed for user {0} while invoking {1} on {2}. The
user is not granted access to any of the required roles: {3}.
This error occurs when you do not have authorization to the roles required
by the application. Make sure that the user or the group it belongs to is
mapped to at least one of the roles that are mentioned in the error
message. 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 page
472.
CWWKZ0013E: It is not possible to start two applications called {0} followed by
unexpected security behavior and error messages such as CWWKS9104A.
This error occurs when you specify your application in both the
server.xml by using theapplication element and in the dropins folder. As
a result, the application is attempted to be installed twice and the security
configuration in the server.xml file might or might not take effect. To fix
this, you must remove your application from the dropins folder and copy
it to another directory. If you have to leave it in the dropins folder, you
must disable the application monitoring by using the following code in
your 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 SAF
user on z/OS) is created when authentication fails or when your servlet or
JSP is unprotected. An unauthenticated user can access your servlet or JSP
if you do not define any security constraints or if you map the EVERYONE
special subject to the role required by your application. Review the
user-to-role mappings in the ibm-application-bnd.xmi/xml and server.xml
files. 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 on
page 472.
v If a certain user cannot be authorized to your servlet or JSP, review who
is mapped to that role by examining the ibm-application-bnd.xmi/xml
and server.xml files. You can map a role to a user, group, or special
subject. If your role is mapped to the EVERYONE special subject, any user
is granted access. If your role is mapped to the ALL_AUTHENTICATED
special subject, any authenticated user is granted access. Remove these
special subjects if you want to further limit who can access your servlet
or JSP. Finally, check what group the user belongs to. Although the user
might not have explicit access, the group might be mapped to the role.
In this case, remove the user from the authorized group or remove the
group from role mapping. See Configuring authorization for
applications 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 servers
that use the same LTPA keys, password, and ssoCookieName attribute of
webAppSecurity element have the same Universal Time (UTC) and share
the same user registry. Also, if the token expires or if the cookie is sent
from a web browser after changing the user registry in a manner that is
inconsistent, like modifying the realm or removing the user the cookie
represents, the SSO fails and the user is prompted to enter the credential
information again. See Customizing SSO configuration using LTPA
cookies for the Liberty profile on page 468.
Debugging security public APIs.
WSSecurityHelper and RegistryHelper are loaded even if security is not
enabled, for example, if a security feature - appSecurity-1.0,
appSecurity-2.0 or zosSecurity-1.0 - is not specified. If security is not
enabled, then WSSecurityHelper.isServerSecurityEnabled() and
WSSecurityHelper.isGlobalSecurityEnabled() methods both return false,
and RegistryHelper.getUserRegistry() method returns null.
Other security public API classes might not be loaded if security is not
enabled. If you try to access these classes and call a method on one of
these classes, you might get a java.lang.NoClassDefFoundError exception.
To avoid getting java.lang.NoClassDefFoundError exceptions, you must
first test to see whether security is enabled by calling the
WSSecurityHelper.isServerSecurityEnabled() or
WSSecurityHelper.isGlobalSecurityEnabled() class, and then call other
security public API classes only when security is enabled. See Liberty
profile: Security public APIs on page 43 for examples of this coding
technique.
Note: This behavior is different from the full profile. In full profile, all
classes are always loaded regardless of whether security is enabled or not.
Troubleshooting LDAP
This section describes some common LDAP problems and solutions you can
choose.
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 server
cannot be reached. Check your LDAP server to verify that it is running
and 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 is
javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.g: PKIX path building
failed: java.security.cert.CertPathBuilderException: unable to find valid
certification path to requested target]
If you enable SSL on your LDAP server without copying the signer of the
LDAP 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 your
truststore.
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 usable
sockets on the local server are exhausted, which can result in a failure
when connecting to your LDAP server. Make sure that the socket is not
used and try again.
CWWKS1100A: Authentication did not succeed for user ID xxxxx. An invalid
user ID or password was specified
This FFDC exception might happen on the server even though the user
mentioned in the message above is a valid user on the LDAP server under
heavy load. With the LDAP configuration, you can add the
reuseConnection=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 an
SSL port and the SSL port is not available. The port might not be available
because of a missing SSL configuration or some error in the SSL
configuration definition. Check the SSL configuration in the server.xml file
to make sure that it exists and is correct. See Securing communications
with 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.ManagedServiceFactoryTracker
aSyncReadNupdate. Exception thrown while trying to read configuration and
update ManagedServiceFactory. Exception = java.lang.IllegalArgumentException:
Unknown, incomplete configuration: missing id field" at
ffdc_12.04.18_16.09.42.0.log
This error occurs when a keystore element exists in the configuration
without an ID field. If you use a minimal SSL configuration, set the ID
field to defaultKeyStore.
You might get an exception if using a LDAP user registry with
sslEnabled and a sslRef value is not specified.
For example, a configuration has sslEnable set to true but there is not a
sslRef 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 SSL
configuration 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 configuration
should be placed in the sslRef field.
Troubleshooting JAX-WS
This section describes some common JAX-WS problems and solutions you can
choose.
The org.apache.cxf.bus.extension.ExtensionException occurred when deploying
web services application on the Liberty Profile.
If your application has CXF libraries and configurations embedded already
and you want to deploy the application to the Liberty Profile, you must
make sure that the jaxws-2.2 server feature is disabled by removing the
feature from the server.xml file.
The java.lang.NoClassDefFoundError exception occurred when running IBM
fastpath with the Oracle JVM.
To use IBM fastpath Java Architecture for XML Binding (JAXB), you can
configure the com.ibm.xml.xlxp.jaxb.opti.level custom property to
control whether optimization methods are enabled for JAXB unmarshalling
(deserialization) and marshalling (serialization). If you are experiencing the
java.lang.NoClassDefFoundError exception when running IBM fastpath
JAXB with the Oracle JVM, you can change the value of
com.ibm.xml.xlxp.jaxb.opti.level property to 0 to turn off the
optimization. For example, you can use the
-Dcom.ibm.xml.xlxp.jaxb.opti.level=0 property in the command line, or
add 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 property
on the Java virtual machine custom properties page.
The java.lang.NoClassDefFoundError : com.ibm.CORBA.iiop.ORB exception
occurred 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 the
Oracle JVM and the jaxws-2.2 feature is already enabled on the Liberty
profile. To resolve this problem, you can use the
-Dcom.ibm.websphere.thinclient=true property when running the full
profile 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 property
on the PM39777: ADMINISTRATIVE THIN CLIENT USING SOAP
CONNECTOR AND SUN JDK DOES NOT WORK page.
An Empty file returned when retrieving binary files from an MTOM service to a
MTOM client.
This scenario happens when a MTOM client sent binary files successfully
to an MTOM service, but an empty file is returned when retrieving the
same binary files back from the MTOM service.
As a workaround, you can create a new DataHandler and initialize the
DataHandler by filling the content of the binary file. For example, use a
FileDataStore object to read from I/O and return the newly created
DataHandler 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 when
using XMLGregorianCalendar in xsd:gMonth format with the Oracle JVM.
This error occurs when you use the XMLGregorianCalendar class to store
gMonth format constants as part of your SOAP request on client side and
the jaxws-2.2 feature is enabled on the Liberty profile with the Oracle
JVM. The root cause is that the Oracle JVM supports the new standard
format --MM for the xsd:gMonth type while the latest JAXB RI (Reference
Implementation) only supports the format of --MM--.
To resolve this problem, you can change the Oracle JVM to the IBM JVM
for both the client side and the server side applications.
The java.io.FileNotFoundException occurred when resolving WSDL files
specified by the wsdlLocation attribute.
This error occurs when you specify the WSDL file as in the code
wsdlLocation = "file:/WEB-INF/wsdl/a.wsdl" and the WSDL file is
packaged within your application. If you want to refer to the WSDL file
that is packaged in your application, you must use relative URIs for the
wsdlLocation attribute defined in the @WebService, @WebServiceProvider,
@WebServiceClient or @WebServieRef annotation.
The relative URI for the wsdlLocation attribute must be one of the
following 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 when
you apply service updates. For more information, see Applying a fix pack to a
Liberty profile archive installation on page 84 and Applying an interim fix to a
Liberty profile archive installation on page 86.
Liberty profile: Trace and logging
The product has a unified logging component. It provides base implementations of
trace and FFDC services, for runtime code and for your code, to gather debug
information.
The trace and FFDC implementations both apply an initial configuration during
static initialization. You can modify this default initial configuration by specifying
properties in the server configuration files (see Administering the Liberty profile
manually on page 351) or bootstrap.properties file (see Specifying Liberty
profile bootstrap properties on page 95).
Messages are written to stdout as well as to the defined trace destination. OSGi
logging output is intercepted and output through the trace support. There is also
interception 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 the
server configuration files are processed; in this case you set them in the
bootstrap.properties file instead of the server configuration. You do not usually
need to do this to get logging from your own code, which is loaded after server
configuration processing, but you might need to do this to analyze problems in
early 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 the
bootstrap.properties file. Any settings in the bootstrap.properties file are used
from the time the server reads the bootstrap.properties file until the time the
If you set logging attributes in the server.xml file, you might want to set the
corresponding logging properties in the bootstrap.properties file to the same
value to avoid changes in configuration between startup time and runtime.
Note: If no logging properties are set in the bootstrap.properties file, the server
will start the logging system using the default logging settings.
Table 30. Logging properties for the Liberty profile. Column 1 contains attributes that can be
set in the server.xml file. Column 2 contains equivalent properties that can be used in the
bootstrap.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 all
log files, including FFDC.
maxFileSize com.ibm.ws.logging
.max.file.size
The maximum size (in MB) that a log
file can reach before being rolled. The
Liberty profile runtime only does
size-based log rolling. To disable this
attribute, set the value to 0. The
maximum file size is approximate.
maxFiles com.ibm.ws.logging
.max.files
If an enforced maximum file size
exists, this setting is used to
determine how many of each log file
are kept. This setting also applies to
the number of exception logs that
summarize exceptions occurred on
any given day). So if this number is
10, you might have 10 message logs,
10 trace logs, and 10 exception
summaries in the ffdc/ directory.
Table 30. Logging properties for the Liberty profile (continued). Column 1 contains
attributes that can be set in the server.xml file. Column 2 contains equivalent properties
that can be used in the bootstrap.properties file. Column 3 provides description of each
logging property.
Attribute Equivalent property Description
consoleLogLevel com.ibm.ws.logging
.console.log.level
This filter controls the granularity of
messages that go to the console.log
file. The valid values are INFO,
AUDIT, WARNING, ERROR, and
OFF. By default, the level is AUDIT.
messageFileName com.ibm.ws.logging
.message.file.name
The message log has a default name
of messagel.log. This file always
exists, and contains INFO and other
(AUDIT, WARNING, ERROR,
FAILURE) messages in addition to
System.out and System.err. This log
also contains time stamps and the
issuing thread ID.
traceFileName com.ibm.ws.logging
.trace.file.name
The trace.log file is only created if
additional or detailed trace is
enabled. stdout is recognized as a
special value, and causes trace to be
directed to the original standard out
stream.
traceSpecification com.ibm.ws.logging
.trace.specification
The trace string is used to selectively
enable trace. The default is *=info.
traceFormat com.ibm.ws.logging
.trace.format
This attribute controls the format of
the trace log. The default format for
the Liberty profile is ENHANCED.
You can also use BASIC and
ADVANCED formats as in the full
profile.
You can set logging properties in the server configuration file by selecting Logging
and Tracing in the Server Configuration view in the developer tools, or by adding
a 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 the
traceSpecification property, see the logging element in Liberty profile:
Note: On all platforms, logs are written in the default system encoding.
v
Windows
On Windows systems, there are two types of encoding: OEM code
page, which is used for console output, and ANSI code page, which is used to
read and write files. The console.log file uses the OEM code page, and all other
logs use the ANSI code page.
v
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 JDBC
calls are operating slowly.
Overview
Timed operations help WebSphere Application Server
administrators see, by way of a logged warning, when certain JDBC calls in their
application server are operating more slowly than expected.
Timed operations are disabled by default and are enabled by adding the
timedoperations-1.0 feature to the server.xml file.
The system looks for abnormal patterns in the execution times of several types of
JDBC calls, keeps track of multiple recent execution times, and computes the mean
and standard deviation for each timed operation. Specific messages are logged so
that administrators know what is slow when an abnormal pattern is detected. The
timed operation feature uses an exponentially weighted moving average, where the
most recent durations have more weight than older durations. When computing
the moving average, a certain number of durations are excluded in order to avoid
a high variance during the warm-up period. The timed operations feature does not
log a warning if a single duration is too slow, but instead uses the Western Electric
rules to decide if a warning should be logged. A warning is logged in the
following 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 from
periodic garbage collection.
Periodically, the system generates a report to the logs that contains the ten longest
JDBC timed operations. The frequency and enablement of this report is
configurable 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 the
server.xml file:
<timedOperation enableReport="false"/>
To change the frequency of the report to once every 12 hours, add the following
line to server.xml:
<timedOperation reportFrequency="12"/>
You can also use the server dump command to get a full report of all timed
operations, 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 cities
values (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: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 that
the 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 194ms
for websphere.datasource.execute:jdbc/exampleDS:insert into cities values (myHomeCity, 106769, myHomeCounty)
for websphere.datasource.execute:jdbc/exampleDS:select county from cities where name=myHomeCity
for 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 151ms
for 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 is
provided as a part of the product.
Overview
Note: The basic log and trace facility is enabled by default. To use HPEL you must
enable it.
HPEL provides a convenient mechanism for storing and
accessing log, trace, System.err, and System.out information produced by the
application server or your applications. It is an alternative to the basic log and
trace facility, which provides the JVM logs and diagnostic trace files commonly
named 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. See
the following figure to understand how applications and the application server
store log and trace information.
Log data
repository
Trace data
repository
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 is
typically intended to be reviewed by administrators. This includes any
information 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 or
higher (including Detail, Config, Info, Audit, Warning, Severe, Fatal, and
any custom levels at level Detail or higher).
HPEL trace data repository
The trace data repository is a storage facility for trace records. Trace data is
typically intended for use by application programmers or by the
WebSphere Application Server support team. This includes any information
applications or the server write to the OSGi logging service at level
LOG_DEBUG or java.util.logging at levels below level Detail (including
Fine, 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 log
file is provided for convenience, primarily so that log content can be read
without having to run the LogViewer command-line tool to convert the log
data repository content to plain text.
The text log file does not contain any content that is not also stored in
either the log data repository or trace data repository. You can disable the
text log to enhance server performance. The text log can be configured to
record trace content for debugging convenience.
Note: Writing trace to the text log is expensive from a performance
perspective.
Log and trace performance
HPEL has been designed and tested to significantly
outperform the existing basic log and trace facility. One result is that the
application server can run with trace enabled while causing less impact to
performance than tracing the same components using basic logging. Another result
is that applications that frequently write to the logs can run faster when using
HPEL. A number of factors contribute to the overall performance of HPEL logging
and tracing.
Log and trace events are each stored in only one place
Log events, System.out, and System.err are stored in the log data
repository. Trace events are stored in the trace data repository. If the text
log file is disabled, HPEL will only write log and trace content to these
repositories. Storing each type of event in one place ensures that
performance is not wasted on redundant data storage.
Log events, and optionally trace events, are written to the text log file
when it is enabled. Since this data is always also stored in the log data and
trace data repositories, the text log file content is redundant. The text log is
convenient for users who do not want to run the LogViewer command-line
tool to see their logs and trace; but you can disable the text log if this
convenience is not needed.
Data is not formatted unless it is needed
Formatting data for a user to read uses processor time. Rather than format
log event and trace event data at run time, HPEL log and trace data is
stored more rapidly in a proprietary binary representation. This improves
the performance of the log and trace facility. By deferring log and trace
formatting until the LogViewer is run, sections of the log or trace that are
never viewed are never formatted.
You can enable the text log file, which stores the log data and trace data in
an already readable text format.
Note: Disable the text log when performance of your server is a key
concern, 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 the
same amount of data in small blocks. HPEL provides the capability to
buffer log and trace data before writing it to disk. By default, log and trace
data is stored in an 8 KB buffer before being written to disk. If the buffer is
filled within 10 seconds, the buffer is written to disk. If the buffer is not
filled within that time it is automatically written to disk to ensure that the
logs 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 or
trace, or how long to retain log and trace records, and leave the management of
log 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-use
command (LogViewer), avoiding any possible confusion over which file to access
for certain content.
Reading from the log data and trace data repositories
The log data and trace data repositories are stored in a WebSphere
Application Server proprietary format and cannot be read using text file
editors such as Notepad or VI. You can copy the log data and trace data
repositories 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 for
HPEL users to work with the log data and trace data repositories. The
LogViewer provides filtering and formatting options that make finding
important content in the log data and trace data repositories easy. For
example, a user might filter any errors or warnings, then filter all log and
trace entries that occurred within 10 seconds of a key error message on the
same thread.
Filtering using log and trace record extension content
HPEL provides the capability for developers to add custom extensions to
log and trace records using a log record context API
(com.ibm.websphere.logging.hpel.LogRecordContext). You can use the
LogViewer command-line tool to filter records based on the content of log
and trace record extensions.
Development resources
HPEL has been designed to make working with log and trace content more flexible
and effective than the basic logging facility. Log and trace content can be easily
filtered 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 create
powerful log handling programs using the HPEL API.
Reading the log data and trace data
Developers can use the com.ibm.websphere.logging.hpel API to read the
log data and trace data repositories
HPEL API
An API has been provided to make it easy for developers to develop tools
to consume content from the HPEL log and trace repositories. For example,
a developer might write a Java program to search the log and trace content
to find any messages with message IDs that match a known list of
important message IDs. This API is in the com.ibm.websphere.logging.hpel
package. Refer to the API documentation for details on the HPEL log
reading API.
Log and trace record extensibility
As with other log and trace record fields, developers can access the record
extensions using the HPEL API. This is useful when writing tools to read
from log and trace repositories. Developers can also make use of the log
record context API to access extensions in custom log handlers, filters, and
formatters at run time.
LogViewer command-line tool
Use the LogViewer command to query the contents of the High Performance
Extensible Logging (HPEL) log and trace repositories. You can also use the
LogViewer command to view new log and trace repository entries as the server
writes content to them.
LogViewer
The High Performance Extensible Logging (HPEL) facility writes to the log and
trace repositories in a binary format. You can view, query and filter the repository
using the LogViewer command. The LogViewer command provides options for
quickly converting HPEL logs into a text file in various formats, including basic,
advanced, and Common Base Event format. The command also provides options
to make getting the data you need from the logs easier; for example, allowing you
to 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 trace
repositories:
v
Windows
(Windows) logViewer.bat
Optional parameters
[Liberty profile] servername
Specifies the name of the server whose log and trace data repositories you
want the logViewer command to use. This parameter is not needed in cases
where there is only one Liberty profile server created nor in cases where you
specify the path to the log and trace data repository root using the
-repositoryDir parameter.
-repositoryDir directory_name
Specifies the path to the repository directory. In the case where you want to
query both the log and trace data together, provide the path to the parent
directory, which contains both the log data and tracedata directories. If you use
the default repository location, profile_root/logs/application_server/, and run
this tool from the profile bin directory, then this argument is optional. The tool
checks the default location if one is not provided. If multiple application
servers exist in this profile with HPEL repositories, you are prompted to select
which server log and trace repository you want to view.
-outLog file_name
Specifies the file name you want the text output written to. If you do not
provide this information, the text output is displayed on the console.
-format basic | advanced | cbe-1.0.1
Specifies the output format. Supported formats include basic, advanced, and
the CBE-1.0.1 format. If you do not provide this information, the output is in
basic format.
-monitor [integer]
Specifies that you want the logViewer to continuously monitor the repository
and output new log record entries as they are created. You can provide an
optional integer argument after this parameter to specify how often you want
the LogViewer tool to query the repository for new records. By default the
logViewer queries the repository for new records every 5 seconds. When used
with other filtering options, only those new records that match the filter
criteria are displayed.
-help
Use this parameter to have the LogViewer tool list the full set of options that
are available.
-startDate date_time
You can filter the results that are displayed from the repository by date and
time. Use the startDate parameter to filter out log entries that occurred after
the date or date time provided as an argument. Provide either a date or date
and time, entered in the MM/dd/yy format or the MM/dd/yy H:m:s:S:z
format, where z represents timezone.
-stopDate date_time
Use this parameter to filter out log entries that occurred before the specified
date or date time. Provide the argument in the same format as the -startDate
option.
-level level_name
Specifies that you want the tool to only display those log events which match
the level name you provide as an argument. Valid values for the level name
are FINEST, FINER, FINE, DETAIL, CONFIG, INFO, AUDIT, WARNING,
SEVERE, FATAL.
-minLevel level_name
Specifies that you want the tool to only display records which are at or above
the specified level. Valid values for the level name are FINEST, FINER, FINE,
-maxLevel level_name
Specifies that you want the tool to only display records that are at or below the
specified level. Valid values for the level name are FINEST, FINER, FINE,
-includeLoggers logger_name
When this option is used, only log events from the specified loggers are
included 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 parent
logger. When used in combination with the -excludedLoggers option, the more
specific match determines if the log event is included or excluded.
-excludeLoggers logger_name
Use this option to exclude log events from the specified loggers in the
LogViewer output. Separate multiple entries with a comma. The * symbol can
be used as a wildcard to include all loggers below a parent logger. When used
in combination with the -includeLoggers option, the more specific match
determines if the log event is included or excluded.
-thread thread_id
Use this option to restrict LogViewer output to only those log events from a
specific thread. Any log messages that were not created by the thread ID
provided as an argument to this option are not displayed. Specify the thread
ID in hex format.
-extractToNewRepository directory_name
This option redirects log and trace records from a binary repository to a new
binary 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 new
repository. This option uses the directory path where the new repository must
be written as an argument. Therefore, the directory must be empty. If the
directory does not exist, the directory is created. However, errors that occur
during the directory creation might create extraneous directories.
-listInstances
Use this option to list the IDs of available server process instances that are
available to use with the -instance option. After running LogViewer with the
-listInstances option, you can then use the -instance option to invoke
LogViewer with one of the server process instance IDs as an argument. Since
this option does not process any log or trace records, all other options are
ignored when you specify this option.
-instance instance_id
Use this option to retrieve the log and trace data for a given server process
instance 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 that
contains subprocesses, such as the z/OS operating system.
If this option is combined with -latestInstance, -instance is ignored.
-latestInstance
Use this option to retrieve the log and trace data from the most recent server
instance. If this option is used with the -instance option, the -instance option is
ignored.
-message match_string
Use this option to retrieve only log or trace data with a message field that
matches the requested text.
-includeExtensions name[=value][,name[=value]]*
Use this option to retrieve the log and trace data with an extension name that
matches the requested name, and an extension value that matches the
requested value. You can also use this option to retrieve the log and trace data
with an extension name that matches the requested name, and an extension
value 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 as
extensions, and so cannot be filtered on with this option.
Separate multiple name=value arguments with a comma. Specify '==' (two
equals signs) in place of '=' (one equals sign) in cases where the name or value
must contain an equal sign. Specify ',,' (two commas) in place of ',' (one
comma) in cases where the name or value must contain a comma.
-encoding character_set
Specifies the character set that the LogViewer command will use for text
output.
Filtering considerations
Be aware of LogViewer filtering optimizations. The LogViewer tool is able to filter
log and trace data most efficiently when used with the following filter options:
v startDate
v stopDate
v thread
v level
v minLevel
v maxLevel
Example usage
See the following examples of LogViewer commands used with full profile servers
on UNIX-based systems. The examples show how to run LogViewer from the
profile 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 the
advanced 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 specific
repository 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 with
value 'WebContainer : 6'
logViewer.sh -includeExtensions thread="WebContainer : 6" -format advanced
v Write events from the default repository that were a part of the request with
requestID 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 servicing
the PlantsByWebSphere application.
logViewer.sh -includeExtensions appName=PlantsByWebSphere
Configuring HPEL in the Liberty Profile
You can configure the High Performance Extensible Logging (HPEL) log and trace
framework. Use this information as a guide for configuring HPEL in your Liberty
profile.
About this task
HPEL provides faster log and trace handling capabilities and more flexible ways to
use 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. The
bootstrap.properties file specifies properties that need to be available before the
main configuration is processed, and are kept to a minimum. The server.xml file is
the primary configuration file for the server.
The server.xml file and its associated files use a simple xml format that is suitable
for most text editors. A richer editing experience is provided by the eclipse server
adapter for liberty (WAS4D+ adapter), which uses a generated schema to provide
drop-down lists of available choices, auto-completion, and other editing tools.
The bootstrap.properties file specifies whether the server should use HPEL as the
log and trace framework, or the default log and trace framework.
You can configure HPEL through the server configuration or the
bootstrap.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 you
need to analyze problems that occur early in server start or configuration
processing. In this case, you can configure HPEL in the bootstrap.properties
file.
You can set Logging properties in either the bootstrap.properties or the
server.xml file. Use attributes in the server.xml file, or use equivalent properties
in the bootstrap.properties file. Any settings in the bootstrap.properties file are
used from the time the server reads the bootstrap.properties file until the time the
When HPEL is enabled, the maxFileSize, maxFiles, messageFileName,
traceFileName, and traceFormat logging element attributes are ignored (since
HPEL runs without trace.log and messages.log files). The traceSpecification
and consoleLogLevel attributes continue to be used to set the trace specification
and the level for the console log. The logDirectory attribute is ignored in cases
where the HPEL dataDirectory attribute is explicitly provided -- otherwise the
logDirectory controls the placement of HPEL files.
If you set logging or HPEL attributes in the server.xml file, you can avoid changes
in configuration between startup time and runtime by setting the corresponding
properties in the bootstrap.properties file to the same value. Note that if no logging
or HPEL properties are set in the bootstrap.properties file, the server uses the
default logging and HPEL settings.
Procedure
v Enable HPEL for the server by updating the bootstrap.propertiesfile. In the
bootstrap.properties file, add the following text on a line by itself:
v Configure the HPEL settings. Use the following parameters to configure HPEL.
All subelements listed are subelements of the logging element in the server.xml
file. The following table lists the HPEL attributes that are configurable in the
server.xml file and the equivalent properties that can be set in the
Table 31. HPEL attributes that are configurable in server.xml and the equivalent properties that can be set in
Logging
subelement 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 enable
HPEL:
The following example shows a server.xml file with the HPEL subelements. The
log content is set to expire after 96 hours, the trace content is set to retain a
maximum of 1024MB, and the text log is set for advanced format:
<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: Configuration
Results
After you restart the server, the HPEL log and trace framework will be enabled
and configured.
Liberty profile: Runtime environment known restrictions
There are some known restrictions that apply when working with the Liberty
profile 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 the
Java 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 the
JDK from IBM. If you are developing applications on Windows or Linux, and you
plan to deploy those applications to a server running on the WebSphere
Application Server full profile, you should use the JDK from IBM. For HP systems
and Mac OS, use the JDK from Oracle.
The JDK from IBM is available in many IBM products. For example, WebSphere
Application Server Version 7 includes the Java 6 JDK from IBM.
The installation directory name and path cannot include
non-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 installation
directory names and paths.
Changing the JDBC data source at run time might result in JPA
failures
If the database dictionary type is not specified through properties, it is detected
and calculated by OpenJPA when the first entity manager is created and the
database connection is made. This database dictionary type is used for all entity
managers that are subsequently created. If the JDBC data source is changed while
an application is running, the entity manager factory does not detect this change
and 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, and
JDBC vendor properties at run time might result in JPA failures
If you update the configuration of dataSource, jdbcDriver, connectionManager or
any of the JDBC vendor properties lists (for example, properties.db2.jcc or
properties.oracle) while the server is running, you might see J2CA8040E failures.
These failures state that multiple dataSource elements cannot be associated with a
single connectionManager. These failures are generated even if your configuration
associates 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 by
getRealPath must be deployed as an expanded application, not
as a WAR file
The Java EE specification states that the getRealPath() method returns a null
value if the content is being made available from a web archive (WAR) file. When
you deploy a WAR file to the Liberty profile, the profile does not automatically
extract the archive file into a directory structure. Therefore the application might
fail 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 WAR
file. For example, you can manually extract the WAR file and copy the expanded
application to the dropins directory.
WebSphere Application Server full profile scripts do not work
with the Liberty profile
You cannot use any of the scripts under the bin directory of the WebSphere
Application 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 ("/") at
the 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 newer
versions of APIs that are provided by Java SE 6. JAX-WS, JAXB and the
javax.annotation.Resource annotation are all examples where a Java 6 SDK
contains older classes than those required by Java EE 6. When compiling your
application code against these APIs using Java SDK version 6, you need to use
classes that are provided by the Liberty profile rather than the Java SDK. You must
take 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 as
separate <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 the
endorseddirs 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 until
the server is stopped
When you unpublish a shared library from a server, the library JAR file is not
immediately released from the server. Therefore the operating system does not
know that the file is no longer in use, and does not let you delete the file. When
you 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 to
access 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 IBM
extension 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 of
an @Named CDI style bean, with other CDI beans injected into it. The following
CDI 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, or
java: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 to
the 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, the
application might still bind to the JAXB implementation that is cached from the
last server startup.
jaxrs-1.1 feature restriction
For the jaxrs-1.1 feature, Liberty profile does not support JAX-RS third-party
APIs 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, the
application might still bind to an incorrect JAXB version that is cached from the
last server startup.
v You cannot use annotation injections for JAX-WS handlers that are
associated 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 WebSphere
Application 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 lite
specification. See ejblite-3.1 feature restrictions on page 569.
Projects that are required by web fragment projects are not
automatically added to the Java build path
If you have a web application project that contains one or more web fragment
projects, and the web application project has references in its deployment assembly
page to projects that are required by the web fragment projects, then those
dependent projects (such as the JPA and Utility projects) are not automatically
added to the Java build path of the web fragment projects.
Manually add the dependent projects to the Java build path of the web fragment
projects in order for them to compile.
For more information about limitations, see Known problems and limitations for
WebSphere Application Server Developer Tools for Eclipse, Version 9.0 Beta
Liberty profile: Messages
When you use the Liberty profile, you might encounter system messages. Each
message has a unique message identifier, and includes an explanation of the
problem, and details of any action that you can take to resolve the problem.
Liberty profile system messages are logged from various sources, including
application server components and applications. For the Liberty profile, the
message identifier is 10 characters in length and has the following form:
CWXXX9999X
where:
CWXXX
Is a five-character alphabetic message prefix that identifies the Liberty
profile component.
9999 Is a four-character numeric identifier used to identify the specific message
for 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 message
prefix 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 (all
implementations)
Table 32. Alphabetic message prefixes for Liberty profile messages (continued)
CWWKM 0101-0150 Artifact API Zip
implementation
CWWKM 0151-0200 Artifact API File
implementation
CWWKM 0401-0450 Adaptable API
Implementation messages
(adaptable module factory /
adapter service)
CWWKM 1001-1100 Loose archive API (used by
the Eclipse-based tools
option that runs an
application directly from the
Eclipse workspace(The
Eclipse platform supports a
"virtual" application archive,
where a set of files that
appear to be in the same
archive file are actually
spread out across the Eclipse
workspace. Liberty calls this
a loose archive, and the
tools option that uses the
loose archive API is called
Run this application directly
from 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: Authentication
services
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 (common
code)
CWWKS 9200-9299 Web Application
Collaborator
CWWKS 9300-9399 Web Administration
Collaborator
CWWKT HTTP transport/dispatcher
CWWKW
0000-0099 JAX-WS common
CWWKW
0100-0199 JAX-WS for webContainer
CWWKW
0200-0299 JAX-WS security
CWWKW
0300-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 in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing 2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM websites are provided for
convenience only and do not in any manner serve as an endorsement of those
websites. The materials at those websites are not part of the materials for this IBM
product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
Software Interoperability Coordinator, Department 49XA
3605 Highway 52 N
Rochester, MN 55901
U.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 material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
Trademarks
IBM, the IBM logo, ibm.com
, Rational, and WebSphere are trademarks or

registered trademarks of International Business Machines Corporation in the
United States, other countries, or both. If these and other IBM trademarked terms
are marked on their first occurrence in this information with a trademark symbol
(
or

), these symbols indicate U.S. registered or common law trademarks owned
by IBM at the time this information was published. Such trademarks may also be
registered or common law trademarks in other countries. A current list of IBM
trademarks 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 registered
trademarks of Oracle and/or its affiliates.
Linux is a registered trademark of Linus Torvalds in the United States, other
countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
This product includes software developed by the Eclipse Project
(http://www.eclipse.org/).
Notices 577
Sending your comments to IBM
If you especially like or dislike anything about this book, please use one of the
methods listed below to send your comments to IBM.
Feel free to comment on what you regard as specific errors or omissions, and on
the accuracy, organization, subject matter, or completeness of this book.
Please limit your comments to the information in this book and the way in which
the information is presented.
To make comments about the functions of IBM products or systems, talk to your
IBM representative or to your IBM authorized remarketer.
When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate, without incurring
any 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 Laboratories
Hursley Park
WINCHESTER,
Hampshire
SO21 2JN
United 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: idrcf@hursley.ibm.com
Whichever method you use, ensure that you include:
v The publication title and order number
v The topic to which your comment applies
v Your name and address/telephone number/fax number/network ID.

Liberty V85next Beta

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Liberty V85next Beta

Hochgeladen von

Copyright:

Verfügbare Formate

IBM WebSphere Application Server

Application Server Developer Tools for Eclipse is a lightweight

EE, OSGi, Web 2.0,

Application Developer documentation.

Web services technologies

Java Architecture for XML

Web Services Metadata for the

Java API for XML-based RPC

Web application technologies

Dependency Injection for Java

Bean Validation 1.0 JSR 303

Java Transaction API (JTA) 1.1 JSR 907

data source to the Liberty profile.

online. The associated service is available from Fix Central.

LDAP filters. PID is

Directory Server LDAP filters. PID is

Transaction API (JTA) data source JNDI name

JDBC driver. PID is

Distributed operating systems

Distributed operating systems

operating system), the password is

<dataSource id="solidDB" jndiName="jdbc/solidDB">

, Rational, and WebSphere are trademarks or

Das könnte Ihnen auch gefallen