# Configuration and User Guide

# Understanding LiquidVM

WLS-VE combines WebLogic Server (WLS) with LiquidVM, a Java Virtual Machine (JVM) that works with hypervisor software and provides only the set of operating system (OS) features that WLS needs to offer its full range of services. Details about LiquidVM are provided in the following topics:

- What is LiquidVM?
- Understanding the LiquidVM File System
- Using the Virtual Local Disk
- Using the LiquidVM SSH Service
- Using LiquidVM in Passive Mode

## What is LiquidVM?

LiquidVM is a virtualization enabled version of the JRockit JVM that can run on a hypervisor without a standard OS, allowing Java applications to run directly on the virtualized hardware. For more information, see WLS-VE Overview.

LiquidVM provides the following features:

- JRockit JVM as the Java runtime component.
- A scaled-down OS kernel that replaces the OS for LiquidVM. It differs from a normal OS in that it is a single-user, single-process environment that is designed to only run a single JVM. No other processes can be started. It implements the following services that the JRockit JVM needs to run Java:

- Low-level memory management
- Thread-scheduling
- Filesystem
- Networking
- Interaction with the hypervisor

- Java-based services, started after the JRockit JVM has started, that run in threads that are separate from your application. The LiquidVM services are:

- LiquidVM SSH-service
- LiquidVM heap-resizer
- LiquidVM syslog publisher

- Tools that are used to create and control LiquidVM instances. The LiquidVM tools run on a standard OS; they do not run inside LiquidVM. LiquidVM tools include:

- LiquidVM launcher—used to start and stop LiquidVM instances
- LiquidVM Configuration Wizard—used to configure the connection between LiquidVM and the VMware VirtualCenter

- A virtual local disk for each virtual machine. The local disk removes the dependence on NFS and provides faster and more secure file transfers

## Understanding the LiquidVM File System

The LiquidVM file system is very similar to most Unix-like OSes. There is a single root (`/`) directory; disks and remote NFS file-shares can be mounted in sub-directories. By default, the virtual disk, if configured, is mounted in the root directory (`/`).

The directory structure for WLS-VE is described in Table 2-1.

Table 2-1 WLS-VE Directory Structure
Directory | Contents | Notes
--- | --- | ---
`/appliance` | The contents of the WLS-VE ISO image | This directory is read-only. The WLS-VE ISO image file to be used is specified in the `bea.lvm.info` file using the `vmwareDiskPath` parameter. For example: `vmwareDiskPath=[storage1] wlsve/wlsve922.iso` For more information on `/appliance`, see The Installation Directory for the WLS-VE ISO Image in the WLS-VE Installation Guide.
`/bea` | `license.bea` `patch_weblogic` `nnn` | The default location for the BEA Home directory on the virtual local disk. You can change the location of the BEA Home directory by specifying the `-Dbea.home` option in the WLS-VE start script. The BEA Home directory contains the `license.bea` file, and any WLS patches.
`/domain` | server-root directory log files application classes | The default location of the WLS domain and the current working directory for WLS-VE.
/tmp |  | Directory for temporary files created when WLS boots. The temporary files are erased each time the LiquidVM instance reboots.

## Using the Virtual Local Disk

LiquidVM provides a virtual local disk for each virtual machine. The local disk can be mapped to a SAN disk attached to the ESX server. You specify the size of the disk by passing the `diskSize` parameter as a startup option to the LiquidVM launcher. To do so, specify the disk size in the WLS-VE start script using the `LVM_DISKSIZE` option. The default is 1GB (1024). For more information, see Editing the Start Scripts. If no disk is specified, the local disk is not created.

The first time that you boot LiquidVM, it detects that a virtual hard disk is attached and that it is empty. LiquidVM formats the disk and mounts it in the root directory (`/`).

To the VMware ESXserver, the virtual hard disk is a `vmdk` file. The `vmdk` file is placed in the same directory as the Virtual Machine's configuration file on the ESX server/SAN. You can specify which VMware datastore the VM configuration files and the virtual hard disk should be placed in by specifying the `vmwareVmDatastore` option to the launcher. To do so, add a `vmwareVmDatastore=` entry to the `bea.lvm.info` file.

