13 Setting Up Node Manager for an Enterprise Deployment

This chapter describes how to configure Node Manager according to the Enterprise Deployment recommendations.

This chapter includes the following sections:

13.1 Overview of the Node Manager

The Node Manager enables you to start and stop the Administration Server and the managed servers.

Oracle recommends using host name verification for the communications between Node Manager and the Administration Server. This requires the use of certificates for the different addresses communicating with the Administration Server. In this chapter, the steps for configuring SOAHOST1 and SOAHOST2 certificates for host name verification are provided. Similar steps would be required for BAMHOST1 and BAMHOST2 in a BAM Enterprise Deployment topology. Although the appropriate host name changes in the steps are required for BAM, the procedure and syntax are exactly the same.

13.2 Changing the Location of Node Manager Log

Oracle recommends placing your Oracle Fusion Middleware deployment's NodeManager's log in a different location from the default (which is inside the MW_Home where Node Manager is located).

To change the location of the Node Manager log, edit the nodemanager.properties file located in the following directory:

MW_HOME/wlserver_10.3/common/nodemanager

Oracle recommends locating this file outside of the MW_HOME directory, and inside the admin directory for the deployment.

Add the following line to nodemanager.properties:

LogFile=ORACLE_BASE/admin/nodemanager.log

Restart Node Manager for the change to take effect.

13.3 Enabling Host Name Verification Certificates for Node Manager in SOAHOST1

Host name verification enables communication between Node Manager and the Administration Server. This verification requires the use of certificates for the different addresses communicating with the Administration Server.

This section contains the following topics:

13.3.1 Generating Self-Signed Certificates Using the utils.CertGen Utility

This section describes the procedure for creating self-signed certificates on SOAHOST1.mycompany.com. Create these certificates using the network name/alias.

The directory where keystores and trust keystores are maintained must be on shared storage that is accessible from all nodes so that when the servers fail over (manually or with server migration), the appropriate certificates can be accessed from the failover node. Oracle recommends using central or shared stores for the certificates used for different purposes (for example, SSL set up for HTTP invocations). In this case, SOAHOST2 uses the cert directory created for SOAHOST1 certificates.

For information on using trust CA certificates instead, see "Configuring Identity and Trust" in Oracle Fusion Middleware Securing Oracle WebLogic Server.

About Passwords

The passwords used in this guide are used only as examples. Use secure passwords in a production environment. For example, use passwords that include both uppercase and lowercase characters as well as numbers.

To create self-signed certificates:

  1. Set up your environment by running the WL_HOME/server/bin/setWLSEnv.sh script:

    In the Bourne shell, run the following command:

    . setWLSEnv.sh
    

    Verify that the CLASSPATH environment variable is set:

    echo $CLASSPATH
    
  2. Create a user-defined directory for the certificates:

    mkdir certs
    
  3. Change directory to the user-defined directory.

    cd certs
    
  4. Run the utils.CertGen tool from the user-defined directory to create the certificates for both HOST. mycompany.com and VIP. mycompany.com.

    Syntax:

    java utils.CertGen key_passphrase cert_file_name key_file_name [export | domestic] [hostname]

    Examples:

    java utils.CertGen welcome1 SOAHOST1.mycompany.com_cert SOAHOST1.mycompany.com_key domestic SOAHOST1.mycompany.com
    
    java utils.CertGen welcome1 ADMINVHN.mycompany.com_cert ADMINVHN.mycompany.com_key domestic ADMINVHN.mycompany.com
    

13.3.2 Creating an Identity Keystore Using the utils.ImportPrivateKey Utility

In previous sections you have created an identity keystore that resides in a shared storage. In this section new keys for SOAHOST2 are added to the store. Import the certificate and private key for both SOAHOST2 and SOAHOST2VHN1 into the Identity Store. Make sure that you use a different alias for each of the certificate/key pair imported.

Syntax:

java utils.ImportPrivateKey keystore_file keystore_password certificate_alias_to_use private_key_passphrase certificate_file private_key_file keystore_type

Examples:

java utils.ImportPrivateKey appIdentityKeyStore.jks welcome1
            appIdentity1 welcome1
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/SOAHOST1_cert.pem
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/SOAHOST1_key.pem

java utils.ImportPrivateKey appIdentityKeyStore.jks welcome1
            appIdentity2 welcome1
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/SOAHOST1VHN1_cert.pem
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/SOAHOST1VHN1_key.pem

