Installing Persistent Mobile Foundation Server to an application server

You must configure a secure JMX connection for Apache Tomcat application server.

The Ant tasks can configure a default secure JMX connection, which includes the definition of a JMX remote port, and the definition of authentication properties. They modify tomcat_install_dir/bin/setenv.bat and tomcat_install_dir/bin/setenv.sh to add these options to CATALINA_OPTS:

-Djava.rmi.server.hostname=localhost
-Dcom.sun.management.jmxremote.port=8686
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false

Note: 8686 is a default value. The value for this port can be changed if the port is not available on the computer.

• The setenv.bat file is used if you start Apache Tomcat with tomcat_install_dir/bin/startup.bat, or tomcat_install_dir/bin/catalina.bat.
• The setenv.sh file is used if you start Apache Tomcat with tomcatInstallDir/bin/startup.sh, or tomcat_install_dir/bin/catalina.sh.

This file might not be used if you start Apache Tomcat with another command. If you installed the Apache Tomcat Windows Service Installer, the service launcher does not use setenv.bat.

Important: This configuration is not secure by default. To secure the configuration, you must manually complete steps 2 and 3 of the following procedure.

Manually configuring Apache Tomcat:

1. For a simple configuration, add the following options to CATALINA_OPTS:

   -Djava.rmi.server.hostname=localhost
   -Dcom.sun.management.jmxremote.port=8686
   -Dcom.sun.management.jmxremote.authenticate=false
   -Dcom.sun.management.jmxremote.ssl=false

2. To activate authentication, see the Apache Tomcat user documentation SSL Support - BIO and NIO and SSL Configuration HOW-TO.
3. For a JMX configuration with SSL enabled, add the following options:

   -Dcom.sun.management.jmxremote=true
   -Dcom.sun.management.jmxremote.port=8686
   -Dcom.sun.management.jmxremote.ssl=true
   -Dcom.sun.management.jmxremote.authenticate=false
   -Djava.rmi.server.hostname=localhost  
   -Djavax.net.ssl.trustStore=<key store location>
   -Djavax.net.ssl.trustStorePassword=<key store password>
   -Djavax.net.ssl.trustStoreType=<key store type>
   -Djavax.net.ssl.keyStore=<key store location>
   -Djavax.net.ssl.keyStorePassword=<key store password>
   -Djavax.net.ssl.keyStoreType=<key store type>

   Note: The port 8686 can be changed.

4. If the Tomcat instance is running behind a firewall, the JMX Remote Lifecycle Listener must be configured. See the Apache Tomcat documentation for JMX Remote Lifecycle Listener.

   The following environment properties must also be added to the Context section of the administration service application in the server.xml file, such as in the following example:

   <Context docBase="mfpadmin" path="/mfpadmin ">
       <Environment name="mfp.admin.rmi.registryPort" value="registryPort" type="java.lang.String" override="false"/>
       <Environment name="mfp.admin.rmi.serverPort" value="serverPort" type="java.lang.String" override="false"/>
   </Context>

   In the previous example:
   • registryPort must have the same value as the rmiRegistryPortPlatform attribute of the JMX Remote Lifecycle Listener.
   • serverPort must have the same value as the rmiServerPortPlatform attribute of the JMX Remote Lifecycle Listener.
5. If you installed Apache Tomcat with the Apache Tomcat Windows Service Installer instead of adding the options to CATALINA_OPTS, run tomcat_install_dir/bin/Tomcat7w.exe, and add the options in the Java tab of the Properties window.

PMF requires the secure JMX connection to be configured.

• The Ant tasks can configure a default secure JMX connection, which includes the generation of a self-signed SSL certificate with a validity period of 365 days. This configuration is not intended for production use.
• To configure the secure JMX connection for production use, follow the instructions as described in Configuring secure JMX connection to the Liberty profile.
• The rest-connector is available for WebSphere Application Server, Liberty Core, and other editions of Liberty, but it is possible to package a Liberty server with a subset of the available features. To verify that the rest-connector feature is available in your installation of Liberty, enter the following command:

                      
  liberty_install_dir/bin/productInfo featureInfo

  Note: Verify that the output of this command contains restConnector-1.0.

PMF requires the secure JMX connection to be configured.

• PMF requires access to the SOAP port, or the RMI port to perform JMX operations. By default, the SOAP port is active on a WebSphere Application Server. PMF uses the SOAP port by default. If both the SOAP and RMI ports are deactivated, PMF does not run.
• RMI is only supported by WebSphere Application Server Network Deployment. RMI is not supported by a stand-alone profile, or a WebSphere Application Server server farm.
• You must activate Administrative and Application Security.

The administration service is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file. The administration service WAR file is in pmf_install_dir/MobileFoundationServer/mfp-admin-service.war. You can define the context root as you want. However, usually it is /mfpadmin.

Mandatory JNDI properties

When you define the JNDI properties, the JNDI names must be prefixed with the context root of the administration service. The following example illustrates the case to declare mfp.admin.push.url whereby the administration service is installed with /mfpadmin as the context root:

<jndiEntry jndiName="mfpadmin/mfp.admin.push.url" value="http://localhost:9080/imfpush"/>

If the push service is installed, you must configure the following JNDI properties:

• mfp.admin.push.url
• mfp.admin.authorization.server.url
• mfp.push.authorization.client.id
• mfp.push.authorization.client.secret
• mfp.admin.authorization.client.id
• mfp.admin.authorization.client.secret

The JNDI properties for the communication with the configuration service are as follows:

• mfp.config.service.user
• mfp.config.service.password

For more information about the JNDI properties, see List of JNDI properties for PMF administration service.

Data source

