13.6 Configuring the Kernel and User Region
Prev | 13. Configuration | Next

## 13.6 Configuring the Kernel and User Region

This section provides information about configuring the Virgo kernel and the User Region.

### Configuring the Kernel

To change any of the kernel properties, provide the new value to the startup script. The following table describes all properties.

Table 13.7. Kernel Configuration Properties

Property (prefixed by `org.eclipse.virgo`) | Description | Default Value
--- | --- | ---
`.kernel.home` | Specifies the location of the Virgo Kernel. | `$SERVER_HOME`
`.kernel.config` | Specifies the location of the Virgo Kernel and User Region configuration files. The location of the configuration files can also be specified using `-configDir` startup parameter. | `$SERVER_HOME/configuration`
`.kernel.domain` | Specifies the JMX domain that should be used by the Virgo Kernel. | `org.eclipse.virgo.kernel`
`.kernel.startup.wait.limit` | Specifies the amount of time, in seconds, after which various operations time out out while trying to start the kernel. See Configuring OSGi Framework Properties for the recommended way to configure this parameter. | `180`

### Configuration Files

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

Table 13.8. Kernel Configuration Files

Property File | Description
--- | ---
`org.eclipse.virgo.kernel.properties` | Configures deployment.
`org.eclipse.virgo.kernel.userregion.properties` | Configures the User Region of Virgo.
`org.eclipse.virgo.kernel.users.properties` | Configures the users that are allowed to access the Admin Console, and roles to which they map.
`org.eclipse.virgo.kernel.jmxremote.access.properties` | Configures the permissions for users that are allowed to access the Admin Console.
`org.eclipse.virgo.kernel.authentication.config` | Configures the Java Authentication and Authorization Service (JAAS) for the Tomcat server users.
`osgi.console.ssh.properties` | Configures the kernel SSH console. See Section 8.1, “Enabling the Equinox Console”.
`osgi.console.telnet.properties` | Configures the kernel telnet console. See Section 8.1, “Enabling the Equinox Console”.

### Configuring Deployment

You can configure various properties of deployment: the pickup directory into which you copy applications for hot-deployment, the deployment timeout, and whether or not bundles are unpacked during deployment.

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

Table 13.9. Deployment Configuration Properties

Property | Description | Default Value
--- | --- | ---
`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`. | `./pickup`
`deployer.timeout` | Specifies the amount of time, in seconds, after which Virgo times out while trying to deploy an artifact. If you want to disable deployment timeout, specify `0`. | `300`
`deployer.scanIntervalMillis` | Specifies the scan interval, in milliseconds, used to survey the pickup directory. | `1000`
`deployer.unpackBundles` | Determines whether or not bundles (with file extension `.jar` or `.war`) are unpacked during deployment. The value must be either `true` or `false`. If you want to deploy bundles packed, specify `false`. This option can help alleviate a known issue with long work directory paths under Windows. Note that web applications may behave differently depending on whether they are deployed packed or unpacked. Certain servlet API methods return `null` when a web application is deployed packed. | `true`
`WABHeaders` | This kernel property is only relevant for Virgo Nano Web. For the corresponding property in Virgo Server for Apache Tomcat, see Configuring the Web Integration Layer. Specifies how Web Application Bundle manifest headers are processed. See "Web Application Manifest Processing" in the Programmer Guide for details. A value of `strict` causes Virgo Nano Web to interpret certain headers in strict compliance with the OSGi Web Applications specification if they are not specified. A value of `defaulted` causes Virgo Nano Web to set certain headers to default values if they are not specified. This value is provided as a migration aid and may not be supported in future releases. | `strict`

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

    deployer.timeout=300
    deployer.pickupDirectory=pickup
    deployer.scanIntervalMillis=1000

So the default deployment timeout is 300 seconds, the default pickup directory is `$SERVER_HOME/pickup` and the default scan interval is `1000`.

### Configuring the User Region

The User Region is the subsystem of Virgo 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 protects the kernel from interference by applications.

You configure the User Region by updating properties in the `$SERVER_HOME/configuration/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 Virgo to fail. These properties are documented for your information.

Table 13.10. User Region Configuration Properties

Property | Description
--- | ---
`baseBundles` | Specifies the hard-coded list of bundles that Virgo installs directly into the User Region. Virgo 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 Virgo 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 Virgo 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` which would need to be specified separately to be imported). 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.
`serviceImports` | Specifies the services in the kernel that are imported into the User Region so they are available to bundles in the User Region.
`serviceExports` | Specifies 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 Virgo deploys into the User Region when the server starts. Virgo performs dependency satisfaction when it deploys these artifacts. This means that you only need to list the top-level artifacts that you care about; Virgo 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

#### Configurating User Region Consoles

The configuration of the User Region consoles is located by default in the `$SERVER_HOME/repository/ext` directory:

Table 13.11. User Region Console Configuration Files

Property File | Description
--- | ---
`osgi.console.ssh.properties` | Configures the User Region SSH console. See Section 8.1, “Enabling the Equinox Console”.
`osgi.console.telnet.properties` | Configures the User Region telnet console. See Section 8.1, “Enabling the Equinox Console”.

### Configuring Authentication

Virgo 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/configuration/org.eclipse.virgo.kernel.authentication.config` file configures the underlying authentication technology for Virgo. The short file consists of the following entries:

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

The entry named `virgo-kernel` corresponds to the `<Realm>` element in the `$SERVER_HOME/configuration/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 Virgo 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 VTS is `admin/springsource`.

The entry named `equinox_console` controls ssh authentication for the Virgo shell. It also uses the `KernelLoginModule`.

You configure the administration user in the `org.eclipse.virgo.kernel.users.properties` file. The default file for a freshly installed Virgo 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 Virgo after you make this change for it to take effect.

The final file involved in Virgo authentication is `$SERVER_HOME/configuration/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 | Up | Next
13.5 Configuring a Hosted Repository | Home | 13.7 Configuring the Embedded Tomcat Servlet Container