java utils.ImportPrivateKey appIdentityKeyStore.jks welcome1
            appIdentity3 welcome1
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/ADMINVHN_cert.pem
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/ADMINVHN_key.pem

13.3.3 Creating a Trust Keystore Using the Keytool Utility

To create the Trust Keystore on SOAHOST1.mycompany.com.

  1. Copy the standard java keystore to create the new trust keystore since it already contains most of the root CA certificates needed. Oracle does not recommend modifying the standard Java trust key store directly. Copy the standard Java keystore CA certificates located under the WL_HOME/server/lib directory to the same directory as the certificates. For example:

    cp WL_HOME/server/lib/cacerts
    ORACLE_BASE/admin/domain_name/aserver/domain_namecerts/appTrustKeyStore.jks
    
  2. The default password for the standard Java keystore is changeit. Oracle recommends always changing the default password. Use the keytool utility to do this. The syntax is:

    keytool -storepasswd -new NewPassword -keystore TrustKeyStore -storepass Original_Password
    

    For example:

    keytool -storepasswd -new welcome1 -keystore appTrustKeyStore.jks -storepass changeit
    
  3. The CA certificate CertGenCA.der is used to sign all certificates generated by the utils.CertGen tool and is located at WL_HOME/server/lib directory. This CA certificate must be imported into the appTrustKeyStore using the keytool utility. The syntax is:

    keytool -import -v -noprompt -trustcacerts -alias AliasName
     -file CAFileLocation -keystore KeyStoreLocation -storepass KeyStore_Password
    

    For example:

    keytool -import -v -noprompt -trustcacerts -alias clientCACert -file
     WL_HOME/server/lib/CertGenCA.der -keystore appTrustKeyStore.jks -storepass welcome1
    

13.3.4 Configuring Node Manager to Use the Custom Keystores

To configure the Node Manager to use the custom keystores, add the following lines to the end of the nodemanager.properties file located in the WL_HOME/common/nodemanager directory:

KeyStores=CustomIdentityAndCustomTrust
CustomIdentityKeyStoreFileName=Identity KeyStore
CustomIdentityKeyStorePassPhrase=Identity KeyStore Passwd
CustomIdentityAlias=Identity Key Store Alias
CustomIdentityPrivateKeyPassPhrase=Private Key used when creating Certificate

Make sure to use the correct value for CustomIdentityAlias for Node Manager's listen address. For example on SOAHOST1, use appIdentity1 according to the steps in Section 13.3.3, "Creating a Trust Keystore Using the Keytool Utility."

(appIdentity1 mapped to the SOAHOST1 listen address).
Example for Node 1:
KeyStores=CustomIdentityAndCustomTrust
CustomIdentityKeyStoreFileName=ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/appIdentityKeyStore.jks
CustomIdentityKeyStorePassPhrase=welcome1
CustomIdentityAlias=appIdentity1
CustomIdentityPrivateKeyPassPhrase=welcome1

The passphrase entries in the nodemanager.properties file are encrypted when you start Node Manager as described in Section 13.4, "Starting the Node Manager on SOAHOST1." For security reasons, minimize the time the entries in the nodemanager.properties file are left unencrypted. After you edit the file, start Node Manager as soon as possible so that the entries are encrypted.

13.3.5 Using a Common or Shared Storage Installation

When using a common or shared storage installation for MW_HOME, Node Manager is started from different nodes using the same base configuration (nodemanager.properties). Add the certificate for all the nodes that share the binaries to the appIdentityKeyStore.jks identity store.by creating the certificate for the new node and import it to appIdentityKeyStore.jks, as described in Section 13.3.1, "Generating Self-Signed Certificates Using the utils.CertGen Utility.". Once the certificates are available in the store, each node manager must point to a different identity alias to send the correct certificate to the Administration Server.

To set different environment variables before starting Node Manager in the different nodes:

cd WL_HOME/server/bin
export JAVA_OPTIONS=-DCustomIdentityAlias=appIdentitySOAHOST1

cd WL_HOME/server/bin
export JAVA_OPTIONS=-DCustomIdentityAlias=appIdentitySOAHOSTn

13.4 Starting the Node Manager on SOAHOST1

Start Node Manager on SOAHOST1 using the startNodeManager.sh script.

Note:

