Contents

Introduction

The configuration of osgi-runner itself as well as the configuration of all installed OSGi bundles are in files in osgi-runner's etc directory.

In Windows installations this is the etc/ subdirectory of osgi-runner's installation directory, i.e. usually C:\Program Files\osgi-runner\etc\.

In Linux installations it's /etc/osgi-runner.

osgi-runner's core configuration files can only be edited directly, with a text editor operating on the raw configuration files.

Bundles' configurations are accessible through mechanisms within the OSGi container, therefore we were able to create Web UIs for easier access to bundle configurations. The later chapters of this page explain some availble Web UIs.

Optional (Recommended): Configuring osgi-runner Administration Access

osgi-runner provides several interfaces to maintain it a run-time: An integrated SSH daemon and a web based config manager.

To restrict access to these run-time management features, osgi-runner maintains its own JAAS based authentication service:

The configuration file htpasswd.d/osgi.htpasswd specifies one or more osgi-runner users in the domain osgi, like this snippet from the default configuration shows:

osgi:$apr1$a2pxQc6X$fc.1CQ0UO.rkhXwKXdWeZ.
karaf:$apr1$eQJ1yFFI$q/orCEOYMpcoplIBAxpcg/

The file format is the same format as used by the apache's httpd server and may be maintained according to the informations provided under http://httpd.apache.org/docs/current/programs/htpasswd.html

We very strongly recommend to change the password to something worthy of being called a password, or restrict administrative access vectors by other means (Firewall, ReverseProxy font, ...).

In typical environment the authentication will be changed from JAAS to an auth backend like LDAP/ADS.

Optional: Configuring the embedded SSH Server

As mentioned, osgi-runner comes with an embedded SSH server.

The port and address to listen on can be configured in the configuration file  etc/conf.d/gogo-ssh.properties. The major lines of the default configuration are:

# location of the authorized_keys file
gogo.ssh.etcPath = ${osgi.runner.etcPath}/sshd.d
# port and address to listen on
gogo.ssh.port = 8101
gogo.ssh.host = localhost

There is usually no need for the system administrator to use this SSH server, but our support stuff may need it to investigate problems on a deep level, or to install hotfix updates at run-time.

We strongly recommend not to change the localhost-only default configuration.

We recommend to only allow trusted ssh keys inside the etc/sshd.d/authorized_keys file.

Optional: Configuring the osgi-runner HTTP Port

Our osgi-runner package comes with an integrated HTTP server in the form of the Felix HTTP bundle, based on Jetty (which is unfortunate because it is not as configurable as one might wish). There is also a newer approach org.ops4j.pax.web, but for now we stick with Felix.

Felix' HTTP port is configured in the configuration file adm.d/org.apache.felix.http.cfg which looks like this:

# 8080 is often used by other daemons, so use another port:
org.osgi.service.http.port = 8081

This basic HTTP connector uses clear-text HTTP communication, SSL encrypted HTTPS communication is covered in another chapter below.

Optional: Restricting Remote Access to osgi-runner using a legacy Web Server as Reverse Proxy

Like most J2EE and OSGi engines, osgi-runner provide more web based management interfaces than a security-aware administrator likes to see. There are many known incidents regarding unknown or insecure web interface parts of JBoss, ColdFusion, and others.

Therefore it is common practice to “hide” the application server (in our case osgi-runner) behind a legacy Web server like Apache, IIS, nginx acting as a reverse proxy and to only pass-through known sub URLs.

This approach also makes it easier to provide SSL encryption, and static content like application updates and manuals.

Disallow LAN/WAN access to osgi-runner

There are two approaches to disallow remote access to osgi-runner's HTTP engine, both can be used together:

osgi-runner should only listen on localhost (127.0.0.1), which is achieved by adding the setting org.apache.felix.http.host=127.0.0.1 to org.apache.felix.http.cfg, see also http://felix.apache.org/documentation/subprojects/apache-felix-http-service.html for more configuration options of the embedded HTTP server.

Alternatively, the local firewall should not allow remote access to osgi-runner's HTTP port.

Apache as reverse proxy

For using Apache's modules proxy and proxy_http, these are the appropriate http.conf snippets:

# Foo interface
ProxyPass        /foo-app/ http://localhost:8081/foo-app/
ProxyPassReverse /foo-app/ http://localhost:8081/foo-app/
 
# see application documentation for a list of URL paths to patch through

IIS as reverse proxy

Using IIS as reverse proxy requires additional IIS features to be installed, specifically the Application Request Routing.

