Configuring Sun Java System Web Server

For Sun Java System Web Server, when you install the load balancer plug-in using the Sun Java System Application Server 9.1 installation wizard, the installation wizard automatically does all the necessary configuration. No manual configuration is required. The load balancer plug-in bundled with Application Server 9.1 supports the following versions of Sun Java System Web Server:

• Sun Java System Web Server 6.1

• Sun Java System Web Server 7.0

But, if you are using GlassFish v2, you must download the Application Server load balancer plug-in separately from http://download.java.net/javaee5/external/SunOS_X86/aslb/jars/aslb-9.1-MS4-b7.jar and make some manual changes to set it up. For detailed steps on how to install and set up the plug-in for GlassFish v2, refer to the section To Install the Load Balancing Plug-in (standalone) in Sun Java System Application Server 9.1 Installation Guide.

To Configure Sun Java System Web Server

Before You Begin

The following steps are automatically performed by the installation program for Application Server 9.1. But, if you are using GlassFish v2, you will need to perform these steps manually.

1. To the web server instance's magnus.conffile, add the following lines:

   ##BEGIN EE LB Plug-in Parameters
   Init fn="load-modules"
   shlib="web-server-install-dir/plugins/lbplugin/bin/libpassthrough.so"
   funcs="init-passthrough,service-passthrough,name-trans-passthrough" Thread="no"
   Init fn="init-passthrough"
   ##END EE LB Plug-in Parameters=

2. Append the following line if it does not exist already:

   Init fn="load-modules" shlib=".../libj2eeplugin.so" shlib_flags="(global|now)"

3. In the file web-server-install-dir/config/obj.conf, insert the following in a single line before the first occurrence of the string nametrans:

   Nametrans fn="name-trans-passthrough" name="lbplugin"
   config-file="web-server-install-dir/config/loadbalancer.xml"

   The order in which NameTrans entries appear in obj.conf is very important. The installer puts the NameTrans entries in the correct location, but if you are editing obj.conf for other purposes you must ensure that the order remains correct. In particular, the load balancer info must come before the document-root function. For more information on the obj.conf file, see Sun Java System Web Server 7.0 Administrator’s Configuration File Reference.

4. Append the following lines to the file web-server-install-dir/config/obj.conf:

   <Object name = "lbplugin"> 
   ObjectType fn="force-type" type="magnus-internal/lbplugin"
   PathCheck fn="deny-existence" path="*/WEB-INF/*"
   Service type="magnus-internal/lbplugin" fn="service-passthrough"
   Error reason="Bad Gateway" fn="send-error" uri="$docroot/badgateway.html"
   </Object>

5. Edit the web-server-install-dir/start script to update the LD_LIBRARY_PATH value to include app-server-install-dir/lib/lbplugin/lib.

   The app-server-install-dir/lib/lbplugin/lib directory contains binaries that the load balancer plug-in requires.

6. (Optional) For the new DAS-based Load Balancer Administration, configure the web server for SSL.

   For detailed instructions for Web Server 6.1 , see To Set Up the Load Balancer in SSL Mode for Sun Java System Web Server 6.1.

   For detailed instructions for Web Server 7, see Setting up the Load Balancer in SSL Mode for Web Server 7.

7. If the web server is not already running, start the web server.

Configuring Sun Java System Web Server to Use Auto Apply

Auto Apply is a feature provided by Application Server 9.1 to send the load balancer configuration automatically over the wire to the web server configuration directory. For more information about this feature, see Auto Apply. The following procedures explain how to configure Sun Java System Web Server (versions 6 and 7) to use this feature.

To Set Up the Load Balancer in SSL Mode for Sun Java System Web Server 6.1

You need to perform the steps in this section only if you want to use the Auto Apply feature of the load balancer plug-in. This feature helps to send the load balancer configuration automatically over the wire to the web server configuration directory.

1. Using a browser, access the Admin Console of Web Server and login.