If you have not configured and started Node Manager yet, run the setNMProps.sh script as specified in section Section 8.4.2, "Starting Node Manager on SOAHOST1." After running this script you can use the start script, which is required for SOA and BAM.

To start Node Manager on SOAHOST1:

SOAHOST1> cd WL_HOME/server/bin
SOAHOST1> export JAVA_OPTIONS=-DCustomIdentityAlias=appIdentityX
SOAHOST1> ./startNodeManager.sh

Note:

Ensure that you specify the custom identity alias specifically assigned to each host, so appIdentity1 for ...HOST1 and appIdentity2 for ...HOST2, and so on.

13.5 Enabling Host Name Verification Certificates for the Node Manager in SOAHOST2

Host name verification enables communication between Node Manager and the Administration Server. This verification requires the use of certificates for the different addresses communicating with the Administration Server.

Perform these steps to set up SSL for communication between the Node Manager and the Administration Server:

13.5.1 Generating Self-Signed Certificates Using the utils.CertGen Utility

This section describes the procedure for creating self-signed certificates on SOAHOST2.mycompany.com. Create these certificates using the network name/alias.

The directory where keystores and trust keystores are maintained must be on shared storage that is accessible from all nodes so that when the Administration Server or SOA servers fail over, (manually or with server migration), the nodes can access the appropriate certificates. In this case, SOAHOST2 uses the cert directory created for SOAHOST1 certificates. If you are maintaining duplicated stores, create user-defined directory for the certificates.

Create self-signed certificates using the untils.CertGen utility using the network name/alias.

For information on using trust CA certificates instead, see "Configuring Identity and Trust" in Oracle Fusion Middleware Securing Oracle WebLogic Server.

To create self-signed certificates on SOAHOST2.mycompany.com:

  1. Set up your environment by running the WL_HOME/server/bin/setWLSEnv.sh script:

    In the Bourne shell, run the following command:

    . setWLSEnv.sh
    

    Verify that the CLASSPATH environment variable is set:

    echo $CLASSPATH
    
  2. Create a user-defined directory for the certificates:

    mkdir certs
    
  3. Change directory to the user-defined directory.

    cd certs
    
  4. Run the utils.CertGen tool from the user-defined directory to create the certificates for both SOAHOST2 and SOAHOST2VHN1.

    Syntax:

    java utils.CertGen key_passphrase cert_file_name key_file_name
    export | domestic hostname
    

    Examples:

    java utils.CertGen welcome1 SOAHOST2_cert SOAHOST2_key
                 domestic SOAHOST2.mycompany.com
    
    java utils.CertGen welcome1 SOAHOST2VHN1_cert SOAHOST2VHN1_key
                 domestic SOAHOST2VHN1.mycompany.com
    

13.5.2 Importing Identities in SOAHOST2 using the "utils.ImportPrivateKey" Utility

The procedures described in the previous sections created an Identity keystore that resides in a shared storage. In this section new keys for SOAHOST2 are added to the store. Import the certificate and private key for both SOAHOST2 and SOAHOST2VHN1 into the Identity Store. Make sure you use a different alias for each of the certificate/key pairs imported.

To create an Identity Keystore on SOAHOST2.mycompany.com:

Syntax:

java utils.ImportPrivateKey keystore_file keystore_password certificate_alias_to_use private_key_passphrase certificate_file private_key_file keystore_type

Examples:

java utils.ImportPrivateKey appIdentityKeyStore.jks welcome1
            appIdentity3 welcome1
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/SOAHOST2_cert.pem
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/SOAHOST2_key.pem

java utils.ImportPrivateKey appIdentityKeyStore.jks welcome1
            appIdentity4 welcome1
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/SOAHOST2VHN1_cert.pem
            ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/SOAHOST2VHN1_key.pem

13.5.3 Configuring Node Manager to Use the Custom Keystores

