11. Configuration
Prev |  | Next

## 11. Configuration

You use configuration files in the `$SERVER_HOME/config` directory to configure VWS. You can also configure the Equinox framework properties using the `$SERVER_HOME/lib/org.eclipse.virgo.kernel.launch.properties` file. This section divides the configuration of the server into the following high-level tasks:

- Configuring the kernel and the user region.

- Configuring embedded Tomcat servlet container.

- Configuring serviceability.

- Configuring the local provisioning repository.

- Configuring the hosted repository.

- Configuring the framework properties.

## 11.1 Configuring the Virgo Kernel and User Region

This section provides information about configuring the VWS kernel and the user region by updating the following files in the `$SERVER_HOME/config` directory:

Table 11.1. Kernel Configuration Files

Property File (prefixed by `org.eclipse.virgo`) | Description
--- | ---
`.kernel.properties` | Configures kernel deployment.
`.kernel.userregion.properties` | Configures the user region of VWS and enables the OSGi console.
`.kernel.users.properties` | Configures the users that are allowed to access the Admin Console, and roles to which they map.
`.kernel.jmxremote.access.properties` | Configures the permissions for users that are allowed to access the Admin Console.
`.kernel.authentication.config` | Configures the Java Authentication and Authorization Service (JAAS) for the Tomcat server users.

### Configuring Deployment

You can configure three properties of deployment: the pickup directory into which you copy applications for hot-deployment, the deployment timeout, and whether automatic cloning of deployed bundles is enabled.

To change any of these properties, edit the `deployer.XXX` properties of the `$SERVER_HOME/config/org.eclipse.virgo.kernel.properties` file. The following table describes these properties.

Table 11.2. Deployment Configuration Properties

Property | Description
--- | ---
`deployer.timeout` | Specifies the amount of time, in seconds, after which VWS times out while trying to deploy a bundle, library, or plan. The default value is `300`. If you want to disable deployment timeout, specify `0`.
`deployer.pickupDirectory` | Specifies the absolute or relative path to the pickup directory to which you copy applications for hot-deployment. Relative paths are relative to `$SERVER_HOME`. The default value is `./target/pickup.`.

The following listing displays the default configuration distributed with the VWS; only relevant sections of the `org.eclipse.virgo.kernel.properties` file are shown.

    deployer.timeout=300
    deployer.pickupDirectory=pickup

As the default configuration shows, the default pickup directory is `$SERVER_HOME/pickup` and the deployment timeout is 300 seconds.

### Configuring the User Region

The user region is the subsystem of VWS that supports deployed applications, both your own user applications and those of the server itself, such as the Admin Console. The user region is deliberately isolated from the kernel, which makes it much simpler for you to manage your applications with the Admin Console because the internal server bundles are not visible.

You configure the user region by updating properties in the `$SERVER_HOME/config/org.eclipse.virgo.kernel.userregion.properties` file; these properties are described in the following table.

WARNING: We strongly recommend that you update only the `initialArtifacts` and the `osgi.console` properties; updating other properties could cause VWS to fail. These properties are documented for your information.

Table 11.3. User Region Configuration Properties

Property | Description
--- | ---
`baseBundles` | Specifies the hard-coded list of bundles that VWS installs directly into the user region. Virgo Web Server does not perform any automatic dependency satisfaction for these bundles; in other words, you only get the bundles in the list and nothing more.
`packageImports` | Specifies the packages that exist in the kernel that VWS imports into the user region so that they are in turn available to be imported by bundles in the user region. This property supports a `.*` wildcard. For example, `org.eclipse.virgo.util.*` will import all packages that start with `org.eclipse.virgo.util`.
`serviceImports` | Specifies the services in the kernel that are imported into the user region so that they're available to bundles in the user region.
`serviceExports` | Specifies the services in the user region that are imported into the kernel so that they're available to bundles in the kernel.
`inheritedFrameworkProperties` | Specifies the framework properties, configured in the `$SERVER_HOME/lib/org.eclipse.virgo.kernel.launch.properties` file, that will also be set on the user region's nested framework.
`osgi.console` | Specifies the port number which the Equinox console will use. The usual port number is 2401. If specified, the Equinox console is enabled (with the Equinox Console Extension) during user region start. If not specified, the Equinox console is not available.
`initialArtifacts` | Specifies the artifacts that VWS deploys into the user region when the server starts. Virgo Web Server performs dependency satisfaction when it deploys these artifacts. This means that you only need to list the top-level artifacts that you care about; VWS automatically installs any other artifacts upon which they depend from the repository. You can use this property to convert a VWS into a Virgo Kernel by removing the `repository:plan/org.eclipse.virgo.server.web` plan.

### Configuring Authentication

Virgo Web Server uses the Java Authentication and Authorization Service (JAAS) framework to authenticate the administration user that connects to Web Servers using the Admin Console. This section describes how the authentication mechanism is configured by default, and the files that you need to update if you want to change the administration user, change their password, and so on.

The `$SERVER_HOME/config/org.eclipse.virgo.kernel.authentication.config` file configures the underlying authentication technology for VWS. The short file consists of the following entry:

    dm-kernel {
            org.eclipse.virgo.kernel.authentication.KernelLoginModule REQUIRED;
    };

The entry is named `dm-kernel`. This name corresponds to the `<Realm>` element in the `$SERVER_HOME/config/tomcat-server.xml` file that configures the JAAS authentication mechanism for the `Catalina` service of the Tomcat servlet container. The `dm-kernel` entry specifies that the JAAS LoginModule that VWS uses to authenticate users is `org.eclipse.virgo.kernel.authentication.KernelLoginModule` and that this `KernelLoginModule` is required to "succeed" in order for authentication to be considered successful. The `KernelLoginModule` succeeds only if the name and password supplied by the user are the ones it expects. The default administration username/password pair for Web Server is `admin/springsource`.

You configure the administration user in the `org.eclipse.virgo.kernel.users.properties` file. The default file for a freshly installed VWS is as follows:

    ##################
    # User definitions
    ##################
    user.admin=springsource

    ##################
    # Role definitions
    ##################
    role.admin=admin

The administration user that connect to the Admin Console must have the `admin` role. The preceding file shows how, by default, the `admin` role is assigned the `admin` user with password `springsource`.

If you want to change the administration user, update the `org.eclipse.virgo.kernel.users.properties` file. For example, if you want the `juliet` user, with password `supersecret`, to be the new adminstration user, update the file as shown:

    ##################
    # User definitions
    ##################
    user.juliet=supersecret

    ##################
    # Role definitions
    ##################
    role.admin=juliet

Be sure to restart VWS after you make this change for it to take effect.

The final file involved in VWS authentication is `$SERVER_HOME/config/org.eclipse.virgo.kernel.jmxremote.access.properties`. This file specifies the JMX access privileges that the administration user has; by default they are read and write, as shown in the following listing:

    admin=readwrite

The only other value you can enter is `readonly`, which means that the adminstration user would only be able to view information using the Admin Console.

Prev |  | Next
10.2 Undeploying Artifacts | Home | 11.2 Configuring Serviceability