The JNDI name of the data source for the administration service must be defined as jndiName=the-contextRoot/jdbc/mfpAdminDS. The following example illustrates the case whereby the administration service is installed with the context root /mfpadmin, and that the service is using a relational database:

<dataSource jndiName="mfpadmin/jdbc/mfpAdminDS" transactional="false">
  [...]
</dataSource>

Declare the following roles in the application-bnd element of the application:

• mfpadmin
• mfpdeployer
• mfpmonitor
• mfpoperator

The live update service is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file. Before you proceed, review Manual installation on WebSphere Application Server Liberty for the configuration details that are common to all services.

The live update service WAR file is in pmf_install_dir/MobileFoundationServer/mfp-live-update.war. The context root of the live update service must define in this way: /the-adminContextRootconfig. For example, if the context root of the administration service is /mfpadmin, then the context root of the live update service must be /mfpadminconfig.

Data source

The JNDI name of the data source for the live update service must be defined as the-contextRoot/jdbc/ConfigDS. The following example illustrates the case whereby the live update service is installed with the context root /mfpadminconfig, and that the service is using a relational database:

<dataSource jndiName="mfpadminconfig/jdbc/ConfigDS" transactional="false">
  [...]
</dataSource>

Declare the configadmin role in the application-bnd element of the application. At least one user must be mapped to this role. The user and its password must be provided to the following JNDI properties of the administration service:

• mfp.config.service.user
• mfp.config.service.password

The console is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file. Before you proceed, review Manual installation on WebSphere Application Server Liberty for the configuration details that are common to all services.

The console WAR file is in pmf_install_dir/MobileFoundationServer/mfp-admin-ui.war. You can define the context root as you want. However, usually it is /mfpconsole.

Mandatory JNDI properties

When you define the JNDI properties, the JNDI names must be prefixed with the context root of the console. The following example illustrates the case to declare mfp.admin.endpoint whereby the console is installed with /mfpconsole as the context root:

<jndiEntry jndiName="mfpconsole/mfp.admin.endpoint" value="*://*:*/mfpadmin"/>

The typical value for the mfp.admin.endpoint property is *://*:*/the-adminContextRoot.
For more information about the JNDI properties, see JNDI properties for PMF Operations Console.

Security roles

Declare the following roles in the application-bnd element of the application:

• mfpadmin
• mfpdeployer
• mfpmonitor
• mfpoperator

The runtime is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file. Before you proceed, review Manual installation on WebSphere Application Server Liberty for the configuration details that are common to all services.

The runtime WAR file is in pmf_install_dir/MobileFoundationServer/mfp-server.war. You can define the context root as you want. However, it is /mfp by default.

Mandatory JNDI properties

When you define the JNDI properties, the JNDI names must be prefixed with the context root of the runtime. The following example illustrates the case to declare mfp.analytics.url whereby the runtime is installed with /mobilefirst as the context root:

<jndiEntry jndiName="mobilefirst/mfp.analytics.url" value="http://localhost:9080/analytics-service/rest"/>

You must define the mobilefirst/mfp.authorization.server property. For example:

<jndiEntry jndiName="mobilefirst/mfp.authorization.server" value="embedded"/>

If Persistent Mobile Foundation Analytics is installed, you need to define the following JNDI properties:

• mfp.analytics.url
• mfp.analytics.console.url
• mfp.analytics.username
• mfp.analytics.password

For more information about the JNDI properties, see List of JNDI properties for PMF runtime.

Data source

The JNDI name of the data source for the runtime must be defined as jndiName=the-contextRoot/jdbc/mfpDS. The following example illustrates the case whereby the runtime is installed with the context root /mobilefirst, and that the runtime is using a relational database:

<dataSource jndiName="mobilefirst/jdbc/mfpDS" transactional="false">
  [...]
</dataSource>

The push service is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file. Before you proceed, review Manual installation on WebSphere Application Server Liberty for the configuration details that are common to all services.

The push service WAR file is in pmf_install_dir/PushService/mfp-push-service.war. You must define the context root as /imfpush. Otherwise, the client devices cannot connect to it as the context root is hardcoded in the SDK.

Mandatory JNDI properties

When you define the JNDI properties, the JNDI names must be prefixed with the context root of the push service. The following example illustrates the case to declare mfp.push.analytics.user whereby the push service is installed with /imfpush as the context root:

<jndiEntry jndiName="imfpush/mfp.push.analytics.user" value="admin"/>

• mfp.push.authorization.server.url
• mfp.push.authorization.client.id
• mfp.push.authorization.client.secret
• mfp.push.services.ext.security - the value must be com.ibm.mfp.push.server.security.plugin.OAuthSecurityPlugin.
• mfp.push.db.type - for a relational database, the value must be DB.

• mfp.push.analytics.endpoint
• mfp.analytics.username
• mfp.analytics.password
• mfp.push.services.ext.analytics - the value must be com.ibm.mfp.push.server.analytics.plugin.AnalyticsPlugin.

The artifacts component is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file. Before you proceed, review Manual installation on WebSphere Application Server Liberty for the configuration details that are common to all services.

The WAR file for this component is in pmf_install_dir/MobileFoundationServer/mfp-dev-artifacts.war. You must define the context root as /mfp-dev-artifacts.

The administration service is packaged as a WAR application for you to deploy to the Liberty collective controller. You need to make some specific configurations for this application in the server.xml file of the Liberty collective controller.

Before you proceed, review Manual installation on WebSphere Application Server Liberty collective for the configuration details that are common to all services.

The administration service WAR file is in pmf_install_dir/MobileFoundationServer/mfp-admin-service-collective.war. You can define the context root as you want. However, usually it is /mfpadmin.

