Server configuration

version 7.1
feedback: 2step@zentense.com

This document describes the configurations options of 2step built-in server (a subset of Jetty 6.1). Jetty is a very complete server and some of the options (JSP support, filters, etc) have been removed from the version included in 2step. If you need them you may also use a complete and newer Jetty version or any other servlet engine, as Tomcat.

1. Starting and stopping server
2. Package contents
3. Configuration file
3.1. Listeners sections
3.1.1. HTTP server
3.1.2. HTTPS server
3.1.3. AJP 1.3 server
3.2. Options sections
3.3. Contexts section
3.3.1. Default context
3.3.2. User defined contexts
4. Context samples

1. Starting and stopping server

Just execute startup.jar and shutdown.jar to start and stop server. On Windows just double-click on the icon. For executing a jar from command-line do java -jar startup.jar from the STEP_HOME directory (directory where you uncompressed 2step package). By default server runs on port 8080.

When starting server you can use these options:

java [-DDEBUG] -jar startup.jar [stdout] [<config_file>]

-DDEBUG activates debug output
stdout disables writing standard output and error to logs/jetty.out
<config_file> loads a different configuration file. By default 2stepserver.conf is read.

For stopping server:

java -jar shutdown.jar [<port>]

By default server listening at port specified in configuration file is shut down, but another one can be specified as an argument.

2. Package contents

Into STEP_HOME directory you will find these contents:

2stepserver.conf: Configuration file
docs: 2step documentation is here
lib: All the libraries used by 2step are in this directory
logs: Server logs are stored here. In jetty.out you will find server standard output and error and some errors are shown in this file. In this directory access logs for each context are also stored.
ext: Any JAR in this directory will be loaded and available to all contexts.
webapps: Default web applications directory.

3. Configuration file

In the configuration file all the default options are commented. If you uncomment them nothing happens because is the default.

Configuration file is divided intro three different sections: listeners, options and contexts. Let's see them in detail:

3.1. Listeners sections

Jetty features three different listeners: one for HTTP, other for HTTPS supporting secure connections. These listeners are for serving web pages. There is a third listener for AJP (Apache JServ Protocol) that allows communicate Jetty with different web servers as Apache or IIS.

3.1.1. HTTP server

The property http.enabled enables or disables the listener, while the property http.port tells which port the HTTP server is listening to. By default HTTP listener is enabled on port 8080.

3.1.2. HTTPS server

The property https.enabled enables or disables this listner, while the property https.port tells which port the HTTP server is listening to. By default HTTPS listener is disabled and its default port is 8443. The property https.needclientauth tells if a secure certificate is requested to authenticate clients. By default this option is disabled.

For configuring the server certificates use the Java keystore tool as documented here.

3.1.3. AJP 1.3 server

The property ajp.enabled enables or disables the listener, while the property ajp.port tells which port the AJP server is listening to. By default AJP listener is enabled on port 8009.

3.2. Options sections

In this section some global options are set up:

web.root: By default '.'. This is the path of the web root for the default context.

java.home: No default. Path to Java SDK. Usually 2step administration is able to locate Java compiler if it is installed, but you can override default detection with this option.

logs.enabled: Default 'true'. Tells if accessed logs are written.

logs.dir: Default 'logs'. Path to logs directory.

manager.enabled: Default 'true'. Enables the context manager on default context. Notice that if manager is disabled on default context shutdown will not work. You can access manager on /manager URI.

manager.password: Default 'manager'. Sets the password for context manager. The user is 'admin'.

webapp.dir: Default 'webapps'. Path to default directory where find web applications.

check.file.aliases: Default 'true'. If enabled, soft links are not allowed on web spaces.

3.3. Contexts section

A context is a directory on the web space (URI) of localhost that is mapped to a directory on the server file system (web root) for serving HTTP requests, and that may have a 2step application mapped to another directory on the web space (web application URI).

You can define as many contexts as you wish but remember that a given host and URI can be only mapped to a unique context

3.3.1. Default context

There is always at least one context served by the server, the default context whose URI is '/'. Default context cannot contain web applications!

