# Installation and Configuration Guide

# Configuring and Starting WLS-VE Domains

This chapter contains the procedures and ancillary information necessary for successfully using WLS-VE. It shows how to create, start, and stop virtualized servers in a WebLogic Server domain, start and run this product, and how to use its features. It also describes conditions that must be met before you attempt to use the product. In some cases, WLS-VE procedures are identical to the same procedures in non-virtualized WebLogic Server. In those cases, the chapter will provide a brief description of the functionality and links to the relevant WebLogic Server documentation.

This chapter contains information on these subjects:

- Before You Begin
- Comparing Startup, Configuration, and Logging Options to Non-virtualized WLS
- Creating WLS-VE Domains
- Starting WLS-VE
- Additional Configuration Tasks
- Deploying an Application to WLS-VE

## Before You Begin

This section describes requirements for running WLS-VE successfully. You will probably have completed these sorts of tasks as a general practice; however, verifying that they are already met before you begin will reduce problems later on.

### Ensure Proper Components are in Place

Before attempting to run WLS-VE, ensure the following:

- ESX artifacts (clusters, disk mount, and so on) exist.
- NFS servers are up and running and configured properly for exporting the directories WLS-VE instances will need.

Note: | Please review important security information about the NFS servers in NFS Security Measures.

- Load balancers and Web servers have been configured.
- The WLS-VE ISO Image is available from VMware Virtual Infrastructure. BEA recommends that the ISO image reside in a datastore that is on each ESX Server's local disk or on a SAN. Normally, you copy it there during installation. See Copying the ISO Image.
- WLS-VE is installed along with any WLS patches/Liquid VM updates that might be required. The BEA license file and patch directory must be installed on the NFS server.
- Determine the IP addresses for your virtual machines.

## Comparing Startup, Configuration, and Logging Options to Non-virtualized WLS

If you have experience using non-virtualized WebLogic Server, you might want to use some of the configuration techniques common to that product. If so, you need to be aware that some of them will not work with WLS-VE.

- Some customers want to run a script to configure their environment before running WLS. You can do this only on the normal OS before starting the WLS-VE instance, not on the WLS-VE instance itself.
- When you create a domain with the Domain Configuration Wizard, specify the password. WLS encrypts it and stores it in the domain directory in the `boot.properties` and `SerializedSystemIni.dat` files. You cannot specify credentials at an interactive prompt, because WLS-VE does not offer one.
- To track the progress of WLS-VE, look at the log files stored in the NFS share. You'll find at least two different log files that might be of interest to you for tracking progress. The first one is the standard WebLogic Server log that is available in its normal location in the domain directory `<domain>/servers/<myserver>/logs/...` The other one is the LiquidVM Console Log. The Console Log is normally stored in the current working directory as seen from inside the WLS-VE instance. By default, that is `/domain` (that is, your domain directory on the NFS server). The default name of the file is `<vmname>`.Use your favorite tools (for example, `tail`) to monitor these log files.
- When using the WLS Domain Configuration Wizard, you should specify the Administration Server network address. The wizard will only display local addresses so, if your Administration Server will be a WLS-VE instance or on other host, you will have to type it in yourself. If you specify the Administration Server in the wizard, the `startWLSVE.sh` startup script that was created will include that Administration Server as a parameter.

## Creating WLS-VE Domains

To create a domain and WLS-VE servers ("virtualized servers"), use this procedure.

Note: | This procedure assumes the following:

- You have a supported configuration of BEA WebLogic Server 9.2 installed on your launcher machine, running on Windows or Linux.
- You have access to an NFS server.

1. Run the WLS Domain Configuration Wizard by using one of the procedures described in Table 7-1:

Table 7-1 Configuration Wizard Start-up Modes
To start the Configuration Wizard in the... | Do this...
--- | ---
Console Mode | Open a command-line shell and navigate to the `\common\bin` subdirectory of `<WEBLOGIC_HOME>` directory (for example, `c:\bea\weblogic92\common\bin`). From the command line, enter: `./config.sh` (or `config.cmd` for Windows)
Graphical Mode | On the Windows desktop, click Start and select Start>Programs>BEA Products>Tools>Configuration Wizard On Linux, set the DISPLAY environment variable, navigate to the `/common/bin` subdirectory of `<WEBLOGIC_HOME>` directory (for example, `/bea/weblogic92/common/bin`) and enter `./config.sh`

The Configuration Wizard launches.