Mandatory JNDI properties

When you define the JNDI properties, the JNDI names must be prefixed with the context root of the administration service. The following example illustrates the case to declare mfp.admin.push.url whereby the administration service is installed with /mfpadmin as the context root:

<jndiEntry jndiName="mfpadmin/mfp.admin.push.url" value="http://localhost:9080/imfpush"/>

If the push service is installed, you must configure the following JNDI properties:

• mfp.admin.push.url
• mfp.admin.authorization.server.url
• mfp.push.authorization.client.id
• mfp.push.authorization.client.secret
• mfp.admin.authorization.client.id
• mfp.admin.authorization.client.secret

The JNDI properties for the communication with the configuration service are as follows:

• mfp.config.service.user
• mfp.config.service.password

For more information about the JNDI properties, see List of JNDI properties for PMF administration service.

Data source

The JNDI name of the data source for the administration service must be defined as jndiName=the-contextRoot/jdbc/mfpAdminDS. The following example illustrates the case whereby the administration service is installed with the context root /mfpadmin, and that the service is using a relational database:

<dataSource jndiName="mfpadmin/jdbc/mfpAdminDS" transactional="false">
  [...]
</dataSource>

Security roles

Declare the following roles in the application-bnd element of the application:

• mfpadmin
• mfpdeployer
• mfpmonitor
• mfpoperator

The live update service is packaged as a WAR application for you to deploy to the liberty collective controller. You need to make some specific configurations for this application in the server.xml file of the Liberety collective controller.

Before you proceed, review Manual installation on WebSphere Application Server Liberty collective for the configuration details that are common to all services.

The live update service WAR file is in pmf_install_dir/MobileFoundationServer/mfp-live-update.war. The context root of the live update service must define in this way: /the-adminContextRootconfig. For example, if the context root of the administration service is /mfpadmin, then the context root of the live update service must be /mfpadminconfig.

Data source

The JNDI name of the data source for the live update service must be defined as the-contextRoot/jdbc/ConfigDS. The following example illustrates the case whereby the live update service is installed with the context root /mfpadminconfig, and that the service is using a relational database:

<dataSource jndiName="mfpadminconfig/jdbc/ConfigDS" transactional="false">
  [...]
</dataSource>

Security roles

Declare the configadmin role in the application-bnd element of the application. At least one user must be mapped to this role. The user and its password must be provided to the following JNDI properties of the administration service:

• mfp.config.service.user
• mfp.config.service.password

The console is packaged as a WAR application for you to deploy to the Liberty collective controller. You need to make some specific configurations for this application in the server.xml file of the Liberty collective controller.

Before you proceed, review Manual installation on WebSphere Application Server Liberty for the configuration details that are common to all services.

The console WAR file is in pmf_install_dir/MobileFoundationServer/mfp-admin-ui.war. You can define the context root as you want. However, usually it is /mfpconsole.

Mandatory JNDI properties

When you define the JNDI properties, the JNDI names must be prefixed with the context root of the console. The following example illustrates the case to declare mfp.admin.endpoint whereby the console is installed with /mfpconsole as the context root:

<jndiEntry jndiName="mfpconsole/mfp.admin.endpoint" value="*://*:*/mfpadmin"/>

The typical value for the mfp.admin.endpoint property is *://*:*/the-adminContextRoot.
For more information about the JNDI properties, see JNDI properties for PMF Operations Console.

Security roles

Declare the following roles in the application-bnd element of the application:

• mfpadmin
• mfpdeployer
• mfpmonitor
• mfpoperator

The runtime is packaged as a WAR application for you to deploy to the Liberty collective cluster members. You need to make some specific configurations for this application in the server.xml file of every Liberty collective cluster member.

Before you proceed, review Manual installation on WebSphere Application Server Liberty collective for the configuration details that are common to all services.

The runtime WAR file is in pmf_install_dir/MobileFoundationServer/mfp-server.war. You can define the context root as you want. However, it is /mfp by default.

Mandatory JNDI properties

When you define the JNDI properties, the JNDI names must be prefixed with the context root of the runtime. The following example illustrates the case to declare mfp.analytics.url whereby the runtime is installed with /mobilefirst as the context root:

<jndiEntry jndiName="mobilefirst/mfp.analytics.url" value="http://localhost:9080/analytics-service/rest"/>

You must define the mobilefirst/mfp.authorization.server property. For example:

<jndiEntry jndiName="mobilefirst/mfp.authorization.server" value="embedded"/>

If Persistent Mobile Foundation Analytics is installed, you need to define the following JNDI properties:

• mfp.analytics.url
• mfp.analytics.console.url
• mfp.analytics.username
• mfp.analytics.password

For more information about the JNDI properties, see List of JNDI properties for PMF runtime.

Data source

The JNDI name of the data source for the runtime must be defined as jndiName=the-contextRoot/jdbc/mfpDS. The following example illustrates the case whereby the runtime is installed with the context root /mobilefirst, and that the runtime is using a relational database:

<dataSource jndiName="mobilefirst/jdbc/mfpDS" transactional="false">
  [...]
</dataSource>

The push service is packaged as a WAR application for you to deploy to a Liberty collective cluster member or to a Liberty server. If you install the push service in a Liberty server, see PMF push service configuration details under Manual installation on WebSphere Application Server Liberty.

When the PMF push service is installed in a Liberty collective, it can be installed in the same cluster than the runtime or in another cluster.

You need to make some specific configurations for this application in the server.xml file of every Liberty collective cluster member. Before you proceed, review Manual installation on WebSphere Application Server Liberty collective for the configuration details that are common to all services.