2. Select your server instance and click on Manage.

3. Click on the Security tab.

4. Initialize the trust database by giving the username and password. This could be done using either the certutil command or the GUI. The following options of the certutil command could be used to initialize the trust database:

   certutil -N -P  "https-instance-name-hostname-" -d .

   • When prompted by certutil, enter the password to encrypt your keys. Enter a password, which will be used to encrypt your keys. The password should be at least eight characters long, and should contain at least one non-alphabetic character.

   • When prompted to enter a new password, specify your password.

5. Create a sample local Certificate Authority (CA) using the following command:

   certutil -S -P "https-boqueron.virkki.com-boqueron-" 
   -d . -n SelfCA -s "CN=Self CA,OU=virkki.com,C=US" 
   -x -t "TC,TC,TC" -m 101 -v 99 -5

   1. When prompted to enter 0-7 for the type of certificate, type 5 for SSL CA. When the prompt reappears, specify 9.

   2. When queried “Is this a critical extension [y/n]?,” specify “y.”

6. Use the above sample CA to generate a certificate

   certutil -S -P "https-instance-name-hostname-"
   -d . -n MyServerCert -s "CN=boqueron.virkki.com,C=US"
   -c SelfCA -t "u,u,u" -m 102 -v 99 -5

   1. When prompted to enter 0-7 for the type of certificate, type 1 for SSL Server. When the prompt reappears, specify 9.

   2. When queried “Is this a critical extension [y/n]?,” specify “y.”

7. Create an HTTPS listener as explained in the following steps:

   1. Log on to the web server's Administration Server.

   2. Select a server and click Manage.

   3. Click Add Listen Socket. In the Add Listen Socket page, do the following:

      1. Specify a port number.

      2. Ensure that the fully qualified domain name (FQDN) of the server is specified for the Server Name. For example, if the host name is machine1, and the domain name is server.example.com, then the FQDN is machine1.server.example.com.

      3. Select Enable from the Security drop-down list.

      4. Click OK.

   4. Go to Edit Listen Sockets page and select the Listen Socket that you just created.

   5. In the Listen Socket page, verify if the Server Certificate name is the same as the certificate name that you provided in Step 6.

To Export and Import the DAS Certificate for Sun Java System Web Server 6.1

1. If you are using Application Server 9.1, export the DAS certificate by executing the command:

   <appserver_install_dir>/lib/upgrade/pk12util -d <domain root>/config -o sjsas.p12-W
   <file password> -K <master password> -n s1as

   • If you are using GlassFish v2, you must use the following commands to export the DAS certificate:

     <JAVA_HOME>/bin/keytool -export -rfc -alias s1as -keystore
     <GLASSFISH_HOME>/domains/<DOMAIN_NAME>/config/keystore.jks-file s1as.rfc

     where, <GLASSFISH_HOME> indicates the Application Server installation directory and <DOMAIN_NAME> refers to the domain whose certificate is being exported.

   • Copy the certificate file to the web server configuration directory.

2. Import the DAS certificate.

   • If you are using Application Server 9.1, import the DAS certificate into the Web Server instance using the following commands:

     <webserver_install_dir>/bin/https/admin/bin/pk12util-i sjsas.p12 -d 
     <webserver_install_dir>/alias -W<file password> -K <webserver security db password> -P
     <instance-name>-<hostname>-

     <webserver_install_dir>/bin/https/admin/bin/certutil -M -n s1as -t "TCu"
     -d <webserver_install_dir>/alias -P <instance-name>-<hostname>-

     These commands make the Application Server CA a trusted CA to sign both client and server certificates.

   • If you are using GlassFish v2, import the DAS certificate from the rfc file created using certutil, the NSS security tool.

     <webserver_install_dir>/bin/certutil -A -a -n s1as -t "TCu" -i s1as.rfc 
     -d <webserver_install_dir>/alias -P <instance-name>-<hostname>-

     You can check the presence of this certificate by using the following command, which would list the s1as certificate along with other CA certificates including the default server certificate. Ensure that you type the command in a single line.

     <WS_INSTALL_ROOT>/bin/certutil -L 
     -d <webserver_install_dir>/alias -P <instance-name>-<hostname>-