2. Follow the prompts in the Configuration Wizard as you would for creating a new WLS domain (see Creating a New WebLogic Domain); however, since you are configuring a domain for WLS-VE, when you reach the Select Domain Source window, you must select Generate a domain configured automatically to support the following BEA products: and ensure that WebLogic Server VE Extensions is checked (this is a required selection and should already by checked).
3. Specify the Administration Server network address. The Configuration Wizard will only display local addresses so, if your Administration Server will be a WLS-VE instance or on another host, you will have to type it in yourself. If you specify the Administration Server in the wizard, the `startWLSVE_Admin.sh` startup script that was created will include that Administration Server as a parameter.

Note: | Unlike with non-virtualized WebLogic Server, you cannot reuse an IP address for multiple servers

4. Complete the Configuration Wizard per the requirements of your implementation. Create any needed Managed Servers on the Configure Managed Servers page of the Configuration Wizard, specifying for each Managed Server a name and optionally specifying a listen address, listen port, SSL listen port, and whether SSL is enabled. Note that since WLS-VE does not support the Node Manager, there is no need to configure any Node Manager-related options in the Configuration Wizard.

Be sure to note where you create your domain (assuming you can put this domain on the NFS server) and what you named your Managed Servers.

Note: | If you are going to boot the Administration Server on a virtual machine, Start Admin Server on the Creating a Domain window should remain unchecked.

5. In your local file system, navigate to `<DOMAIN-DIR>/bin/`and locate the file `startWLSVE.sh` (or `.cmd` on Windows) as described here:

   Table 7-2 Creating Start-up Scripts
   For... | Do this...
   --- | ---
   The Administration Server | Make a copy of this script named `startWLSVE_Admin.sh` (or `.cmd`).
   Each Managed Server | Make separate copies of `startWLSVE.sh` (or `.cmd`) for each Managed Server you plan to have and name them `startWLSVE_Managed_``nn``.sh` (or `.cmd`), where `nn` is a sequential number identifying the individual Managed Server; for example `startWLSVE_Managed__01`, `startWLSVE_Managed__02`, and so on.

The `bin/startWebLogic.cmd` and `startWebLogic.sh` files are not valid for WLS-VE.

6. Edit the start-up scripts `startWLSVE_Admin.sh` (or `.cmd`) and `startWLSVE_Managed_``nn``.sh` (or `.cmd`) by setting the properties required for your implementation. At the minimum, you must set the following values:

- Set `IP_ADDRESS` to a valid IP address. This must be an address that no one else will be attempting to use when you are trying to run your machine. Otherwise, you will receive a "Configured IP [...] in use by MAC" Error. You test an IP address for availability using `ping`; if there is no response to `ping` at that address, it is probably available. Check with your network administrator.
- Set `DOMAIN_MOUNT` to the NFS mount for this domain. Specify this property like this:

    DOMAIN_MOUNT=IPA.DD.RE.SS:/full/path/to/domain,uid=nnnnn,gid=nnnnn

where `gid` is the group identifier and `uid` the user identifier (see Configuring Group and User Names for an explanation of these identifiers); for example:

    DOMAIN_MOUNT=131.18.110.61:/space1/servers/bea_home/user_projects/domains/product-1,uid=10016,gid=10000

- Set `BEA_HOME_MOUNT` to the location of your `<BEA_HOME>` on your NFS server. Specify this property like this:

    BEA_HOME_MOUNT=IPA.DD.RE.SS:/full/path/to/BEA_HOME,uid=nnnnn,gid=nnnnn

where `gid` is the group identifier and `uid` the user identifier (see Configuring Group and User Names for an explanation of these identifiers); for example:

    BEA_HOME_MOUNT=131.18.110.61:/space1/servers/bea_home,uid=10016,gid=10000

- Set `TMP_MOUNT` to the location where the WLS-VE instance will store temporary files. Specify this property like this:

    TMP_MOUNT=IPA.DD.RE.SS:/full/path/to/temp_directory,uid=nnnnn,gid=nnnnn

where `gid` is the group identifier and `uid` the user identifier (see Configuring Group and User Names for an explanation of these identifiers); for example:

    TMP_MOUNT=131.18.110.61:/space1/servers/server_temp,uid=10016,gid=10000

Additionally, for each Managed Server, verify that the `ADMIN_URL` is pointing to the IP address of the Administration Server (for the Administration Server, `ADMIN_URL` must be blank).

Note: | The start-up scripts do not and should not include a path reference to the WebLogic Server classes. WLS-VE uses the WebLogic Server classes that are located in the WLS-VE ISO image.

Note: | To create a Managed Server in your WLS-VE domain, it is not enough to create a start-up script; you must also create the Managed Server instance in the domain, as described in step 4.

