Previous | Home | Next


Working with the Liberty profile

This Liberty profile runtime and WebSphere Developer Tools are useful for development and pre-production testing.

The first scenario walks through the set up of a Liberty profile server. It shows how to configure for database connectivity, deploy an application, and package the whole runtime for further distribution.

In the second scenario, we use the package created in the first scenario to create a new environment. This scenario covers configuring security for an application, including...

Downloadable resources associated with this topic are available on the IBM Redbook site.


Scenario 1: Set up the Liberty profile


Create the Liberty profile server

  1. Install the Liberty runtime.

    If you installed Liberty using the WebSphere Developer Tools the server is already created.

  2. Create a new Liberty profile server...

      cd LIBERTY_PROFILE/bin
      server create server1

    This creates the server1 directory structure.


Configure the database connectivity

In this example, we use the Apache Derby version 10.8.2.2 database and Java Persistance API 2.0 feature provided with the Liberty profile.. For this example, you need to...

  1. Install the database
  2. Configure Liberty to support it

When the database environment is ready, create file bootstrap.properties in the same location as server.xml, and insert the configuration...

Open server.xml, and update it with configuration... 

<server description="server1 configuration">

    <featureManager>
        <feature>jsp-2.2</feature>
        <feature>jdbc-4.0</feature>
        <feature>jpa-2.0</feature> 
    </featureManager>
    
    <jdbcDriver 
                libraryRef="DerbyLib"/>

    <library filesetRef="DerbyFileset" 
             id="DerbyLib"/>

    <fileset dir="${derbyInstallDir}/lib" 
             
             includes="derby.jar"/>

    <dataSource 
                jdbcDriverRef="DerbyEmbedded"
                jndiName="jdbc/MyDataSource" 
                syncQueryTimeoutWithTransactionTimeout="false"
                type="javax.sql.DataSource">

        <properties.derby.embedded createDatabase="create" 
                                   databaseName="CUSTDB1"/>
    
    </dataSource>
    
    <httpEndpoint host="localhost" 
                  httpPort="${liberty.server1.http.port}"
                  httpsPort="${liberty.server1.https.port}" 
                  id="defaultHttpEndpoint"/>
</server>

The key elements of the configurations are:

If we are using a different database, create a CUSTDB1 before running the application.


Deploying the ITSOWebCustomerCredit application

With the configuration complete, we can start the server and deploy and run the application.

In this section, we use a sample ITSOWebCustomerCredit application included in the download material.

To start the server, use the server command from the Liberty bin directory:

To install the application, use the monitored dropins directory, or configure the application in server.xml:

The location specified for a configured application must not be in the dropins directory. If you copy an application into the dropins directory, and also specify the location in server.xml, you are telling the server to deploy the application twice, which results in an error.


Verify the application

To verify the application, inspect...

The log shows the server startup procedure:

  1. The kernel is starting.

  2. The feature manager initializes and reads the configuration from server.xml. The server is configured to listen on a given port and successfully created the data source.

  3. The server monitors the dropins directory, and as soon as the application is discovered in the dropins directory it is deployed to the runtime environment.

To verify if the application is running...

If the application was successfully deployed on the Liberty profile server, you will see the main page of the application.

To use the application, click...

We can also submit amounts of credits to customers in the database by providing the client number, the amount to credit the customer, and then clicking Submit.

Use the ITSOWebCustomerCredit application only for proof of technology purposes.

It is not production-ready code.


Configuring additional logging

A typical task when working with an application server is to enable and configure the logging properties to inspect for problems. The Liberty profile has a unified logging component. It provides a base implementations of the trace and FFDC services to gather debug information for both runtime and application code.

The trace and FFDC implementations apply an initial configuration during static initialization.

We can modify this default initial configuration by specifying properties in the server configuration file or bootstrap.properties file. There is also interception of java.util.logging output. 

<logging traceSpecification="*=audit=enabled:com.ibm.itso.*=debug=enabled"/>

In this example, the configuration specifies to log the outputs produced by the classes...

In this case, do not perform a server restart to apply the new setting to the server.

There might be some cases where to put logging properties into bootstrap.properties:

To configure the trace.log for the sample ITSOWebCustomerCredit application using bootstrap.properties...

Notice that this listing shows a similar logging level to the previous one using the dynamic server.xml file. After enabling trace, invoke the application, and inspect the trace.log file.

We can find several more events logged by the application that are not available in the standard messages.log.

If you analyze the source code of the sample ITSOWebCustomerCredit application, you find the Apache common loggings library was used for this purpose.

Apart from the logging capabilities, WebSphere Developer Tools comes with features to enable developers to debug their applications that are running on top of the Liberty profile server. To use this feature, the server needs to be started in debug mode. To start the server in this mode, right-click it in the Eclipse workbench, and click Debug.


Packaging the Liberty profile

We can package the applications and server in a compressed file for efficient distribution

First we have to stop the server...

Next, to package the whole runtime, enter the following command:

The command results in creating a server1.zip archive. Note that this archive contains not only the server configuration but also the full runtime and applications that were deployed to the server. This feature can also be useful to create a snapshot of the Liberty profile server.

To package only the server instance and its resources, use the --include=usr parameter instead. We can also use the WebSphere Developer Tools to package the server.


Scenario 2: Deploying the Liberty profile on production server

Distribute the package to the target environment

To deploy a packaged Liberty profile server decompress its archive file on the target environment. If you inspect the content of the server1.zip archive, you will see that it contains the root wlp directory with the server configuration, applications, and all libraries, so the server is ready to start.

You might also need to specify the location of the Java runtime for the server.

Alternatively we can use the WebSphere ND job manager console to deploy the package on a remote target.


Monitoring the server status

To check the server status, use the server command with your server name.

To verify the Liberty profile version...

To generate detailed information about the server, you might want to run the dump command, which gathers information about the whole server, including its resources.


Configure security

To secure the server, we configure the SSL certificate and a basic user registry for user authentication and authorization.

To configure the certificate, first we need to generate a server keystore using the securityUtility command.

We use a self-signed certificate for demonstration; however, on production servers import a certificate from a trusted provider to the server keystore. 

$ securityUtility.sh createSSLCertificate \
                     --server=server1 \
                     --password=passw0rd \
                     --validity=365 \
                     --subject=CN=liberty,O=IBM,C=PL

Creating keystore /IBM/WebSphere/wlp/usr/servers/server1/resources/security/key.jks
Created SSL certificate for server server1

Add the following lines to the server.xml to enable SSL: 

<featureManager>
  <feature>ssl-1.0</feature>
</featureManager>

<keyStore id="defaultKeyStore" 
             password="{xor}Lz4sLChvLTs=" />

The securityUtility command creates a key.jks keystore file located under...

...on the specified server. This command also prints the configuration lines that must be added to server.xml. Copy these lines into your server.xml file and try to access the application on a secured HTTPS port. In our configuration, we can use the following URL:

Notice that we do not need to restart the server because all the changes are being made inside server.xml, which is dynamically monitored.

Next, we set up a basic user registry and configure the ITSOWebCustomerCredit application to use it. For this configuration, we include a separate security.xml file, containing all of the security configurationNew security settings for the Liberty profile server. 

<server description="Web application security sample configuration">

    <featureManager>
        <feature>ssl-1.0</feature>
        <feature>appSecurity-1.0</feature>
    </featureManager>
    
    <keyStore id="defaultKeyStore" password="{xor}Lz4sLChvLTs=" />
    
    <basicRegistrySampleBasicRealm">
    
        <user name="user1" password="12345678" />
        <user name="user2" password="passw0rd" />
        <user name="user3" password="passw0rd" />
        <user name="user4" password="passw0rd" />
        
        <group name="group1">
          <member name="user3" />
          <member name="user4" />
        </group>
    
    </basicRegistry>
    
    <application type="war" 
             id="ITSOWebCustomerCredit" 
             name="ITSOWebCustomerCredit"
             location="${server.config.dir}/apps/ITSOWebCustomerCredit.war">
    
    <application-bnd>
        <!-- Map 'user3' to the 'Manager' role. -->
        
        <security-role name="Manager">
           <user name="user3" />
           <group name="group1" />
        </security-role>
        
        <!-- Map all authenticated users (those who can successfully login) to the 'Person' role. -->
        
        <security-role name="Person">
            <special-subject type="ALL_AUTHENTICATED_USERS" />
        </security-role>
        
        </application-bnd>
    </application>
</server>

The feature that you need to enable the user registry is appSecurity-1.0. The user repository definition is located within the basicRegistry tags. To enable authentication and authorization for the application, there is a section that maps the security roles to users and groups. We can find the security roles definition in web.xml of the ITSOWebCustomerCredit application.

You have to define both the security roles and security constraints in web.xml. 

<server description="server1 configuration">
<featureManager>
    <feature>jsp-2.2</feature>
    <feature>jdbc-4.0</feature>
    <feature>jpa-2.0</feature>
</featureManager>

    <jdbcDriver libraryRef="DerbyLib"/>
    
    <library filesetRef="DerbyFileset" id="DerbyLib"/>
    
    <fileset dir="${derbyInstallDir}/lib" includes="derby.jar"/>
    
    <dataSource 
                jdbcDriverRef="DerbyEmbedded"
                jndiName="jdbc/MyDataSource" 
                syncQueryTimeoutWithTransactionTimeout="false"
                type="javax.sql.DataSource">
    
        <properties.derby.embedded createDatabase="create" 
                                   databaseName="CUSTDB1"/>
    </dataSource>
    
    <httpEndpoint host="localhost" 
                  httpPort="${liberty.server1.http.port}"
                  httpsPort="${liberty.server1.https.port}" 
                  id="defaultHttpEndpoint"/>
    
    <include location="security.xml" />
    
    <logging traceSpecification="*=audit=enabled:com.ibm.itso.*=debug=enabled"/>
    
    </server>

The new server.xml configuration includes the security configuration, which in a production environment can be limited for access to only specific administrators. To access the ITSOWebCustomerCredit application, you are prompted for credentials

When you successfully authenticate to the application, notice that this time the application shows the user name and checks the user roles.

The authentication and authorization information provided by the application When the application was not secured, the authenticated user was displayed as null, and after securing the application the authenticated user is user2. We can inspect the configuration of the basic user registry defined in the security.xml file to see how the authorization and roles were mapped. Although this example used the basic user registry, we can achieve the same result if you were to configure the Liberty profile server with a real LDAP user registry.


Encoding the passwords

Providing plain text passwords in the security.xml file is not a good practice, especially on production environments. The listing shows a sample configuration where the user passwords are kept in clear text; however, the password for the keystore is encoded. This is because Liberty profile securityUtility was used to encode this password during the certificate generation.

We can use this script any time to encode passwords. To use it, simply run this command providing your password:

It will return a similar string:

Now replace the original password with the encoded value, for example:

If we do not want to expose your password, we can also use the interactive mode of the securityUtility, which prompts you to provide a password but does not show it in clear text.

To use this mode...

The Liberty profile configuration file accepts passwords in both encoded and clear formats.


Generate the Web server plug-in

The simplest way to generate the plug-in for the web server is using the WebSphere Developer Tools. First, add the following line to your server.xml configuration, providing the ports of your HTTP server.

Remember that if you configured the virtual hosts of the Liberty profile to a specific target, the HTTP servers have to use that host to communicate with the Liberty profile server. To allow all traffic to the Liberty profile server, use the following syntax: 

<httpEndpoint host="*" 
              httpPort="9080" 
              httpsPort="9443" 
              id="defaultHttpEndpoint"/>

To generate the plug-in using the WebSphere Developers Tools...

In the pop-up window, click Finish. Your plug-in named plugin-cfg.xml is generated in the Liberty profile server root directory. This file then has to be copied to the machine that hosts the web server (the web server might need to be restarted to lookup the new plug-in configuration). To access the application, use the following URL:

For the IBM HTTP Server, typically we have to enable the plug-in in the httpd.conf configuration. For example, on Windows environments, this configuration looks like:


Administering using the ND job manager console

The Liberty profile can be administered remotely using the job manager console available with the WAS ND offering. We can use the job manager console to start, stop, or change the configuration files of the Liberty profile.