You can transfer files to and from the local disk by using the LiquidVM SSH service. For more information, see Using the LiquidVM SSH Service.

### Determining the Amount of Free Disk Space

To determine the amount of free disk space on your virtual machine while the WLS-VE instance is running, press F1 in the VMware VM console. Details about the running system, including the amount of free disk space, are displayed in the console.

### Increasing the Size of the Local Disk

If your disk is full, you can shut-down WLS-VE and specify a larger disk by increasing the value of the `LVM_DISKSIZE` property in the WLS-VE start script.

VMware does not provide a way to increase the size of the disk. Instead, when you restart WLS-VE, the LiquidVM launcher creates a new larger disk and copies the files from the old disk to the new disk. When you increase the size of the disk, the initial restart of WLS-VE will take longer depending on the size of the disk and the amount of files to be copied.

Note: | LiquidVM does not provide a mechanism to reduce the size of a disk.

## Using the LiquidVM SSH Service

LiquidVM provides a SSH2-compatible service for transporting files to and from LiquidVM. The SSH service does not provide shell services; that is, LiquidVM does not support scripts or editing files from the SSH shell.

The SSH service in LiquidVM provides an encrypted communication channel between the server and the client. The encryption protocol used is AES-128. Unencrypted communication is not supported.

You can transfer files using the `scp` and `sftp` extensions to SSH. The Linux OS includes `sftp` and `scp` clients. On Windows systems, several free SSH2 clients are available for download (e.g., `PuTTy`, `WinSCP`, `FSecure`, and `FileZilla`.)

Note: | LiquidVM does not support SSH1 clients.

You authenticate with the SSH service using either password-based or public/private key authentication. For more information, see Authenticating with the SSH Service.

LiquidVM is a single-process, single-user environment, therefore only the `liquidvm` user is supported. Multiple users cannot login into LiquidVM.

### SSH Listen Port

The SSH2 server normally listens on the standard SSH port (port 22), but you can change the SSH listen port by setting the Java property`-Dlvm.ssh.port`. You may prefer to change the SSH port to something other than the default (port 22), since most SSH attacks try to attack the default port.

### Authenticating with the SSH Service

When you use the LiquidVM launcher to create a new instance, you can specify the type of authentication to be used. To use public/private key authentication, you need to provide your public key as a startup option to the LiquidVM launcher. To do so, specify the location of the public key in the WLS-VE start script using the `LVM_SSH_PUBLIC_KEY` option. For more information, see Editing the Start Scripts. When you attempt to authenticate with the SSH service, you will be prompted to provide your private key.

In a development environment, you may not want to bother with keys and secure passwords. In that case, LiquidVM provides a simpler, but unsafe method, of specifying an SSH password in clear-text from the launcher. You can specify the password in the WLS-VE start script using the `LVM_SSH_UNSAFE_PASSWORD` option.

Caution: | The password is stored in clear-text. This option should not be used in a production environment. BEA recommends using public/private key authentication in development environments also. Once you have specified a real password or set up an SSH public-key, the unsafe password is no longer valid.

### Auditing SSH Actions

The SSH service will send audit messages to the syslog for the following actions:

- Successful or failed log-in attempts. These audit messages include information about where the client tried to login from and the authentication method used.
- Logouts

You can use remote logging facilities to send these message to a remote log-collector for compliancy verification. For more information, see Configuring Logging.

## Using LiquidVM in Passive Mode

To copy files to or from the LiquidVM instance before starting WLS, you can use LiquidVM in passive mode. In passive mode, only the LiquidVM services, including the SSH service, are started. WLS is not started.

To start LiquidVM in passive mode, add the `startMode=passive` option to the launcher start arguments. Once LiquidVM is started in passive mode, you can log in over SSH and transfer your files. When you have finished transferring your files, you can either restart the server or login over SSH and run the start command to resume execution.

If you want the LiquidVM launcher to wait for the SSH service to be started before the launcher exits, you can specify `waitForSSH=true`. This can be useful in a scripting environment where you first start the instance and then you want to copy files from or to the server as soon as SSH is running on the newly started server.