7. Verify that the servers start successfully by going to the `<DOMAIN_DIR>/bin/`directory and entering the start-up command; for example:

`startWLSVE_Admin.sh` (or `.cmd` on Windows)

OR

`startWLSVE_Managed_``nn``.sh` (or `.cmd` on Windows)

The server output will appear at `<DOMAIN_DIR>/WLS-<``servername``>/log`, unless you have specified a different location using the `LVM_CONSOLE_LOG` environment variable.

Note: | The message `JVM is booted` does not mean that your server is fully running. It means that your virtual machine has been started and that your server startup process has been initiated.

#### Other VM Configuration Properties

In addition to the required configuration properties for the Administration Server and Managed Servers, you can configure other aspects of your VM by setting any of the properties shown in the start-up script. Please refer to Additional Configuration Tasks for details.

### Configuring Group and User Names

When LiquidVM boots, it has to mount the `BEA_HOME` and `DOMAIN` directories, which are located on an NFS server. Any time you mount an NFS share, you provide a user and group name. When you attempt to read or write below the NFS share, the NFS server compares the user/group ID (`uid` and `gid`, respectively) with the access control list for the file or directory that you requested. You have to ensure that the user and group ID that you supply in the mount command has sufficient privileges to read and write in the domain directory. Note that if the domain directory is one or more directory levels below the share, the `uid` and `gid` must be able to read all of the directories from the share down to the domain directory. It must be able to read and write in the domain directory itself.

To ensure that read and write permissions are set up properly, run the Domain Configuration Wizard from the same OS user account that you plan to use to mount shares.

For example:

1. On an NFS server named myNFSServer, you export the `/myShare` directory as an NFS share. On the machine on which you ran the WLS-VE installer, you log in as user "pat" and run the Domain Configuration Wizard to create a domain in `/myShare/user_domains/base_domain`
2. Then, you get the `uid` and `gid` for "pat." To do this, use the UNIX command `id`. Your `uid`(s) and `gid`(s) will be displayed. For this example, let's say that they're 1112 and 1115.
3. When you edit the `/myShare/user_domains/base_domain/bin/startWLSVE_Admin.sh` startup script, for the `DOMAIN_MOUNT` variable, specify:

    set DOMAIN_MOUNT=myNFSServer.mycompany.com:/myShare/user_domains/base_domain,uid=1112,gid=1115

Pat's `uid` and `gid` must have read privileges for `myShare` and `user_domains`. They must have read and write privileges for `base_domain` and everything below it.

### DemoIdentity Keystore Warning

When you install WLS-VE, the installer generates a DemoIdentity keystore that includes a certificate for the host that runs the installer. This is not the host from which you will run the product. The installer then stores this certificate on the ISO. If SSL is used, this certificate is the default if no other certificate is specified.

When you launch WLS-VE, it will use a different IP address than the installation machine. WebLogic Server will generate a warning that the hostname is not the same as the host for the certificate. You can ignore this warning and the machine will run normally.

## Upgrading and Promoting Domains

Generally, upgrading and promoting virtualized domains requires the same steps used for upgrading and promoting non-virtualized domains. The main steps in this process are:

1. Plan the upgrade.

In this step, you need to inventory the application environment, verify supported configuration information, review the compatibility information, and create an upgrade plan

2. Prepare to upgrade.

In this step, you undeploy any deployed applications, shut down all servers in the application environment, back up the application environment, install any required BEA products, prepare the remote Managed Server domain directories, and set up the environment

3. Upgrade your application environment.
4. Complete post-upgrade procedure.

For detailed instructions on these steps, please see Upgrading WebLogic Application Environments.

Due to its virtualized nature, when you upgrade WLS-VE, depending upon your required upgrade scenario, you will have to modify the standard upgrade procedure to address important virtualization issues. Those are described below.

### Upgrade from a Non-virtualized WebLogic Server 9.2 to WLS-VE 9.2

When you upgrade an application from a non-virtualized implementation of WebLogic Server 9.2 to WLS-VE 9.2, you will need to make some modifications to the application code to ensure successful operation.

- Use the Domain Configuration Wizard to create an empty WLS-VE domain, copy the `<DOMAIN-DIR>/bin/startWLSVE.sh` or `.cmd` file, and edit the start file to work with your domain, as described in Creating WLS-VE Domains.
- Any Java commands that boot a server need to be changed from `java` to `java_esx`.
- Applications must continue to be able to run in a non-virtualized environment after they have been modified to work in the virtualized environment.
- If the application has hardcoded `localhost` as the host name, you must change the host name to the LiquidVM IP address.

Note: | If your application uses Pointbase, you will need to change `localhost` to the IP address of Pointbase.

- If your application uses default values for the host in the WLST `connect()` command, you will need to change it so that the hostname can be passed in.

### Upgrade from an Earlier Version of WebLogic Server to WLS-VE 9.2

You cannot migrate an application directly from an earlier version of WebLogic Server (for example, version 8.1) directly to WLS-VE 9.2. Instead, you need to follow the upgrade procedures outlined in Upgrading WebLogic Application Environments.

### Moving a WebLogic Server VE Domain To a Production Environment

Moving a WLS-VE domain into a production environment follows the same procedure used to move any development domain into production. The critical concerns here relate to added security and performance requirements in a production environment. See Securing a Production Environment for suggestions on securing your production environment. You also need to understand the NFS security issues described in NFS Security Measures. As with any migration, be sure to migrate the VM and any files stored on NFS server at the same time.

## Starting WLS-VE

As defined earlier, WLS-VE is WebLogic Server plus LiquidVM, which is BEA JRockit on BEA's BareMetal technology. When you start LiquidVM, it will simultaneously boot the associated server. You can start a WLS-VE instance either from the command line or from VMware VirtualCenter running on the ESX host.

Note: | You cannot start a WLS-VE server instance from the WebLogic Server Administration Console, nor can you use the Administration Console to resume or suspend a WLS-VE server instance. You can and should use the Administration Console to shut down a WLS-VE server instance.

### From the Command Line

To start WLS-VE from the command line:

1. Open a command-line shell and navigate to `<DOMAIN_DIR>/bin/.`
2. Use one of the commands shown in Table 7-3.

Table 7-3 WLS-VE Start-up Commands
To | Enter
--- | ---
Start a WLS-VE Administration Server | `startWLSVE_Admin.sh` (or `.cmd` on Windows)
Start a WLS-VE Managed Server | `startWLSVE_Managed_``nn``.sh` (or `.cmd` on Windows) where `nn` is a sequential number identifying the individual Managed Server

### From VirtualCenter

After you have started WLS-VE from the command line at least once, you can start it from the VMware VirtualCenter:

1. Launch VirtualCenter.
2. In the Inventory panel of VirtualCenter, drill down to and select the virtual machine associated with the machine you want to start.
3. Do one of the following:

- Click
- In the Commands panel, select Power On.
- Right-click the mouse to open a context menu and select Power On.

As WLS-VE starts up, a progress meter appears in the Recent Tasks panel.

Once WLS-VE has successfully started, the task status changes to Completed.

Note: | Please see DemoIdentity Keystore Warning for important information about a WLS-VE startup warning.

### Stopping WLS-VE

Stopping WLS-VE should be carefully considered as the ripple effects of an improper shutdown can cause unexpected results. Ideally, you should shut down WLS-VE only by using one of following methods:

- Use the WebLogic Server Administration Console for the machine and request the server to gracefully shutdown.

- For information on shutting down a server, see Shut Down a Server Instance and Control Graceful Shutdowns in the Administration Console Online Help.
- For information on gracefully shutting down the Managed Servers in a cluster, see Shut Down Servers in a Cluster in the Administration Console Online Help.

- Use WLST scripts to request the server to gracefully shutdown. For more information, see Shutdown in the WLST Command and Variable Reference.

Note: | You should not shut down WLS-VE by using the following methods:

- Clicking in VirtualCenter
- Pressing Ctrl-C

## Additional Configuration Tasks

Since WLS-VE contains both a JVM and a virtualized WebLogic Server instance, you can configure both devices by using the same configuration flags used by their non-virtualized editions. Usually, you can do this from the WebLogic Server administration console. Please refer to System Administration for BEA WebLogic Server 9.2 for complete information on how to:

- Configure a WebLogic Server environment
- Configure server security
- Configure system resources
- Configure and deploy applications
- Configure WebLogic Server environments for high availability

### Tuning LiquidVM

The JVM should already be well-tuned for most WebLogic Server applications but you can configure and tune a machine's Java behavior by setting the necessary Java options in the start-up script for the domain in question. Simply enter the standard J2SE start-up options or BEA JRockit's non-standard `-X` and `-XX` options at the `JAVA_OPTIONS=` statement.

Listing 7-1 shows a snippet of the Administration Server start-up script, `startWLSVE.cmd`, with `JAVA_OPTIONS=` highlighted.