The push service WAR file is in pmf_install_dir/PushService/mfp-push-service.war. You must define the context root as /imfpush. Otherwise, the client devices cannot connect to it as the context root is hardcoded in the SDK.

Mandatory JNDI properties

When you define the JNDI properties, the JNDI names must be prefixed with the context root of the push service. The following example illustrates the case to declare mfp.push.analytics.user whereby the push service is installed with /imfpush as the context root:

<jndiEntry jndiName="imfpush/mfp.push.analytics.user" value="admin"/>

• mfp.push.authorization.server.url
• mfp.push.authorization.client.id
• mfp.push.authorization.client.secret
• mfp.push.services.ext.security - the value must be com.ibm.mfp.push.server.security.plugin.OAuthSecurityPlugin.
• mfp.push.db.type - for a relational database, the value must be DB.

• mfp.push.analytics.endpoint
• mfp.analytics.username
• mfp.analytics.password
• mfp.push.services.ext.analytics - the value must be com.ibm.mfp.push.server.analytics.plugin.AnalyticsPlugin.

The artifacts component is packaged as a WAR application for you to deploy to the Liberty collective controller. You need to make some specific configurations for this application in the server.xml file of the Liberty collective controller. Before you proceed, review Manual installation on WebSphere Application Server Liberty for the configuration details that are common to all services.

The WAR file for this component is in pmf_install_dir/MobileFoundationServer/mfp-dev-artifacts.war. You must define the context root as /mfp-dev-artifacts.

The administration service is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file of the application server.

Before you proceed, review Manual installation on Apache Tomcat for the configuration details that are common to all services.

The administration service WAR file is in pmf_install_dir/MobileFoundationServer/mfp-admin-service.war. You can define the context root as you want. However, usually it is /mfpadmin.

Mandatory JNDI properties

The JNDI properties are defined within the Environment element in the application context. For example:

<Environment name="mfp.admin.push.url" value="http://localhost:8080/imfpush" type="java.lang.String" override="false"/>

To enable the JMX communication with the runtime, define the following JNDI properties:

• mfp.topology.platform
• mfp.topology.clustermode

If the push service is installed, you must configure the following JNDI properties:

• mfp.admin.push.url
• mfp.admin.authorization.server.url
• mfp.push.authorization.client.id
• mfp.push.authorization.client.secret
• mfp.admin.authorization.client.id
• mfp.admin.authorization.client.secret

The JNDI properties for the communication with the configuration service are as follows:

• mfp.config.service.user
• mfp.config.service.password

For more information about the JNDI properties, see List of JNDI properties for PMF administration service.

Data source

The data source (jdbc/mfpAdminDS) is declared as a resource in the **Context** element. For example:

<Resource name="jdbc/mfpAdminDS" type="javax.sql.DataSource" .../>

Security roles

The security roles available for the administration service application are:

• mfpadmin
• mfpdeployer
• mfpmonitor
• mfpoperator

The live update service is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file.

Before you proceed, review Manual installation on Apache Tomcat for the configuration details that are common to all services.

The live update service WAR file is in pmf_install_dir/MobileFoundationServer/mfp-live-update.war. The context root of the live update service must define in this way: /the-adminContextRoot/config. For example, if the context root of the administration service is /mfpadmin, then the context root of the live update service must be /mfpadminconfig.

Data source

The JNDI name of the data source for the live update service must be defined as jdbc/ConfigDS. Declare it as a resource in the Context element.

Security roles

The security role available for the live update service application is configadmin.

At least one user must be mapped to this role. The user and its password must be provided to the following JNDI properties of the administration service:

• mfp.config.service.user
• mfp.config.service.password

The console is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file of the application server.

Before you proceed, review Manual installation on Apache Tomcat for the configuration details that are common to all services.

The console WAR file is in pmf_install_dir/MobileFoundationServer/mfp-admin-ui.war. You can define the context root as you want. However, usually it is /mfpconsole.

Mandatory JNDI properties

You need to define the mfp.admin.endpoint property. The typical value for this property is *://*:*/the-adminContextRoot.

For more information about the JNDI properties, see JNDI properties for PMF Operations Console.

Security roles

The security roles available for the application are:

• mfpadmin
• mfpdeployer
• mfpmonitor
• mfpoperator

The runtime is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file.

Before you proceed, review Manual installation on Apache Tomcat for the configuration details that are common to all services.

The runtime WAR file is in pmf_install_dir/MobileFoundationServer/mfp-server.war. You can define the context root as you want. However, it is /mfp by default.

Mandatory JNDI properties

You must define the mfp.authorization.server property. For example:

<Environment name="mfp.authorization.server" value="embedded" type="java.lang.String" override="false"/>

To enable the JMX communication with the administration service, define the following JNDI properties:

• mfp.topology.platform
• mfp.topology.clustermode

If Persistent Mobile Foundation Analytics is installed, you need to define the following JNDI properties:

• mfp.analytics.url
• mfp.analytics.console.url
• mfp.analytics.username
• mfp.analytics.password

For more information about the JNDI properties, see List of JNDI properties for PMF runtime.

Data source

The JNDI name of the data source for the runtime must be defined as jdbc/mfpDS. Declare it as a resource in the Context element.

The push service is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application. Before you proceed, review Manual installation on Apache Tomcat for the configuration details that are common to all services.

The push service WAR file is in pmf_install_dir/PushService/mfp-push-service.war. You must define the context root as /imfpush. Otherwise, the client devices cannot connect to it as the context root is hardcoded in the SDK.

Mandatory JNDI properties

You need to define the following properties:

• mfp.push.authorization.server.url
• mfp.push.authorization.client.id
• mfp.push.authorization.client.secret
• mfp.push.services.ext.security - the value must be com.ibm.mfp.push.server.security.plugin.OAuthSecurityPlugin.
• mfp.push.db.type - for a relational database, the value must be DB.

If Persistent Mobile Foundation Analytics is configured, define the following JNDI properties:

• mfp.push.analytics.endpoint
• mfp.analytics.username
• mfp.analytics.password
• mfp.push.services.ext.analytics - the value must be com.ibm.mfp.push.server.analytics.plugin.AnalyticsPlugin.

The artifacts component is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file of the application server. Before you proceed, review Manual installation on Apache Tomcat for the configuration details that are common to all services.

The WAR file for this component is in pmf_install_dir/MobileFoundationServer/mfp-dev-artifacts.war. You must define the context root as /mfp-dev-artifacts.

The administration service is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file of the application server.

Before you proceed, review Manual installation on WebSphere Application Server and WebSphere Application Server Network Deployment for the configuration details that are common to all services.

The administration service WAR file is in pmf_install_dir/MobileFoundationServer/mfp-admin-service.war. You can define the context root as you want. However, usually it is /mfpadmin.

Mandatory JNDI properties

You can set JNDI properties with the WebSphere Application Server administration console. Go to Applications → Application Types → WebSphere enterprise applications → application_name → Environment entries for Web modules and set the entries.

To enable the JMX communication with the runtime, define the following JNDI properties:

• mfp.admin.jmx.dmgr.host
• mfp.admin.jmx.dmgr.port - the SOAP port on the deployment manager.
• mfp.topology.platform - set the value as WAS.
• mfp.topology.clustermode - set the value as Cluster.
• mfp.admin.jmx.connector - set the value as SOAP.

• mfp.topology.platform - set the value as WAS.
• mfp.topology.clustermode - set the value as Standalone.
• mfp.admin.jmx.connector - set the value as SOAP.

If the push service is installed, you must configure the following JNDI properties:

• mfp.admin.push.url
• mfp.admin.authorization.server.url
• mfp.push.authorization.client.id
• mfp.push.authorization.client.secret
• mfp.admin.authorization.client.id
• mfp.admin.authorization.client.secret

The JNDI properties for the communication with the configuration service are as follows:

• mfp.config.service.user
• mfp.config.service.password

For more information about the JNDI properties, see List of JNDI properties for PMF administration service.

Data source

Create a data source for the administration service and map it to jdbc/mfpAdminDS.

Start order

The administration service application must start before the runtime application. You can set the order at Startup behavior section. For example, set the Startup Order to 1 for the administration service and 2 to the runtime.

Security roles

The security roles available for the administration service application are:

• mfpadmin
• mfpdeployer
• mfpmonitor
• mfpoperator

The live update service is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file.

Before you proceed, review Manual installation on WebSphere Application Server and WebSphere Application Server Network Deployment for the configuration details that are common to all services.

The live update service WAR file is in pmf_install_dir/MobileFoundationServer/mfp-live-update.war. The context root of the live update service must define in this way: /the-adminContextRoot/config. For example, if the context root of the administration service is /mfpadmin, then the context root of the live update service must be /mfpadminconfig.

Data source

Create a data source for the live update service and map it to jdbc/ConfigDS.

Security roles

The configadmin role is defined for this application.

At least one user must be mapped to this role. The user and its password must be provided to the following JNDI properties of the administration service:

• mfp.config.service.user
• mfp.config.service.password

The console is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file of the application server.

Before you proceed, review Manual installation on WebSphere Application Server and WebSphere Application Server Network Deployment for the configuration details that are common to all services.

The console WAR file is in pmf_install_dir/MobileFoundationServer/mfp-admin-ui.war. You can define the context root as you want. However, usually it is /mfpconsole.

Mandatory JNDI properties

You can set JNDI properties with the WebSphere Application Server administration console. Go to Applications → Application Types → WebSphere enterprise applications → application_name → Environment entries for Web modules and set the entries.

You need to define the mfp.admin.endpoint property. The typical value for this property is *://*:*/the-adminContextRoot.

For more information about the JNDI properties, see JNDI properties for PMF Operations Console.

Security roles

The security roles available for the application are:

• mfpadmin
• mfpdeployer
• mfpmonitor
• mfpoperator

The runtime is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file.

Before you proceed, review Manual installation on WebSphere Application Server and WebSphere Application Server Network Deployment for the configuration details that are common to all services.

The runtime WAR file is in pmf_install_dir/MobileFoundationServer/mfp-server.war. You can define the context root as you want. However, it is /mfp by default.

Mandatory JNDI properties

You can set JNDI properties with the WebSphere Application Server administration console. Go to Applications → Application Types → WebSphere enterprise applications → application_name → Environment entries for Web modules and set the entries.

You must define the mfp.authorization.server property with the value as embedded.
Also, define the following JNDI properties to enable the JMX communication with the administration service:

• mfp.admin.jmx.dmgr.host - the host name of the deployment manager.
• mfp.admin.jmx.dmgr.port - the SOAP port of the deployment manager.
• mfp.topology.platform - set the value as WAS.
• mfp.topology.clustermode - set the value as Cluster.
• mfp.admin.jmx.connector - set the value as SOAP.

• mfp.topology.platform - set the value as WAS.
• mfp.topology.clustermode - set the value as Standalone.
• mfp.admin.jmx.connector - set the value as SOAP.

If Persistent Mobile Foundation Analytics is installed, you need to define the following JNDI properties:

• mfp.analytics.url
• mfp.analytics.console.url
• mfp.analytics.username
• mfp.analytics.password

For more information about the JNDI properties, see List of JNDI properties for PMF runtime.

Start order