There are two ways to install this:

• Using WebPI and http://www.iis.net/downloads/microsoft/application-request-routing

• Manually as explained here: http://blogs.iis.net/wonyoo/archive/2011/04/20/how-to-install-application-request-routing-arr-2-5-without-web-platform-installer-webpi.aspx)

Hints can be found at http://www.iis.net/learn/extensions/url-rewrite-module/reverse-proxy-rule-template and http://www.iis.net/learn/extensions/url-rewrite-module/reverse-proxy-with-url-rewrite-v2-and-application-request-routing. There is obviously no need to setup an example web site.

A complete web.config with a single reverse proxy example looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="ReverseProxyInboundRuleMDAWeb" stopProcessing="true">
          <match url="^foo-app/(.*)" />
          <action type="Rewrite" url="http://localhost:8181/foo-app/{R:1}" />
        </rule>
      </rules>    
    </rewrite>
  </system.webServer>
</configuration>

The application documentation should provide a list of URL paths to patch through.

Tip: Static index.html

Login URLs of Applications, as well as online documentation deep inside WIKIs or other piles of document, are often hard to remember.

Therefore we recommend offer those Links easily accesible in a simple static index.html file in the DocumentRoot of the server. This way the application users only need to remember the server's name, which usually is consistent with the application name (sometimes with postfixes like -test, -version).

Ports Overview for Firewall Configuration

Bundle PIDs

OSGi packages have a uniqe PID (Package ID). The PID usually is the Java package path of the bundle's "root" (top most) Java package.

For example, the HTTP daemon is provided by the Felix HTTP package, whose Java packages all lie in org.apache.felix.http, Therefor it's PID is org.apache.felix.http.

Unfortunately those PID configurations not always created automatically. Sometimes they have to be created manually.

A few moments after the configuration PID is created, packages often fill in default values of major configuration directives.

Therefore, if creating a missing configuration PID, it's a good idea to just reload the configuration after a few seconds, because it saves some delicate steps like creating configuration directives with complicated names.

Performing configuration tasks in the file system

The simpliest approach is to create resp. edit config files using file managers and text editors.

The name of bundle specific configuration files are constructed from each bundle's PID and '.cfg', i.e. org.apache.felix.http.cfg.

Warning about non-english characters

Special characters like German's "Umlaute" have to be encoded Java style, i.e. \u00E4 for ä.

We recommend to use the web based config managers for such cases and let them do the encoding.

Web-based DOJO-Config-Manager

For easier configuration, there is a web based configuration manager provided as part of the osig-runner installation.

Authentication and access restriction

As most web apps, config-managers require the user to identify and authenticate himself.

In osgi-runner they usually authenticate against the embedded JAAS authentication engine, which by default provides an admin user karaf / karaf in the domain osgi.

Our configuration UIs support other configuration mechanisms, but when bootstrapping an installation only JAAS is available.

Therefore access to the web-based config-managers should be restricted using the mechanisms of either a firewall, or a legacy web server acting as reverse proxy in front of osgi-runner, or the config-managers' own configuration.

DOJO-Config-Manager

The DOJO-Config-Manager is our new web based config manager, and part of bundles-pkg resp. osgi-bundles-dojo.

If installed, it is available under /dojo-config-manger, i.e. http://localhost:8081/dojo-config-manager/. 

The DOJO-Config-Managers' own configuration, especially the loginMechanism,  can be configured in the PID org.clazzes.dojo.configmanager resp. the configuration file org.clazzes.dojo.configmanager.cfg.

Hint 1: Do not forget to save

Changes to configuration directives of a configuration PID in DOJO-Config-Manager are not persisted right away.

This allows to arrange a set of tightly coupled configuration directives and save them in one atomic step.

To persist the changes it is required to press the Save-Icon! The Save-Icon looks like a green arrow pointing down to a hard disc.

Hint 2: Mouse-over hints

All buttons provide a mouse over text: If you "park" the mouse pointer over a button, a small explanation of the button's function will pop up.

Recommended: Ironizing the access to dojo-config-manager by using ADS/ldap logins

Configure LDAP Logins

Create and configure the configuration PID org.clazzes.login.ldap, for details see  https://confluence.clazzes.org/display/LOGIN/org.clazzes.login.ldap

After having set up the ADS connection you should be able to sign on the the given ADS domain using the login form given at http://localhost:8081/http-login/org.clazzes.login.ldap/login

Change Access to the OSGi Configuration Console

Configure the configuration PID org.clazzes.dojo.configmanager and change the following settings: