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.
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.
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.
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.
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.
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.
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 |
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.
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
).
If a Firewall is used (recommended) these are the common ports of our osgi-runner installations.
We usually open these ports to the network:
80
, for a minimal web host redirecting to the https counterpart
443
, for a web host acting as reverse proxy to the MDA server
Windows: 3389
, remote desktop, for maintenance of Windows hosts, restricted to trusted hosts or networks
22
, ssh, DOS-protected by fail2banWe usually do not open these ports:
8080
or 8081
or other, osgi-runner HTTP server port
8101
, osgi-runner SSH server port
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.
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
.
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.
For easier configuration, there is a web based configuration manager provided as part of the osig-runner installation.
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.
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
.
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.
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.
Create and configure the configuration PID org.clazzes.login.ldap, for details see https://confluence.clazzes.org/display/LOGIN/org.clazzes.login.ldap
Key | Value | Remarks |
---|---|---|
defaultDomain | DOMAIN | Replace DOMAIN by your Windows domain name. |
domain.DOMAIN.controllerUri | ads://domain.top | Lookup of LDAP server in DNS via _ldap._tcp SRV entries, adapt to your DNS domain name, replace DOMAIN in key name by your Windows domain name. |
domain.DOMAIN.authMethod | bindAds | Bind to LDAP using ADS conventions, replace DOMAIN in key name by your Windows domain name. |
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
Configure the configuration PID org.clazzes.dojo.configmanager and change the following settings:
Key | Value | Remarks |
---|---|---|
loginMechanism | org.clazzes.login.ldap | Change to the above configured login adapter |
allowedUser.2 | DOMAIN/<myuser> | <myuser> is the Windows logon name of an allowed user. Once LDAP access is working, you may also overwrite the allowedUser.1 entry. Replace DOMAIN by your Windows domain name. |
allowedUser.3, AllowedUser.4,... | DOMAIN/<yetanotheruser> | You may add additional entries allowedUser.3, AllowedUser.4,... |