Listing 7-1 startWLSVE.cmd Code Snippet

    @ECHO OFF
    SETLOCAL
    .
    .
    .
    set PRE_CLASSPATH=
    set POST_CLASSPATH=
    set JAVA_OPTIONS=
    set JAVA_PROPERTIES=

For example, suppose you want to start the machine so that LiquidVM uses a garbage collector (that is, a memory management system) optimized for application throughput. You would do this by setting `JAVA_OPTIONS` thusly:

    JAVA_OPTIONS="-xgcprio:throughput"

You can string together as many valid options as you need; however, you must place them within quotation marks and separate them with a single space. For example, the following code:

    JAVA_OPTIONS="-xgcprio:throughput -xgcreport -Xss:512k"

tells the JVM to:

- Start WLS-VE with its JVM using a garbage collector optimized for application throughput ("-xgcprio:throughput").
- Generate an end-of-run report that shows garbage collection statistics (`"`-xgcreport").
- Set the thread stack size (memory areas allocated for each Java thread for their internal use) to 512 KB ("-Xss:512k").

See the BEA JRockit Reference Manual for a list of valid LiquidVM start-up options and instructions for using them. For LiquidVM tuning and configuration guidelines, see Tuning Basics and Memory Management Basics in the BEA JRockit Diagnostics Guide.

### WLS-VE Configuration Properties

In addition to JVM behavior, you can also configure WLS-VE behavior by setting other parameters in the start-up script. The properties you can set are listed in Table 7-4.

Table 7-4 WLS-VE Start-up Options
Property | Description
--- | ---
`SERVER_NAME` | The WLS server name. In VMware `SERVER_NAME` is called `WLS-(SERVER_NAME)`
`ADMIN_URL` | The address Administration Server URL. This value must be set if you are configuring a Managed Server.
`PRODUCTION_MODE` | Set to true if this is production mode.
`WLS_USER` | The username used to access WLS. This value is set by the WLS Configuration Wizard.
`WLS_PW` | The password to use to access WebLogic Server. This value is set by the WLS Configuration Wizard.
`PRE_CLASSPATH` | Classpath to prepend to the standard classpath
`POST_CLASSPATH` | Classpath to append to the standard classpath
`JAVA_HEAP_SIZE` | The size of the Java heap, in megabytes.
`JAVA_OPTIONS` | Other options passed straight to the JVM
`JAVA_PROPERTIES` | Other Java properties on the form `-Dproperty=val` that will be passed straight to the JVM. This is similar to the `JVM_OPTIONS` but should only be used for properties.
`CPUS` | The number of CPUs to use (1,2,...)
`IP_ADDRESS` | The IP address for the server. If this property is not set, the server will use DHCP to dynamically get an IP address.
`LVM_CONSOLE_LOG` | The console log's path inside LiquidVM. This defaults to `/domain/<WLS=<SERVER_NAME>.log`
VI_NETWORK_NAME | The name of the VMware network this instance should use.
`VI_COMPUTE_RESOURCE` | The VMware Virtual Infrastructure Compute Resource to use. This is a host or a hosts running ESX Server.
`VI_RESOURCE_POOL` | The VMware Virtual Infrastructure Resource Pool that the host will use.
`LVM_INFO` | The default settings for LiquidVM including defaults for your virtualization environment. `VI_COMPUTE_RESOURCE` and `VI_RESOURCE_POOL` can be specified to override pieces of these settings.
`LVM_NETMASK` | The subnet mask for your network. You need to set this value if you are not using DHCP or you are not using default settings for netmask. The default netmask is 255.255.255.0
`LVM_GATEWAY` | The octet (`###.###.###.###`) for the gateway between your current network and one you want to access. You need to set this value if you are not using DHCP or you are not using default settings for netmask. The standard gateway is the static IP address masked with the set netmask, with a 1 in the lowest octet; for example if my netmask is standard 255.255.255.0 and my static IP is 172.23.80.102 then my default gateway is 172.23.80.1. If my netmask is 255.255.0.0 and the same static IP address then the gateway is 172.23.0.1.

## Deploying an Application to WLS-VE

Deploy applications on WLS-VE the same way you deploy them on non-virtuali.zed WebLogic Server. Application deployment generally involves the following tasks:

- Preparing applications and modules for deployment
- Configuring applications for production deployment
- Exporting an application for deployment to new environments
- Deploying applications and modules with `weblogic.Deployer`
- Redeploying applications in a production environment
- Managing deployed applications

These tasks are detailed in Deploying Applications on BEA WebLogic Server 9.2.