The runtime application must start after the administration service application. You can set the order at Startup behavior section. For example, set the Startup Order to 1 for the administration service and 2 to the runtime.

Data source

Create a data source for the runtime and map it to jdbc/mfpDS.

The push service is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application. Before you proceed, review Manual installation on WebSphere Application Server and WebSphere Application Server Network Deployment for the configuration details that are common to all services.

The push service WAR file is in pmf_install_dir/PushService/mfp-push-service.war. You must define the context root as /imfpush. Otherwise, the client devices cannot connect to it as the context root is hardcoded in the SDK.

Mandatory JNDI properties

You can set JNDI properties with the WebSphere Application Server administration console. Go to Applications > Application Types → WebSphere enterprise applications → application_name → Environment entries for Web modules and set the entries.

You need to define the following properties:

• mfp.push.authorization.server.url
• mfp.push.authorization.client.id
• mfp.push.authorization.client.secret
• mfp.push.services.ext.security - the value must be com.ibm.mfp.push.server.security.plugin.OAuthSecurityPlugin.
• mfp.push.db.type - for a relational database, the value must be DB.

If Persistent Mobile Foundation Analytics is configured, define the following JNDI properties:

• mfp.push.analytics.endpoint
• mfp.analytics.username
• mfp.analytics.password
• mfp.push.services.ext.analytics - the value must be com.ibm.mfp.push.server.analytics.plugin.AnalyticsPlugin.

For more information about the JNDI properties, see List of JNDI properties for PMF push service.

Data source

Create the data source for the push service and map it to jdbc/imfPushDS.

The artifacts component is packaged as a WAR application for you to deploy to the application server. You need to make some specific configurations for this application in the server.xml file of the application server. Before you proceed, review Manual installation on WebSphere Application Server and WebSphere Application Server Network Deployment for the configuration details that are common to all services.

The WAR file for this component is in pmf_install_dir/MobileFoundationServer/mfp-dev-artifacts.war. You must define the context root as /mfp-dev-artifacts.

PMF requires the secure JMX connection to be configured.

1. Prepare the application servers that must be configured as the server farm members.
   • Choose the type of application server to use to configure the members of the server farm. PMF supports the following application servers in server farms:
     • WebSphere Application Server full profile. Note: In a farm topology, you cannot use the RMI JMX connector. In this topology, only the SOAP connector is supported by PMF.
     • WebSphere Application Server Liberty profile
     • Apache Tomcat
     To know which versions of the application servers are supported, see System requirements.

     Important: PMF supports only homogeneous server farms. A server farm is homogeneous when it connects same type of application servers. Attempting to associate different types of application servers might lead to unpredictable behavior at run time. For example, a farm with a mix of Apache Tomcat servers and WebSphere Application Server full profile servers is an invalid configuration.

   • Set up as many stand-alone servers as the number of members that you want in the farm.
     
     Each of these stand-alone servers must communicate with the same database. You must make sure that any port used by any of these servers is not also used by another server that is configured on the same host. This constraint applies to the ports used by HTTP, HTTPS, REST, SOAP, and RMI protocols.
     
     Each of these servers must have the PMF administration service, the PMF live update service, and one or more PMF runtimes deployed on it.
     
     For more information about setting up a server, see Constraints on PMF administration service, PMF live update service and PMF runtime.
   • Exchange the signer certificates between all the servers in their respective truststores.
     
     

     Note: This step is mandatory for the farms that use WebSphere Application Server full profile or Liberty as security must be enabled. In addition, for Liberty farms, the same LTPA configuration must be replicated on each server to ensure single-sign on capability. To do this configuration, follow the guidelines in step 6 of Configuring a server farm manually

     .
2. Configure the database for the administration service, the live update service, and the runtime.
   • Decide which database that you want to use and choose the Ant file to create and configure the database in the pmf_install_dir/MobileFoundationServer/configuration-samples directory:
     • For DB2 , use create-database-db2.xml.
     • For MySQL, use create-database-mysql.xml.
     • For Oracle, use create-database-oracle.xml.

     Note: Do not use the Derby database in a farm topology because the Derby database allows only a single connection at a time.

   • Edit the Ant file and enter all the required properties for the database.
     
     To enable the configuration of the database that is used by the PMF components, set the values of the following properties:
     • Set mfp.process.admin to true. To configure the database for the administration service and the live update service.
     • Set mfp.process.runtime to true. To configure the database for the runtime.
   • Run the following commands from the pmf_install_dir/MobileFoundationServer/configuration-samples directory where create-database-ant-file.xml must be replaced with the actual Ant file name that you chose: pmf_install_dir/tools/apache-ant-1.9.4/bin/ant -f create-database-ant-file.xml admdatabases and pmf_install_dir/tools/apache-ant-1.9.4/bin/ant -f create-database-ant-file.xml rtmdatabases.
     
     As the PMF databases are shared between the application servers in a farm, these two commands must be run only once, whatever the number of servers in the farm.
   • Optionally, if you want to install another runtime, you must configure another database with another database name or schema. To do so, edit the Ant file, modify the properties, and run the following command once, whatever the number of servers in the farm: pmf_install_dir/tools/apache-ant-1.9.4/bin/ant -f create-database-ant-file.xml rtmdatabases.