With the default configuration file, the default context can be accessed through http://localhost:8080/ and it maps to directory docs, and the context manager can be accessed through http://localhost:8080/manager.

3.3.2. User defined contexts

You can define as many context as you wish, always respecting that each context cannot have the same host and URI than another one. User defined contexts are identified by a name. In the property contexts you can add as many context names as you wish, separated by comma.

For each context there are some properties. All of them are optional but usually you will need to define at least the host or the uri if you don't want conflicts between diferents contexts. The properties are:

<name>.host: Default 'localhost'. This tells which is the host where this context is mapped to.

<name>.root: Default '.'. This tells which is the directory in the file system that will act as the web root for this context.

<name>.uri: Default '/'. This tells which is the URI in the webspace where this context is mapped to. This property always begins with '/'

<name>.webapp.uri: Default '/*'. This tells which is the URI relative to this context URI where the 2step application is mapped to. This property always ends with '/*'. When you browse to this URI, it is not answered by the web server but by the corresponding 2step application.

<name>.webapp.root: No default. Defines a different 2step application root directory different than defined in the property webapps.dir.

<name>.alias: No default. Comma-separated lists of hosts that are aliases of this context. This way the same context can be accessed from different hosts.

<name>.session.timeout: Default '1800'. Number of seconds of inactivity before an active session to be finished. This only has effect if there is a web application contained in this context.
<name>.manager.enabled: Default 'false'. Enables manager on this context, on URI /manager. Useful for accessing context manager remotely.

<name>.2step: Default 'lib/2stepcore.jar'. Path to 2step runtime library. Useful for having different 2step versions in the same server. This only has effect if there is a web application contained in this context.

<name>.initOnStartup: No default. By default web applications are initialized the first time they are accessed. If this property is defined it must contain a number that defines the priority when initializing web applications at server startup. Lower is earlier. This only has effect if there is a web application contained in this context.

<name>.use.session.cookies: Default 'true'. If set to false, session cookies are never sent and session information is kept through URL rewriting. This only has effect if there is a web application contained in this context.

<name>.access: No default. This property contains a comma separated list of items of the form: user=password. Contexts are public, but if you define this property HTTP server will request authentication and only the users and passwords given here will be allowed to go further.

<name>.welcome: Default 'index.html'. This is the welcome page to show when none is specified.

<name>.welcome.redirect: Default 'false'. When true, a request is redirected to welcome page, or forwarded otherwise, when welcome page is needed to be shown.

<name>.kaptcha.enabled: Default 'false'. When true CAPTCHAs are generated in <uri>/kaptcha.

<name>.kaptcha.length: Default '4'. Number of characters in kaptcha.

4. Context samples

Suppose the next context named test:

test.root= /www/myweb
test.uri=/myweb

This creates a context with no web application that can be accessed through http://localhost:8080/myweb and maps to directory /www/myweb. Notice that coing to default context at http://localhost:8080 would continue to show the same as before.

Now look at another definition of test:

test.root= /www/myweb
test.uri=/myweb
test.webapp.uri=/*

Now server will try to load the application named test into the default webapps.dir. Supposing that it would exist, going to http://localhost:8080/myweb will show the test application instead of the web root. This context is fully mapped to the web application.

Another one:

test.root= /www/myweb
test.uri=/myweb
test.webapp.uri=/webapp/*

Now going to http://localhost:8080/myweb will show the web root as in the first sample, and going to http://localhost:8080/myweb/webapp will show the web application.

test.root= /www/myweb
test.uri=/myweb
test.webapp.uri=/webapp/*
test.host=www.myweb.org

Now localhost is not the host for this context anymore, but www.myweb.org. This context can only be accessed through http://www.myweb.org:8080/myweb

test.root= /www/myweb
test.uri=/myweb
test.webapp.uri=/webapp/*
test.host=www.myweb.org
test.alias= myweb.org, www.myweb.com

Now context can be accessed through diferent localhost. http://www.myweb.org:8080/myweb, http://myweb.org:8080/myweb and http://www.myweb.com:8080/myweb get the same request from server.

Generated on Tue 14 16:01:12 CEST
	2step 7.1.46 © 2008 Zentense S.L.