iKnowBase web server | ||
---|---|---|
Previous | Next | |
Apache Solr Search Server | Installing on Oracle WebLogic Server |
NOTE: This chapter assumes the iKnowBase database repository has been created, as outlined in Quick Installation and upgrade overview .
iKnowBase comes with an embedded web server based on the Eclipse Jetty server. This is a fast and capable server which requires little resources and is very easy to manager. This is the recommended web server for most installations.
Verify / review the recommended installation structure outlined in Quick Installation and upgrade overview .
If you’ve not already done so, set up the iKnowBase instance configuration file described in outlined in Quick Installation and upgrade overview .
For the examples further down we assume you’ve used the configuration file name
production.properties
for a configuration named “production”.
With this configuration, you should be able to easily run and test the applications:
cd /opt/iknowbase/production
./iknowbase.sh production.properties webServer
Start a web-browser, and navigate to http://YOUR_SERVER_NAME:8080/ressurs/iknowbase (to see documentation), http://YOUR_SERVER_NAME:8080/index.html (for the viewer application), or http://YOUR_SERVER_NAME:8080/ikbStudio (for the Development Studio). The first two should open immediately, while the second one will require login, which requires configuration as shown below.
Using the iKnowBase web server, application deployments is specified in the same property file as all other configuration.
The iKnowBase program contains a default configuration that automatically deploys the applications: /ressurs, /. If this is what you want, you don’t have to make any changes or configure any deployments.
If you want to customize the deployment, start by specifying which applications to deploy. The names are only used internally to the property file, but pick names that are easy to understand:
# Web server configuration
web.apps=webRessurs,webIkbWebApp
NOTE that webIkbWebApp is by default deployed to context root / and MUST be listed as the last application in the web.apps property.
Next, add two entries for each application. First add an entry for the application path, which is where the application will be mounted. Next add an entry for the application WAR-file, which is where the application itself is located (can be a war file or a directory containing war contents / exploded war). These entries will be the name of the application, followed by “.path” and “.war” respectively:
# Web server configuration
web.apps=webRessurs,webIkbWebApp
# Web application definitions
webRessurs.path=/ressurs
webRessurs.war=iknowbase-resources-7.0.4.war
webIkbWebApp.path=/
webIkbWebApp.war=iknowbase-webapp-7.0.4.war
Often, you will want to add custom deployment, such as a your own resources (images, scripts, etc). This is done the exact same way, but note that the file-property is here used to point to a directory:
# Web server configuration
web.apps=webRessurs,webCustomResource,webIkbWebApp
# Web application definitions
webRessurs.path=/ressurs
webRessurs.war=iknowbase-resources-7.0.4.war
webIkbWebApp.path=/
webIkbWebApp.war=iknowbase-webapp-7.0.4.war
webCustomResource.path=/custom-resources
webCustomResource.war=/opt/iknowbase/production/custom-resources
As you can see in the examples, you can change the url mount point at will. Note that the iKnowBase web server will visit the mount points in the order they appear in the
web.apps
property, and that having the wrong order is important. Look at the partial example below:
web.apps=root,ressurs
root.path=/
ressurs.path=/ressurs
If a client asks for “/ressurs”, this will be captured by the application “root”, and served from there. Therefore, remember to set the longest paths to the beginning of the “web.apps” definition.
It will sometimes be required to have multiple applications deployed towards different hosts, for example to mount WebDAV at root of “webdav” and “webdav.example.com” and Viewer at the root of all other servers. This can be handled by defined virtual hosts for the required applications:
web.apps=webIkbWebApp,webIkbWebdav
webIkbWebApp.path=/
webIkbWebApp.war=iknowbase-viewer-webapp-7.0.4.war
webCustomResource.path=/custom-resources
webCustomResource.war=/opt/iknowbase/production/custom-resources
webCustomResource.vhosts=custom-resource.example.org, custom-resource
In the example below, when a client asks for “http://custom-resource/” or “http://custom-resource.example.org”, the request will be served by the webCustomResource application. Root requests to all other hosts (such as http://intranet.example.org or http://testserver.example.org) are handled by the iknowbase-webapp application, which has no particular host name affinity.
The recommended sequence for configuration is to first set up iKnowBase using the internal user directory, and verify sure that you have access to the iKnowBase web applications. After that, you can change to any supported authentication setting you want, but with the knowledge that iKnowBase does indeed work properly with a simple login service.
See iKnowBase Installation Guide > Web Application Security for additional explanations.
We strongly recommend using SSL (https) for all production sites.
If you terminate SSL in an external proxy, that proxy will typically use HTTP (an unsecured connection) to talk to the application server. Then, the application server will not be aware that the browser sees a secure connection, and will by default generate links to an unsecure site. To avoid this, note the following items:
If using Apache httpd for ssl-termination, the following configuration in httpd.conf should set the required header:
<Virtualhost ...>
...
RequestHeader set X-Forwarded-Proto "https"
...
</Virtualhost>
To configure the iKnowBase web server, set the property
web.honorXForwardedHeaders
in the property file:
...
web.honorXForwardedHeaders=true
...
The iKnowBase web server can be configured to listen for HTTPS traffic with the following options:
...
web.ssl.port=8443
web.ssl.keyStorePath=iknowbase.keystore
web.ssl.keyStorePassword=<KEYSTORE_PASSWORD>
web.ssl.certAlias=<Optional certificate alias>
...
The iknowbase.keystore is a standard java keystore in JKS format generated by Java keytool.
The following example demonstrates generating the iknowbase.keystore using preexisting private key, a server certificate and a CA chain file.
$ sudo openssl pkcs12 -inkey ./www_example_com.key -in ./www_example_com.crt -certfile ./ca_chain_file.crt -export -out ./www_example_com.pkcs12 -passout pass:<KEYSTORE_PASSWORD>
$ $JAVA_HOME/bin/keytool -keystore ./iknowbase.keystore -storepass <KEYSTORE_PASSWORD> -importkeystore -srckeystore ./www_example_com.pkcs12 -srcstoretype PKCS12 -srcstorepass <KEYSTORE_PASSWORD>
Support for multiple certificates is as simple as repeating the previous step for the next certificate and importing into the same keystore.
By default, the iKnowBase web server separates session between different domains, so that a user that opens both http://www.example.com and http://intranet.example.com will have to log on to each of these sites. Technically, this is done by using different “session cookie domains” for the session cookie for each of these hosts.
Sometimes, it is desirable to share the session information between sites. To do that, configure the session cookie domain to be used by the server. It is important that this domain is the parent domain of the various hosts used, for example, to share the login session between http://www.example.com and http://intranett.example.com you must specify “example.com”; to share the login session between http://www.iknowbase.com and http://customers.iknowbase.com you must specify “iknowbase.com”.
Note also that specifying a sesision cookie domain means that a single iKnowBase web server can only serve sites belonging to that domain. If you specify a session cookie domain of iknowbase.com means that the same server may no longer serve content from example.com. If you need this scenario, for example to serve http://www.example.com, http://intranett.example.com and http://www.iknowbase.com from the same iKnowBase repository, use two iKnowBase web servers (one for *.example.com and one for *.iknowbase.com) listening at different ports, and use a proxy server (such as Varnish or Apache Traffic Server) to direct requests appropriately.
...
web.sessionCookieDomain=example.com
...
By default, the iKnowBase web server will use session cookie name
JSESSIONID_<web application name>
, e.g.
JSESSIONID_WEBIKBWEBAPP
. In case of session name collision you may change the application name or just change the session cookie name. Session cookie name can be set using:
...
# Change the session cookie to "JSESSIONID_CUSTOM_NAME" for web application "webIkbWebApp"
webIkbWebApp.sessionCookieName=JSESSIONID_CUSTOM_NAME
...
During normal execution, the iKnowBase web server needs a directory for storing working files. This directory will be used for e.g. unpacking the web application war files, where each deployed application will get its own subdirectory under the work directory (such as “work/webapps/webIkbWebApp”). The default work directory is “./work” under the current directory, but this can be overridden in the iknowbase property file:
...
iknowbase.workDirectory=/vol/workfiles/iknowbase/prod-server
...
Note that it is not recommended to use the operating system temporary directory (/tmp) for this purpose. For example, Linux installations typically runs the program “tmpwatch” every day, cleaning up the /tmp directory.
The iKnowBase programs writes logfiles during execution, both for command line and web usage. By default, the logfile is written in a subdirectory “logs” under the work directory (i.e. “./work/logs”), but you can override this in the property file:
...
iknowbase.logDirectory=/var/log/iknowbase
...
Max form size that can be submitted to the iKnowBase web server is by default set to 200 000 bytes. This is inteded to help in denial of service attack scenarios where malicious clients send huge amount of data. This limitation does NOT affect file uploads using
multipart/form-data
.
If you need to POST forms larger than 200 000 bytes override the max value per web application in the iknowbase property file:
...
[webAppName].formContentSize=200000
# webIkbWebApp.formContentSize=200000
...
When accessing a database through a firewall or on an unreliable network, use the Oracle Net connection descriptor syntax with ENABLE=BROKEN instead of the standard JDBC URL syntax as the database connection string.
Default JDBC URL:
jdbc:oracle:thin:@//localhost:1521/ORCL
Using Oracle Net connection descriptor syntax:
jdbc:oracle:thin:@(DESCRIPTION = (ENABLE = BROKEN)(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521)))(CONNECT_DATA =(SERVER = DEDICATED)(SERVICE_NAME = ORCL)(FAILOVER_MODE =(TYPE = SESSION)(METHOD = BASIC))))
See Setting max form size.
You may encounter a session cookie collision if you
As the host name is the same for both requests, the session cookie name will by default be valid for both requests. The session cookie is only valid on one server, which will result in a replaced session cookie and effective log out the authenticated user.
Resolve the issue by changing the session cookie name for one of the applications or use different hostnames for accessing the applications.
iKnowBase 7.0 upgraded the embedded web server Jetty from 9.2 to 9.3, which uses updated HTTP specifications.
SEE:
Header parse error after upgrade to Jetty 9.3
for details.
bc..
"Jetty 9.2 followed RFC2616 (Now Obsoleted by: RFC7230, RFC7231, RFC7232, RFC7233, RFC7234, RFC7235 and Updated by: RFC2817, RFC5785, RFC6266, RFC6585)
Jetty 9.3 follows the updates to the venerable (from 1999!) RFC2616 spec. Many things that were valid in the past are no longer valid. We also dropped support for HTTP/0.9 in Jetty 9.3"
This update should not affect end user clients, but it might affect systems requesting information from iKnowBase over HTTP. The systems need to adjust to follow updated HTTP specs.
Previous | Top | Next |
Apache Solr Search Server | Installing on Oracle WebLogic Server |