3. Deploy the administration service, the live update service, and the runtime on the servers and configure these servers as the members of a server farm.
   • Choose the Ant file that corresponds to your application server and your database in the pmf_install_dir/MobileFoundationServer/configuration-samples directory to deploy the administration service, the live update service, and the runtime on the servers.
     
     For example, choose the configure-liberty-db2.xml file for a deployment on Liberty server with the DB2 database. Make as many copies of this file as the number of members that you want in the farm.
     
     Note: Keep these files after the configuration as they can be reused for upgrading the PMF components that are already deployed, or for uninstalling them from each member of the farm.
   • Edit each copy of the Ant file, enter the same properties for the database that are used at step 2, and also enter the other required properties for the application server.
     
     To configure the server as a server farm member, set the values of the following properties:
     • Set mfp.farm.configure to true.
     • mfp.farm.server.id: An identifier that you define for this farm member. Make sure that each server in the farm has its own unique identifier. If two servers in the farm have the same identifier, the farm might behave in an unpredictable way.
     • mfp.config.service.user: The user name that is used to access the live update service. The user name must be the same for all the members of the farm.
     • mfp.config.service.password: The password that is used to access the live update service. The password must be the same for all the members of the farm.
     To enable the deployment of the WAR files of the PMF components on the server, set the values of the following properties:
     • Set mfp.process.admin to true. To deploy the WAR files of the administration service and the live update service.
     • Set mfp.process.runtime to true. To deploy the WAR file of the runtime.
     
     Note: If you plan to install more than one runtime on the servers of the farm, specify the attribute id and set a value that must be unique for each runtime on the installpmfruntime, updatepmfruntime, and uninstallpmfruntime Ant tasks.
     For example,

     <target name="rtminstall">
         <installpmfruntime execute="true" contextroot="/runtime1" id="rtm1">

   • For each server, run the following commands where configure-appserver-database-ant-file.xml must be replaced with the actual Ant file name that you chose: pmf_install_dir/tools/apache-ant-1.9.4/bin/ant -f configure-appserver-database-ant-file.xml adminstall and pmf_install_dir/tools/apache-ant-1.9.4/bin/ant -f configure-appserver-database-ant-file.xml rtminstall.
     
     These commands run the installpmfadmin and installpmfruntime Ant tasks. For more information about these tasks, see Ant tasks for installation of PMF Operations Console, PMF artifacts, PMF administration, and live update services and Ant tasks for installation of PMF runtime environments.
   • Optionally, if you want to install another runtime, do the following steps:
     • Make a copy of the Ant file that you configured at step 3.b.
     • Edit the copy, set a distinct context root, and a value for the attribute id of installpmfruntime, updatepmfruntime, and uninstallpmfruntime that is different from the other runtime configuration.
     • Run the following command on each server on the farm where configure-appserver-database-ant-file2.xml must be replaced with the actual name of the Ant file that is edited: pmf_install_dir/tools/apache-ant-1.9.4/bin/ant -f configure-appserver-database-ant-file2.xml rtminstall.
     • Repeat this step for each server of the farm.
4. Restart all the servers.

1. Choose the type of application server to use to configure the members of the server farm. PMF supports the following application servers in server farms:
   • WebSphere Application Server full profile
     Note: In a farm topology, you cannot use the RMI JMX connector. In this topology, only the SOAP connector is supported by PMF.
   • WebSphere Application Server Liberty profile
   • Apache Tomcat
   To know which versions of the application servers are supported, see System requirements.

   Important: PMF supports only homogeneous server farms. A server farm is homogeneous when it connects same type of application servers. Attempting to associate different types of application servers might lead to unpredictable behavior at run time. For example, a farm with a mix of Apache Tomcat servers and WebSphere Application Server full profile servers is an invalid configuration.

2. Decide which database that you want to use. You can choose from:
   • DB2
   • MySQL
   • Oracle
   PMF databases are shared between the application servers in a farm, which means:
   • You create the database only once, whatever the number of servers in the farm.
   • You cannot use the Derby database in a farm topology because the Derby database allows only a single connection at a time.
   For more information about databases, see Setting up databases.
3. Set up as many stand-alone servers as the number of members that you want in the farm.
   • Each of these stand-alone servers must communicate with the same database. You must make sure that any port used by any of these servers is not also used by another server that is configured on the same host. This constraint applies to the ports used by HTTP, HTTPS, REST, SOAP, and RMI protocols.
   • Each of these servers must have the PMF administration service, the PMF live update service, and one or more PMF runtimes deployed on it.
   • When each of these servers is working properly in a stand-alone topology, you can transform them into members of a server farm.
4. Stop all the servers that are intended to become members of the farm.
5. Configure each server appropriately for the type of application server.
   You must set some JNDI properties correctly. In a server farm topology, the mfp.config.service.user and mfp.config.service.password JNDI properties must have the same value for all the members of the farm. For Apache Tomcat, you must also check that the JVM arguments are properly defined.
   • WebSphere Application Server Liberty profile
     In the server.xml file, set the JNDI properties shown in the following sample code.

     <jndiEntry jndiName="mfp.topology.clustermode" value="Farm"/>
     <jndiEntry jndiName="mfp.admin.serverid" value="farm_member_1"/>
     <jndiEntry jndiName="mfp.admin.jmx.user" value="myRESTConnectorUser"/>
     <jndiEntry jndiName="mfp.admin.jmx.pwd" value="password-of-rest-connector-user"/>
     <jndiEntry jndiName="mfp.admin.jmx.host" value="93.12.0.12"/>
     <jndiEntry jndiName="mfp.admin.jmx.port" value="9443"/>

     These properties must be set with appropriate values:
     • mfp.admin.serverid: The identifier that you defined for this farm member. This identifier must be unique across all farm members.
     • mfp.admin.jmx.user and mfp.admin.jmx.pwd: These values must match the credentials of a user as declared in the administrator-role element.
     • mfp.admin.jmx.host: Set this parameter to the IP or the host name that is used by remote members to access this server. Therefore, do not set it to localhost. This host name is used by the other members of the farm and must be accessible to all farm members.
     • mfp.admin.jmx.port: Set this parameter to the server HTTPS port that is used for the JMX REST connection. You can find the value in the httpEndpoint element of the server.xml file.
   • Apache Tomcat
     Modify the conf/server.xml file to set the following JNDI properties in the administration service context and in every runtime context.

     <Environment name="mfp.topology.clustermode" value="Farm" type="java.lang.String" override="false"/>
     <Environment name="mfp.admin.serverid" value="farm_member_1" type="java.lang.String" override="false"/>

     The mfp.admin.serverid property must be set to the identifier that you defined for this farm member. This identifier must be unique across all farm members.
     You must make sure that the -Djava.rmi.server.hostname JVM argument is set to the IP or the host name that is used by remote members to access this server. Therefore, do not set it to localhost. In addition, you must make sure that the -Dcom.sun.management.jmxremote.port JVM argument is set with a port that is not already in use to enable JMX RMI connections. Both arguments are set in the CATALINA_OPTS environment variable.
   • WebSphere Application Server full profile
     You must declare the following JNDI properties in the administration service and in every runtime application deployed on the server.
     • mfp.topology.clustermode
     • mfp.admin.serverid
     In the WebSphere Application Server console,
     • select Applications → Application Types → WebSphere Enterprise applications.
     • Select the administration service application.
     • In Web Module Properties, click Environment entries for Web Modules to display the JNDI properties.
     • Set the values of the following properties.
       • Set mfp.topology.clustermode to Farm.
       • Set mfp.admin.serverid to the identifier that you chose for this farm member. This identifier must be unique across all farm members.
       • Set mfp.admin.jmx.user to a user name that has access to the SOAP connector.
       • Set mfp.admin.jmx.pwd to the password of the user as declared in mfp.admin.jmx.user.
       • Set mfp.admin.jmx.port to the value of the SOAP port.
     • Verify that mfp.admin.jmx.connector is set to SOAP.
     • Click OK and save the configuration.
     • Make similar changes for every PMF runtime application deployed on the server.
6. Exchange the server certificates in their truststores between all members of the farm. Exchanging the server certificates in their truststores is mandatory for farms that use WebSphere Application Server full profile and WebSphere Application Server Liberty profile because in these farms, communications between the servers is secured by SSL.
   • WebSphere Application Server Liberty profile
     You can configure the truststore by using IBM utilities such as Keytool or iKeyman.
     • For more information about Keytool, see Keytool in the IBM SDK, Java Technology Edition.
     • For more information about iKeyman, see iKeyman in the IBM SDK, Java Technology Edition.
     The locations of keystore and truststore are defined in the server.xml file. See the keyStoreRef and trustStoreRef attributes in SSL configuration attributes. By default, the keystore of Liberty profile is at ${server.config.dir}/resources/security/key.jks. If the truststore reference is missing or not defined in the server.xml file, the keystore that is specified by keyStoreRef is used. The server uses the default keystore and the file is created the first time that the server runs. In that case, a default certificate is created with a validity period of 365 days. For production, you might consider using your own certificate (including the intermediate ones, if needed) or changing the expiration date of the generated certificate.

     Note: If you want to confirm the location of the truststore, you can do so by adding the following declaration to the server.xml file:

     <logging traceSpecification="SSL=all:SSLChannel=all"/>

     Lastly, start the server and look for lines that contain com.ibm.ssl.trustStore in the ${wlp.install.dir}/usr/servers/server_name/logs/trace.log file.
     • Import the public certificates of the other servers in the farm into the truststore that is referenced by the server.xml configuration file of the server. The tutorial Installing PMF in graphical mode provides you the instructions to exchange the certificates between two Liberty servers in a farm. For more information, see step 5 of Creating a farm of two Liberty servers that run PMF section.
     • Restart each instance of WebSphere Application Server Liberty profile to make the security configuration take effect. The following steps are needed for single sign-on (SSO) to work.
     • Exchange the signer certificates between all the servers in their respective truststores.
       
       

       Note: This step is mandatory for the farms that use WebSphere Application Server full profile or Liberty as security must be enabled. In addition, for Liberty farms, the same LTPA configuration must be replicated on each server to ensure single-sign on capability. To do this configuration, perform the following steps.

     • Start one member of the farm. In the default LTPA configuration, after the Liberty server starts successfully, it generates an LTPA keystore as ${wlp.user.dir}/servers/server_name/resources/security/ltpa.keys.
     • Copy the ltpa.keys file to the ${wlp.user.dir}/servers/server_name/resources/security directory of each farm member to replicate the LTPA keystores across the farm members. For more information about LTPA configuration, see Configuring LTPA on the Liberty profile.
   • WebSphere Application Server full profile
     Configure the truststore in the WebSphere Application Server administration console.
     • Log in to WebSphere Application Server administration console.
     • Select Security → SSL certificate and key management.
     • In Related Items, select Keystores and certificates.
     • In the Keystore usages field, make sure that SSL keystores is selected. You can now import the certificates from all the other servers in the farm.
     • Click NodeDefaultTrustStore.
     • In Additional Properties, select Signer certificates.
     • Click Retrieve from port. You can now enter communication and security details of each of the other servers in the farm. Follow the next steps for each of the other farm members.
     • In the Host field, enter the server host name or IP address.
     • In the Port field, enter the HTTPS transport (SSL) port.
     • In SSL configuration for outbound connection, select NodeDefaultSSLSettings.
     • In the Alias field, enter an alias for this signer certificate.
     • Click Retrieve signer information.
     • Review the information that is retrieved from the remote server and then click OK.
     • Click Save.
     • Restart the server.