To configure Node Manager to use the custom keystores:

  1. Add the following lines to the end of the nodemanager.properties file located in the WL_HOME/common/nodemanager directory.

    KeyStores=CustomIdentityAndCustomTrust
    CustomIdentityKeyStoreFileName=Identity KeyStore
    CustomIdentityKeyStorePassPhrase=Identity KeyStore Passwd
    CustomIdentityAlias=Identity Key Store Alias
    CustomIdentityPrivateKeyPassPhrase=Private Key used when creating Certificate
    

    Make sure to use the correct value for CustomIdentityAlias on each node. For example, on SOAHOST2, use "appIdentity3".

    Example for Node 2:

    KeyStores=CustomIdentityAndCustomTrust
    CustomIdentityKeyStoreFileName=ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/appIdentityKeyStore.jks
    CustomIdentityKeyStorePassPhrase=welcome1
    CustomIdentityAlias=appIdentity3
    CustomIdentityPrivateKeyPassPhrase=welcome1
    

    Note:

    The passphrase entries in the nodemanager.properties file get encrypted when you start Node Manager, as described in Section 13.6, "Starting Node Manager on SOAHOST2."

    For security reasons, you want to minimize the time the entries in the nodemanager.properties file are left unencrypted. After you edit the file, you should start Node Manager as soon as possible so that the entries get encrypted.

13.6 Starting Node Manager on SOAHOST2

To start Node Manager on SOAHOST2 using the startNodeManager.sh script, follow the steps in Section 13.4, "Starting the Node Manager on SOAHOST1." Run the commands from SOAHOST2.

Note:

Verify that Node Manager is using the appropriate stores and alias from the NodeManager output. Node Manager should prompt out the following:

CustomIdentityKeyStoreFileName=ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/appIdentityKeyStore.jks
CustomIdentityAlias=appIdentityX

Host name verification works if you apply a test configuration change to the servers and it succeeds without Node Manager reporting any SSL errors.

13.7 Configuring WebLogic Servers to Use the Custom Keystores

Configure the WebLogic Servers to use the custom keystores using the Oracle WebLogic Server Administration Console. Complete this procedure for the Administration Server, the WLS_WSMn and the WLS_SOAn servers.

The example directory path given in Step 6 is just an example. Oracle does not recommend putting keystores into the aserver directory, but recommends putting the keystore in shared storage. Having a separate directory for certificates is a better solution.

To configure the identity and trust keystores:

  1. Log in to the Administration Console, and click Lock & Edit.

  2. In the left pane, expand Environment, and select Servers.

  3. Click the name of the server for which you want to configure the identity and trust keystores.

  4. Select Configuration, and then Keystores.

  5. In the Keystores field, select the "Custom Identity and Custom Trust" method for storing and managing private keys/digital certificate pairs and trusted CA certificates.

  6. In the Identity section, define attributes for the identity keystore.

    1. Custom Identity Keystore: Enter the fully qualified path to the identity keystore:

      ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/appIdentityKeyStore.jks 
      
    2. Custom Identity Keystore Type: Leave this field blank, it defaults to JKS.

    3. Custom Identity Keystore Passphrase: Enter the password Keystore_Password you provided in Section 13.3.2, "Creating an Identity Keystore Using the utils.ImportPrivateKey Utility."

      This attribute may be optional or required depending on the type of keystore. All keystores require the passphrase in order to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WebLogic Server reads only from the keystore, so whether or not you define this property depends on the requirements of the keystore.

  7. In the Trust section, define properties for the trust keystore:

    1. Custom Trust Keystore: Enter the fully qualified path to the trust keystore:

      ORACLE_BASE/admin/domain_name/aserver/domain_name/certs/appTrustKeyStore.jks 
      
    2. Custom Trust Keystore Type: Leave this field blank, it defaults to JKS.

    3. Custom Trust Keystore Passphrase: The password you provided in as New_Password in Section 13.3.3, "Creating a Trust Keystore Using the Keytool Utility."

      As mentioned in the previous step, this attribute may be optional or required depending on the type of keystore.

  8. Click Save.

  9. To activate these changes, in the Change Center of the Administration Console, click Activate Changes.

  10. Click Lock & Edit.

  11. Select Configuration, then SSL.

  12. In the Private Key Alias field, enter the alias you used for the host name the managed server listens on.

    In the Private Key Passphrase and the Confirm Private Key Passphrase fields, enter the password for the keystore that you created in Section 13.3.2, "Creating an Identity Keystore Using the utils.ImportPrivateKey Utility."

  13. Click Save.

  14. Click Activate Changes in the Administration Console's Change Center to make the changes take effect.

  15. Restart the server for which the changes have been applied.

  16. Verify that the communication between Node Manager, Administration Server and the managed servers is correct by enabling hostname verification:

    1. For each server, in the Administration Console, select Configuration, SSL, Advanced, Hostname Verification, and then BEA HostName Verifier.

    2. Restart the servers using the Administration Console.