Pax Web can be configured using Configuration Admin or via framework/system properties.

While looking for a configuration property, Pax Web will first use the property configured via Configuration Admin. If the property is not set (present), it will look for a framework/system property with the same name. In the end, if the property is still not present it will use a default value (when applicable).

For cases that requires advanced Jetty configuration read Advanced Jetty Configuration page.

Configuration via OSGi Configuration Admin Service

Pax Web can be configured via Configuration Admin Service (if available) and it supports all properties listed above.
The PID used for configuration is "org.ops4j.pax.web".

Configuration via OSGi framework/system properties properties

Pax Web can be configured via osgi environment properties and it supports all properties from above. Note that according to OSGi specs if a framework property is not set then the framework must fallback to using standard Java System properties (set via vm -D option).

Basic Configuration

The following is a list with basic configuration properties that can be used to customize Pax Web. If not specified otherwise, the property is available since Pax Web - 0.2.0 (first version).

org.osgi.service.http.port

This property specifies the port used for servlets and resources accessible via HTTP. Default value for this property is 8080.
You can specify a value of 0 (zero), if you wish to allow Pax Web to automatically determine a free port to use for HTTP access.

org.osgi.service.http.port.secure

This property specifies the port used for servlets and resources accessible via HTTPS. Default value for this property is 8443.
You can specify a value of 0 (zero), if you wish to allow Pax Web to automatically determine a free port to use for HTTPS access.

org.osgi.service.http.enabled

This property specifies if the HTTP is enabled. If “true” the support for HTTP access will be enabled. If “false” the support for HTTP access will be disabled. Default value is “true”.

org.osgi.service.http.secure.enabled

This property specifies if the HTTPS is enabled. If “true” the support for HTTPS access will be enables. If “false” the support for HTTPS access will be disabled. Default value is “false”.

org.osgi.service.http.useNIO

This property specifies if the connections established use the nio classes from java. If “true” connections are established using NIO, if “false” connections are established the standard way.

javax.servlet.context.tempdir

A temporary directory that can be accessed via the servlet context attribute with the same name. If not set a default temporary directory wil be created and used.

Note
Since Pax Web - 0.2.2.

org.ops4j.pax.web.session.timeout

The number of minutes after which an inactive session will timeout.

Note
Since Pax Web - 0.2.2.

org.ops4j.pax.web.listening.addresses

This property specifies the comma separated list of addresses used to provide servlets and resources via HTTP
(e.g. localhost or localhost,10.0.0.1). Host names or IP addresses can be used. Default value is “0.0.0.0”.

Note
Since Pax Web - 0.5.0.

org.ops4j.pax.web.session.cookie

Session cookie name.
From Jetty documentation:
Defaults to JSESSIONID.

Note
Since Pax Web - 0.6.1.

org.ops4j.pax.web.session.url

Session URL.
From Jetty documentation:
Defaults to jsessionid. If set to null or “none” no URL rewriting will be done

Note
Since Pax Web - 0.6.1.

org.ops4j.pax.web.worker.name

Sets worker name for use with Apache mod_proxy_balancer sticky sessions.
See: http://docs.codehaus.org/display/JETTY/Configuring+mod_proxy
Defaults to null.

Note
Since Pax Web - 0.6.1

org.ops4j.pax.web.config.file

Configures where to look for an external configuration file for the underlying web container (e.g. Jetty).

Note
Since Pax Web - 0.8.0

org.ops4j.pax.web.log.ncsa.format

Sets the format for logging access logs

org.ops4j.pax.web.log.ncsa.format = /yyyy_mm_dd.request.log
Note
Since Pax Web - 1.1.0

org.ops4j.pax.web.log.ncsa.retainDays

org.ops4j.pax.web.log.ncsa.retainDays = 90
Note
Since Pax Web - 1.1.0.

org.ops4j.pax.web.log.ncsa.append

org.ops4j.pax.web.log.ncsa.append = true/false
Note
Since Pax Web - 1.1.0

org.ops4j.pax.web.log.ncsa.extended

org.ops4j.pax.web.log.ncsa.extended = true/false
Note
Since Pax Web - 1.1.0

org.ops4j.pax.web.log.ncsa.LogTimeZone

org.ops4j.pax.web.log.ncsa.LogTimeZone= GMT
Note
Since Pax Web - 1.1.0

Advanced Jetty Configuration

Warning
The following described way of working is only valid starting with version Pax Web - 0.5.2.

To configure advanced features of Jetty you may use jetty xml style configuration files. To make Pax Web aware of your Jety configuration files you will have to use fragments. Be aware that fragment bundles are not yet fully supported on all OSGi implementations!

As an example, it’s shown enabling JMX in Jetty.

To customize Jetty used by Pax Web Service follow instructions:

Create a bundle fragment for Pax Web Service bundle - in manifest put:
Fragment-Host: org.ops4j.pax.web.pax-web-jetty-bundle

for example:

Manifest-Version: 1.0
Fragment-Host: org.ops4j.pax.web.pax-web-jetty-bundle
Bundle-Version: 0.1
Bundle-Name: My Jetty config
Bundle-ManifestVersion: 2
Bundle-SymbolicName: my.jetty_config
Warning
If you are using version Pax Web - 0.6.0 you should use org.ops4j.pax.web.pax-web-service instead of org.ops4j.pax.web.pax-web-jetty-bundle as value of Fragment-Host.
This because starting with version Pax Web - 0.7.0 symbolic name has been changed as we splited Pax Web into more bundles.
Warning
If you are using version the non bundled version of jetty bundle you should use org.ops4j.pax.web.pax-web-jetty instead of org.ops4j.pax.web.pax-web-jetty-bundle as value of Fragment-Host.
Warning
If you are using Pax Web - 0.5.2 you should use org.ops4j.pax.web.service instead of org.ops4j.pax.web.pax-web-service as value of Fragment-Host.
This because starting with version Pax Web - 0.6.0 symbolic name has been changed.
put jetty.xml in root directory of fragment

