11. Configuration

You use configuration files in the $SERVER_HOME/config directory to configure VWS. You can also configure the OSGi framework using files in $SERVER_HOME/lib. This section divides the configuration of the server into the following high-level tasks:

11.1 Configuring the Virgo Kernel and User Region

This section provides information about configuring the VWS kernel and the user region.

Configuring kernel

To change any of the kernel properties, provide the new value to the startup script. For example: $SERVER_HOME/bin/startup.sh -Forg.eclipse.virgo.kernel.startup.wait.limit=3600. The following table describes all properties.

Table 11.1. Kernel Configuration Properties

Property (prefixed by org.eclipse.virgo)Description
.kernel.homeSpecifies the location of the Virgo Kernel. The property defaults to $SERVER_HOME.
.kernel.configSpecifies the location of the Virgo Kernel and User Region configuration files. The default value is $SERVER_HOME/config. The location of the configuration files can also be specified using -configDir startup parameter.
.kernel.domainSpecifies the JMX domain that should be used by the Virgo Kernel. The default value is org.eclipse.virgo.kernel.
.kernel.startup.wait.limitSpecifies the amount of time, in seconds, after which VWS times out while trying to start the kernel. The default value is 180 seconds.

Configuration files

The configuration of the Virgo Kernel and User Region by default is located in the $SERVER_HOME/config directory:

Table 11.2. Kernel Configuration Files

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

Configuring Deployment

You can configure two properties of deployment: the pickup directory into which you copy applications for hot-deployment and the deployment timeout.

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.3. Deployment Configuration Properties

PropertyDescription
deployer.pickupDirectorySpecifies 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 ./pickup.
deployer.timeoutSpecifies 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.

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 kernel 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 property; updating other properties could cause VWS to fail. These properties are documented for your information.

Table 11.4. User Region Configuration Properties

PropertyDescription
baseBundlesSpecifies 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.
bundleImports

Specifies the bundles in the kernel that VWS imports into the user region so that they are visible to bundles in the user region. This property supports an optional bundle-version attribute which specifies a version range. By default only the system bundle is imported.

Note that packages exported by these bundles are not automatically made available in the user region: these must be specified using the packageImports property.

packageImports

Specifies the packages 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 which is expanded based on the packages available in the kernel when the user region is created. For example, org.eclipse.virgo.util.* will import all packages that start with org.eclipse.virgo.util. (but not the package org.eclipse.virgo.util).

The property also supports matching attributes such as version, bundle-symbolic-name, bundle-version, and user-defined attributes. This can be used to import all the packages of a bundle imported using the bundleImports property. For example the following imports all the packages of the system bundle:

packageImports=*;bundle-symbolic-name="org.eclipse.osgi",\
 ...

Note that if a package is specified more than once in packageImports, the last occurrence is used and the earlier occurrences are ignored. For this reason, it is recommended that imports specifying matching attributes are placed earlier in the list than other imports so that if an import is specified with and without matching attributes, the form without the matching attributes is used.

serviceImportsSpecifies the services in the kernel that are imported into the user region so they are available to bundles in the user region.
serviceExportsSpecifies the services in the user region that are exported to the kernel so they are available to bundles in the kernel.
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, from the repository, any other artifacts upon which they depend.

The artifacts are specified as a comma separated list of URI strings of the form:

repository://type/name[/version]

where type is the artifact type (e.g. "plan", "par", "bundle", "configuration"), name is the (symbolic) name of the artifact, and, optionally, version is the version of the artifact. If version is omitted and there is at least one artifact in the repository with the given type and name, then the artifact with the highest version is selected. So, for example, the following entries are valid:

initialArtifacts=...,\
 repository://plan/APlan,\
 repository://bundle/ABundle/1.0


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:

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

The entry is named virgo-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 virgo-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.