3. If obj.conf does not contain the following lines, please append them at the end of the file. (If you are using Application Server 9.1, this step is automatically performed by the installation program.)

   <Object ppath="*lbconfigupdate*">
   PathCheck fn="get-client-cert" dorequest="1" require="1"
   <Object>
   <Object ppath="*lbgetmonitordata*">
   PathCheck fn="get-client-cert" dorequest="1" require="1"
   </Object>

4. You can verify the above set up from the DAS using the steps provided in the section Verifying the Setup. Instead of using the local CA, you can use any other CA and server certificate. In that case you can skip steps 5 and 6 listed in the previous section, but need to import the server certificate that you obtained from other CAs.

Setting up the Load Balancer in SSL Mode for Web Server 7

1. Start the Web Server's Administration Server using the following command.

   webserver-install-dir/admin_server/bin/startserv

2. Create an HTTPS listener as explained in the following steps. If an HTTP listener already exists, you can skip the following steps and proceed to the section To Export and Import the DAS Certificate for Sun Java System Web Server 7.

   1. Log in to Web Server Admin console.

   2. Select the default configuration. Generally, the default configuration name will be identical to the host name. To do this from the Common Tasks page, select the configuration from the Select Configurations list and click Edit Configuration. Alternatively, open the Configurations page and click on the default configuration name in Configurations table.

   3. If you are in the Common Tasks page, click Request Server Certificate. Else, if you are in the Configuration page, open the Certificates page and click the Request button from the Server Certificates table. This is required to create a self signed server certificate for this default configuration.

   4. Provide the details requested by the Request Server Certificate window.

      While doing so, just ensure that the value provided for "*Server Name (cn)" is the fully qualified domain name (FQDN) of the machine where the web server is installed. For example, if the host name is machine1, and the domain name is server.example.com, then the FQDN is machine1.server.example.com. Select the defaults wherever provided.

      You can also create a self-signed certificate using the following command. Make sure that you type the command in a single line.

      webserver-install-dir/bin/wadm create-selfsigned-cert --user=
      admin-user --server-name=host-name 
      --nickname=ServerCert --token=internal --config=config-name
      

   5. Go back to the selected configuration page.

   6. Open the HTTP Listeners page and click the New button. This is to create an SSL-enabled HTTP listener.

   7. Provide the details sought by the New HTTP Listener wizard. Ensure that the server name is the FQDN provided in the earlier step. Select the SSL button and from the Certificate list, select the previously created server certificate. For example, cert-machine1.server.example.com.

      You can also create an HTTP listener using the following commands. Make sure that you type each command in a single line.

      webserver-install-dir/bin/wadm create-http-listener 
      --user=admin-user --server-name=host-name 
      --default-virtual-server-name=default-virtual-server-name 
      --listener-port=8090 --config=config-name http-listener-ssl

      webserver-install-dir/bin/wadm set-ssl-prop 
      --user=admin-user --http-listener=http-listener-ssl 
      --config=config-name enabled=true server-cert-nickname=ServerCert

   8. Once you have performed the steps listed above, you would see the alert “Deployment Pending” on the top right corner of the Admin console. Click on it and follow the instructions to complete the deployment. This step ensures that the changes to the config store in the web server's Administration Server are copied to the web server instance.

To Export and Import the DAS Certificate for Sun Java System Web Server 7

By exporting and importing the DAS certificate, you can make the DAS a trusted client of Web Server. Client authentication using a DAS certificate ensures that only the DAS connects to Web Server as a trusted client.

1. Open a terminal window and set the LD_LIBRARY_PATH using the following command:

   export LD_LIBRARY_PATH=/opt/SUNWappserver/lib