For example, take a look at a simple example fragment bundle from Pax Web that will add an additional connector on port 8383.

add fragment to your start configuration

If you have logging at DEBUG level enabled, when you start, you should see in logs something like this:

DEBUG  pax.web.service.internal.JettyServerImpl  - starting JettyServerImpl{}
DEBUG  pax.web.service.internal.JettyServerImpl  - configure using bundleresource://100/jetty.xml
Note
Note that the url “bundleresource://100/jetty.xml” from above is just an example as the url is framework specific
Adding specialized ContextHandlers

If you want to add specialized ContextHandlers to the jetty server you have to be
careful not to break the way Pax Web works. So Instead of defining a new
Collection of Handlers in the jetty.xml you need to add your specialized ContextHandler to the
existing Collection.

Here is an example where the jetty Default Servlet is used to
server static content from the file system.

     <Get name="handler">
        <Call name="addHandler">
          <Arg>
     <New class="org.eclipse.jetty.servlet.ServletContextHandler">
              <Set name="contextPath">/app</Set>
              <Set name="resourceBase">/path/to/your/share</Set>
              <Call name="addServlet">
                <Arg>org.eclipse.jetty.servlet.DefaultServlet</Arg>
                <Arg>/</Arg>
              </Call>
            </New>
          </Arg>
        </Call>
    </Get>
using external jetty.xml file
Warning
The following described way of working is only valid starting with version Pax Web - 1.0.0.

An external located jetty.xml file can be used for configuration of Pax Web.
This can be activated by setting the following property for Pax Web

org.ops4j.pax.web.config.file=<FILE-IN-FILESYSTEM>

For more details on how to configure the Jetty Server take a look at the official jetty.xml config page

SSL Configuration

Pax Web supports SSL (https) via Jetty built in SSL support. To get used with Jetty support you may read How to configure SSL in Jetty and skip step 4 from that page, as the configuration part must be done in Pax Web specific way.

To enable SSL support you must set the following properties:

  • org.osgi.service.http.secure.enabled to true

  • org.ops4j.pax.web.ssl.keystore to the path to the keystore to be used. If not set the default path ${user.home}/.keystore is used.

  • org.ops4j.pax.web.ssl.password to the password used for keystore integrity check. The value can be in plain text or obfuscated ( starting with OBF: ) as described in step 4 of jetty docummentation

  • org.ops4j.pax.web.ssl.keypassword to the password used for keystore. The value can be in plain text or obfuscated ( starting with OBF: ) as described in step 4 of jetty docummentation

You may also set the following:

  • org.osgi.service.http.port.secure to change the port. Default is 8443.

The following is a list with SSL related configuration properties that can be used to customize Pax Web SSL support. If not specified otherwise, the property is available since Pax Web - 0.2.0 (first version).

org.ops4j.pax.web.ssl.keystore

Path to the keystore file. See ops4j:SSL Configuration for details.

Note
Since Pax Web - 0.2.1.

org.ops4j.pax.web.ssl.keystore.type

This property specifies the keystore type. Defaults to JKS.

Note
Since Pax Web - 0.5.0

org.ops4j.pax.web.ssl.password

Password used for keystore integrity check.

Note
Since Pax Web - 0.2.1

org.ops4j.pax.web.ssl.keypassword

Password used for keystore.

Note
Since Pax Web - 0.2.1

org.ops4j.pax.web.ssl.clientauthwanted

This property specifies, if certificate-based client authentication at the server is “wanted”.

Note
Since Pax Web - 0.5.0

org.ops4j.pax.web.ssl.clientauthneeded

This property specifies, if certificate-based client authentication at the server is “required”.

Note
Since Pax Web - 0.5.0

JSP Configuration

The following is a list with extra configuration properties for JSP compilation, these can be used to customize Pax Web. If not specified otherwise, the property is available since Pax Web - 1.0.0.
These properties are send to the underlying JSP servlet Container see

The default configuration used can be seen via the MetaTypeService or in the metatype.xml of the runtime bundle.

org.ops4j.pax.web.jsp.scratch.dir

This property defines the Directory where servlets are generated.

org.ops4j.pax.web.jsp.check.interval

Interval in seconds between background recompile checks. Only relevant if org.ops4j.pax.web.jsp.development=false.

org.ops4j.pax.web.jsp.debug.info

Include debugging info in class file.

org.ops4j.pax.web.jsp.development

If true, recompilation checks are made on each request.

org.ops4j.pax.web.jsp.enable.pooling

Determines whether tag handler pooling is enabled.

org.ops4j.pax.web.jsp.ie.classid

Classid used for InternetExplorer

org.ops4j.pax.web.jsp.java.encoding

Pass through the encoding to use for the compilation.

org.ops4j.pax.web.jsp.keep.generated

Do you want to keep the generated Java files around?

org.ops4j.pax.web.jsp.log.verbosity.level

Log verbosity level used.

org.ops4j.pax.web.jsp.mapped.file

Support for mapped Files. Generates a servlet that has a print statement per line of the jsp file.

org.ops4j.pax.web.jsp.tagpool.max.size

Maximum size for tags in pool.

org.ops4j.pax.web.jsp.precompilation

If jsps should be precompiled (see for more detailse here

Note
Since Pax Web - 2.0.0