2. Export the DAS certificate.

   • If you are using Application Server 9.1, export the DAS certificate by executing the command. The DAS certificate acts as both the server certificate as well as the client certificate.

     <appserver_install_dir>/lib/upgrade/pk12util -d <domain root>/config -o s1as.p12 -W
     <s1as.pk12-file-password> -K <master password> -n s1as

   • If you are using GlassFish v2, export the DAS certificate, named with the alias “s1as” using the Java SE 5.0 security tool called keytool. While doing so, select the -rfc option to export the certificate in the printable encoding format, as defined by the Internet RFC 1421 standard.

     From the command line, you can use the following commands to export the DAS certificate:

     <JAVA_HOME>/bin/keytool -export -rfc -alias s1as -keystore
     <GLASSFISH_HOME>/domains/<DOMAIN_NAME>/config/keystore.jks-file s1as.rfc

     where, <GLASSFISH_HOME> indicates the Application Server installation directory and <DOMAIN_NAME> refers to the domain whose certificate is being exported.

3. After exporting, copy the certificate file to the web server configuration directory.

4. Import the DAS certificate.

   • If you are using Application Server 9.1, import the DAS certificate into the Web Server instance and set the trust attributes for the certificate using the following commands:

     <webserver_install_dir>/bin/pk12util -i <path_to_s1as.pk12-file> 
     -d <webserver_install_dir>/admin-server/config-store/<default-config-name>/config 
     -K <webserver security db password> -W <s1as.pk12-file-passwd>

     <webserver_install_dir>/bin/certutil -M -n s1as -t "TCu" 
     -d <webserver_install_dir>/admin-server/config-store/<default-config-name>/config

     These commands make the Application Server CA be a trusted CA to sign both client and server certificates.

   • If you are using GlassFish v2, import the DAS certificate from the rfc file created using certutil, the NSS security tool.

     <webserver_install_dir>/bin/certutil -A -a -n s1as -t "TCu" -i s1as.rfc -d
     <webserver_install_dir>/admin-server/config-store/<CONFIG_NAME>/config

     where, <webserver_install_dir> refers to the web server installation directory and <CONFIG_NAME> refers to the configuration name created for the default web server instance.

     You can check the presence of this certificate by using the following command, which would list the s1as certificate along with other CA certificates including the default server certificate. Make sure that you type the entire command in a single line.

     <webserver_install_dir>/bin/certutil -L -d
     <webserver_install_dir>/admin-server/config-store/
     <DEFAULT_CONFIG_NAME>/config

     You can also use the Web Server Admin Console to view this. Select the configuration to which the certificate has been imported to (default config, in this case), and then select the Certificates tab. To look at all the certificates available, select the Certificate Authorities sub tab.

5. Make the following configuration changes to Web Server 7 if you are using GlassFish v2. You can skip to the next step if you are using Application Server 9.1.

   1. Append the following lines to obj.conffile located at <WS_INSTALL_ROOT>/admin-server/config-store/<DEFAULT_CONFIG_NAME>/config/. Make sure that you type in these lines without any trailing spaces.

       <Object ppath="*lbconfigupdate*">
       PathCheck fn="get-client-cert" dorequest="1" require="1"
      </Object>
      <Object ppath="*lbgetmonitordata*">
       PathCheck fn="get-client-cert" dorequest="1" require="1"
      </Object>

6. Deploy the configuration. While doing the changes listed in the previous steps, the Admin Console would mark this configuration to be deployed.

   1. Select the icon for Deployment Pending in the Web Server Admin Console. You can also deploy this configuration using the CLI utility wadm as follows:

      <webserver_install_dir>/bin/wadm deploy-config --user=<admin> <DEFAULT_CONFIG_NAME>

7. Test this setup from the GlassFish DAS to see if it communicates with the configured HTTP Load Balancer over SSL. For more information, see Verifying the Setup.