Introduction

Ceptor (previously PortalProtect) is a security solution that protects portals and application servers, regardless of the communication type used, be it REST services, SOAP, JSP, Servlets, EJB, Web or other types of communication. Ceptor can provide Authentication and Authorization checking on all resources, as well as provide secure communication between clients and servers.
Any number of web servers, application servers or other types of servers can be integrated, and used to create personalized content and session sharing between all applications, so users experience single sign-on with access (depending on authorization of course) to all applications available in your portal.

Installation

Standalone

Installation can be done in a number of ways, you can unzip the .zip file distribution to any directory and just launch Ceptor using the launcher scripts in the bin directory, or you can install using one of the platform installers which provides a better integration with your platform (e.g. Windows Start Menu), and installs as a Windows or Unix service.

Linux

For Linux, be aware of default limits for file handles or processes/threads - see Linux Troubleshooting for more details.

Docker

For information about Ceptor and Docker, please read: Running Ceptor in Docker

Directories

The Ceptor distribution contains the following files and directories:

• licenses
  Contains license information about Ceptor, and the open source libraries used by parts of Ceptor.
• documentation
  Contains documentation about using various parts of Ceptor - note that this directory no longer contains complete documentation, but only API documentation, Javadoc etc. - refer to the online documentation for full documentation.
• bin
  Binary files - contains a bootstrap loader that starts a Ceptor server or Ceptor Dispatcher/Gateway instance. The classpath will be set to the following directories, in the listed order: classes, patches*.jar, lib*.jar, extlib*.jar, plugins*.jar
• classes
  Classes directory placed first in classpath - contains configuration files for logback - here you can enable/disable logging for specific classes or you can redirect logging to other locations.
• patches
  Here, any eventual patches for specific bugfixes can be stored, any .jar files in this directory are loaded before the rest.
• lib
  Contains Ceptor .jar files.
• extlib
  External libraries, such as logback / log4j. See licences/readme.txt for a list of files and for the license information for each.
• extlib_extras
  Additional external libraries, these are not added to the classpath by default, but can be added by specifying the extraclasspath attribute on classloader definitions in the launcher XML file.
• plugins
  Place your own Ceptor plugins in this directory.
• config
  Contains configuration for Ceptor servers, and startup scripts used by the bootloader to launch Ceptor server instances.
  Contains the following files and subdirectories:
  • ceptor-security.xml
    List of users, groups and access rights for the Ceptor Console.
  • ceptor-configuration.xml
    Main Ceptor server configuration - contains configuration used by all modules.
  • ceptor_launch.xml
    Launcher configuration used by the bootstrapper to start a Ceptor Server instance.
  • configuration-backup
    Backup of the configuration will be stored here, whenever changes are made via the administration interface.
  • eticket
    Contains certificates and samples for using eticket / NetID.
  • filelogin
    Files for specifying ACLs to applications, users' group and protected URLs, used by the sample authorization plugin, other plugins might use other datastores.
  • users
    Sample users used by the sample authentication plugin - typically used for development/testing when a database or other user datastore is not available.
  • x509
    Contains various certificates and sample keys for OCES Digital Signature and DanID / NemID integration.
  • xdomain
    Sample key files for cross-domain session sharing.
• ppserver
  Contains resources used by the Ceptor server, such as web apps for the Administration interface (images, stylesheets etc.), user administration and webapp/configuration for the web services interface to Ceptor.
  • console
    Ceptor Console runtime  and web application files.
  • developerportal
    Ceptor Developer Portal runtime and web application files.
  • useradmin
    User administration web application runtime files.
  • webserviceswebapp
    The webapp folder for the web services webapp if launched
• dispatcher
  Contains resources used by the dispatcher, e.g. key file containing SSL server certificate.
• gateway
  Contains additional libraries used by the Ceptor gateway. 
• auth
  Contains static html/javascript resources for an authentication application that uses the CeptorAuthenticate API to authenticate, self-register or reset password for endusers. Please see Create an Authentication Application within Ceptor Gateway for more information.
• logs
  Log files are generated and stored here.
• samples
  Sample configurations, database scripts etc.
  Samples have the following subdirectories:
  • integration
    Contains the agents for various application servers, as well as the .NET Agent and sample IIS application.
  • demoapp
    Sample demonstration application that uses many Ceptor APIs and demonstrates how to utilize these APIs in your own applications, e.g. it contains samples for authentication users in various ways using userid/password, x.509 certificates, oces applets etc. Source code for the sample application is included.
    Important: The demo app requires a full java JDK to be installed in order to work – it will not work with the JRE bundled with Ceptor. Oracle's license prevents us from bundling the JDK, so you will need to download that from oracle.
  • database
    Contains database creating SQL scripts and scripts for inserting test data for the various supported databases used by the Identity Manager / UserAdministration component.
  • configuration
    Contains various snippets of the configuration used to demonstrate e.g. cluster setup, or how to add a generic .war file to the Ceptor services launcher.
• statistics
  Statistics stored in the statistics server are stored here.
• testdatabase
  Test cloudscape databases used by the sample configuration for user administration. Contains users, groups, acls, organisations etc.
  The sample configuration will also put the API management database in this folder.
• useradminapp
  User Administration application (thick java client), communicates with useradmin server which uses the database located in testdatabase to administer users.
• temp
  Temporary directory, used for cache files etc.
• jcepolicy
  Unrestricted JCE Policy files, for use with Oracles JDK

Patching

Patching Ceptor is relatively easy, it is just a matter of placing the patch .jar files in the patch subdirectory and restarting the servers – then PP will use the classes in the patched .jar files.

Upgrading

When upgrading an existing installation, you can elect to just install/unzip the .jar files and documentation and keep your existing config directory intact. Make sure you have a current backup of your config directory before installing.
Also, make sure to delete any files in the patch directory, unless specifically instructed otherwise, since the new release will contain the fixes itself, and the files in the patch directory might be out of date.

Migrating from Ceptor 6.x to 6.4

With Ceptor version 6.4, Ceptor's .jar files have been renamed from PortalProtect*.jar to Ceptor*.jar - this affects CeptorAgent.jar too, which means that you need to rename from PortalProtectAgent.jar to CeptorAgent.jar where you reference this in your launcher configuration files.
Note that when installling using Ceptor's installer, it will do the renaming in the standard launcher files - if you are using custom files, you will need to do this renaming manually.

Migrating from Ceptor 5.x to 6.x

With Ceptor version 6, default configuration files have been renamed from pp_launch.xml to ceptor_launch.xml, and from portalprotect-configuration.xml/portalprotect-security.xml to ceptor-configuration.xml/ceptor-security.xml

Existing files will still work, but you should rename yours as well.

Licenses

The default evaluation has a trial license located in the licenses directory in the file ceptor_license.txt. Ceptor also uses a number of Open Source products, a description of each and their license is located in the licenses subdirectory. Look within readme.txt for more information.
When you purchase Ceptor, you will be issued with a license specific to your company that replaces the trial license included in the installation distribution.

Starting the Servers

Depending on your platform, and the way you installed PotalProtect, there is a number of ways to start Ceptor, the preferred form should be a Windows or Unix service. You can also start Ceptor directly, by using one of the launchers in the bin directory.
Ceptor usually consists of at least two servers, one for the Gateway or Dispatcher (typically located in a DMZ zone) and another for the Ceptor server itself, which contains the configuration server, session controller, logserver, statistics server etc. But all these services can optionally be split out into individual JVMs or even physical machines as you wish.
When you start Ceptor, by default it listens on a number of ports for browser requests.

4080 / 4443
Used by the Dispatcher, the dispatcher forwards requests to an application which by default is expected to be on port 8080. Look at samples/demoapp – it contains a test application that can be started on port 8080, and demonstrates the usage of many Ceptor APIs.

8000 / 8443
Used by Gateway - the gateway is a reverse proxy replacement for the dispatcher, rewritten to support newest communication protocol and a different more modern configuration concept - see Ceptor Gateway for more information.

4242 / 4243
Used by Ceptor Console - point your browser to http://localhost:4242 or https://localhost:4243 to view the console.
By default, two users exist:

Username 1: admin - Administrator with read/write access to everything
Password 1: password

Username 2: readonly - Read-only user, read-access to everything
Password 2: password

See more information here: Ceptor Console

4244 / 4245
Used by the old, now deprecated administration interface - Ceptor Console replace this, so you should no longer use it - it will be removed in a future version. 

4343 / 4344
Used by User administration Interface - point your browser to http://localhost:4343_ or _https://localhost:4244_ to log in with an existing user. By default no users will exist and you can use http://localhost:4343/adminlogin _to login with the default configured user:

Username: admin - Administrator with read/write access to everything and all users
Password: password

4300 / 4301
The webservices server listens for requests for web services on these ports, 4300 for HTTP and 4301 for HTTPS. Point your browser to http://localhost:4300 for more information.

4400
The HTTP Proxy server listens for requests on this port. You can configure your browser to use <servername>:4400 as HTTP proxy server to test it out.

4848 / 4843
The HTTP and HTTPS ports for direct access to the developer portal as defined in the sample configuration. The developer portal can also be access through the Gateway on port 8443 using /developerportal.

Modifying Services Launcher

The service launcher works by running java –jar bin/boot.jar
It supports these parameters:

Usage: [arguments] <xml launcher filename>
Where arguments are:
 -status                      Print status information.
 -shutdown                    Shutdown any running services / JVMs.
 -restartall                  Asks the running server to shutdown and then
                              re-read launcher xml file and start again.
 -stopjvm <jvmname>           Asks the running server to stop a JVM.
 -startjvm <jvmname>          Asks the running server to start a JVM.
 -restartjvm <jvmname>        Asks the running server to restart a JVM.
 -quiet                       Limit information written to stdout.
 -services <service list>     Start only the listed services (Default: all).
 -jvms <jvm list>             Start only the listed jvms (Default: all).
 -sharedclassloader           Use shared classloader for all services.
 -separateclassloader         Force separate classloader for each service.
 -systemclassloader           Assume all classes are in system classpath.
 -excludeclasses              Do not include the classes directory in classpath.
 -pphome <homedir>            Specify Ceptor home directory.
 -ceptorhome <homedir>        Same as -pphome.
 -java <java launcher path>   Path to java.exe for launching new JVMs.
 -debugclasspath              Print classpath for debugging purposes.
 -standalone                  Do not start new processes, but launch services
                              directly in the current process instead.
Examples:
 java -jar /pp/bin/boot.jar -pphome /pp /pp/config/ceptor_launch.xml
 java -jar /pp/bin/boot.jar -pphome /pp /pp/config/ceptor_launch.xml -status
 java -jar /pp/bin/boot.jar -pphome /pp /pp/config/ceptor_launch.xml -shutdown

Standalone or Distributed

The launcher can operate in 2 modes, either standalone or distributed.
If operating in standalone mode, all services specified in the launcher xml file are launched within the same JVM process – but when running in distributed mode, it will spawn child processes and each process will load the services defined for it – this is a great and easy way of splitting Ceptor components into multiple processes, e.g. running configuration server and statisticsserver in one JVM, and running session controllers or multiple clusters of session controllers each in their own JVM.
Note that –status, -startjvm, -stopjvm, -restartjvm and –shutdown only works on JVMs which do not run in standalone mode.

Starting / stopping individual JVMs in distributed mode

Starting with version 5.60, it is now possible to start/stop individual JVMs, here, these are the relevant options:

 -status Print status information.
 -stopjvm <jvmname> Asks the running server to stop a JVM.
 -startjvm <jvmname> Asks the running server to start a JVM.
 -restartjvm <jvmname> Asks the running server to restart a JVM.

• -status
  Prints out the list of which JVMs are started, and what services are running within them.
• -stopjvm
  Stop an individual JVM, terminating the process.
• -startjvm
  Asks the launcher to start a specific JVM process.
• -restartjvm
  Asks the launcher to starts a specific JVM, first stopping it and then starting it again.

You can also use -restartall which will shutdown all running child processes, re-read the launch .xml file and relaunch again.

This Is an Example of a Launcher File:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Ceptor Launcher configuration -->
<ceptorlauncher port="21211"
	launcherclasspath="classes/launcher;lib/CeptorAgent.jar;extlib/logback-core-1.1.5.jar;extlib/logback-classic-1.1.5.jar;extlib/slf4j-api-1.7.16.jar" jvmstartdelay="5">
	<!-- Ceptor Server -->
	<jvm name="ppserver" vmargs="-Xmx1024M -Djava.awt.headless=true -Xnoclassgc -XX:+HeapDumpOnOutOfMemoryError -XX:+ExitOnOutOfMemoryError" systemclasspath="">
		<config servers="loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false" />
		<!-- Split into multiple classloaders -->
		<classloader name="config">
			<service name="configserver1" launcherclass="dk.itp.managed.service.ConfigServerLauncher">
				<property name="configuration"
					value="${ceptor.home}/config/ceptor-configuration.xml" />
				<webserver webapp="${ceptor.home}/ppserver/webapp"
					httpport="4244" sslport="4245" keystoretype="JKS"
					keystore="${ceptor.home}/ppserver/portalprotect.key"
					password="changeit" />
			</service>
			<service name="logserver1" serviceclass="dk.itp.peer2peer.log.server.LogServer" />
			<service name="statisticsserver1" serviceclass="dk.itp.managed.service.StatisticsService" />
		</classloader>
		<classloader name="config2">
			<service name="configserver2" launcherclass="dk.itp.managed.service.ConfigServerLauncher">
				<property name="configuration"
					value="${ceptor.home}/config/ceptor-configuration.xml" />
				<webserver webapp="${ceptor.home}/ppserver/webapp"
					httpport="4252" sslport="4253" keystoretype="JKS"
					keystore="${ceptor.home}/ppserver/portalprotect.key"
					password="changeit" />
			</service>
		</classloader>
		<classloader name="sessionctrl">
			<service name="sessionctrl1" serviceclass="dk.itp.security.passticket.server.PTSServer" />
			<service name="useradmin1"
				launcherclass="dk.itp.pp.useradmin.server.UserAdminServerLauncher" />
			<service name="radiusserver1"
				launcherclass="dk.itp.pp.radius.RadiusServerLauncher" />
        </classloader>
		<classloader name="useradminapp" extraclasspath="extlib_extras/jsp;extlib_extras/wicket;${ceptor.home}/ppserver/useradmin/language">
			<service name="useradminapp" launcherclass="dk.asseco.pp.ua.UserAdminAppLauncher">
				<webserver webapp="${ceptor.home}/ppserver/useradmin"
					bindaddress="127.0.0.1" httpport="4343" sslport="4344" keystoretype="JKS"
					keystore="${ceptor.home}/ppserver/portalprotect.key"
					password="changeit" minthreads="2" maxthreads="20" />
			</service>
        </classloader>
        <classloader name="scl_and_axis">
			<service name="axis"
				launcherclass="dk.itp.pp.webservices.launcher.WebServicesLauncher">
				<webserver webapp="${ceptor.home}/ppserver/webserviceswebapp"
					httpport="4300" sslport="4301" keystoretype="JKS"
					keystore="${ceptor.home}/ppserver/portalprotect.key"
					password="changeit" />
			</service>
<!-- Uncomment to load SCL -->
<!--
            <service name="sclserver1" launcherclass="dk.itp.scl.server.SCLLauncher">
                <property name="additionalservlets" value="sclsimple,sclssl,scl1"/>
                <property name="servlet.sclsimple.class" value="dk.itp.scl.server.simple.SimpleServer"/>
                <property name="servlet.sclsimple.server.name" value="scl_simple"/>              
                <property name="servlet.sclsimple.urlpattern" value="/pp/simpleserver"/>
                <property name="servlet.sclssl.class" value="dk.itp.scl.server.ssl.SSLServer"/>
                <property name="servlet.sclssl.server.name" value="scl_ssl"/>
                <property name="servlet.sclssl.urlpattern" value="/pp/scl_sslserver"/>             
                <property name="servlet.scl1.class" value="dk.itp.scl.server.crypto.CryptoServer"/>
                <property name="servlet.scl1.server.name" value="scl1"/>
                <property name="servlet.scl1.urlpattern" value="/pp/cryptoserver"/>             
                <webserver webapp="${ceptor.home}/ppserver/webapp" httpport="4222"/>
            </service>
-->
            <service name="proxy1"
                launcherclass="dk.itp.security.proxy.ProxyLauncher">
                <webserver webapp="${ceptor.home}/ppserver/webapp" httpport="4400"/>
            </service>
		</classloader>
	</jvm>
	<!-- Ceptor Console -->
	<jvm name="console" vmargs="-Xmx1024M -Xnoclassgc -XX:+HeapDumpOnOutOfMemoryError -XX:+ExitOnOutOfMemoryError">
        <config servers="nios://localhost:21233?validateservercert=false" />
        <classloader name="console" extraclasspath="">
            <service name="ceptorconsole" launcherclass="io.ceptor.console.ConsoleLauncher">
                <property name="sessioncookiename" value="jsession_ceptorconsole"/>
                <webserver webapp="${ceptor.home}/ppserver/console"
                    contextpath="/"
                    bindaddress="0.0.0.0" httpport="4242" sslport="4243" minthreads="2" maxthreads="10"
                    maxpostsize="67108864" maxidletime="10000"
                    responseheadersize="32768"
                    outputbuffersize="32768" keystoretype="JKS"
					keystore="${ceptor.home}/ppserver/portalprotect.key"
					password="changeit" 
                    />
            </service>
        </classloader>
	</jvm>
	<!-- Ceptor Gateway -->
	<jvm name="gateway" vmargs="-Xmx1024M -Xnoclassgc -XX:+HeapDumpOnOutOfMemoryError -XX:+ExitOnOutOfMemoryError -Dorg.jboss.logging.provider=slf4j" systemclasspath="">
		<config servers="loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false" />
		<classloader name="gw" extraclasspath="gateway">
			<service name="gateway1" launcherclass="io.ceptor.gateway.GatewayLauncher">
			</service>
		</classloader>
	</jvm>
	<!-- Ceptor Dispatcher -->
	<jvm name="dispatcher" vmargs="-Xmx1024M -Xnoclassgc -XX:+HeapDumpOnOutOfMemoryError -XX:+ExitOnOutOfMemoryError -Xbootclasspath/p:&quot;${ceptor.home}/alpn/alpn-boot-8.1.9.v20160720.jar&quot;" systemclasspath="">
		<config servers="loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false" />
		<classloader name="dispatcher">
			<service name="dispatcher1" launcherclass="dk.itp.tunnel.DispatcherLauncher ">
			    <property name="ws.jettyxml" value="${ceptor.home}/dispatcher/jetty-requestlog.xml;${ceptor.home}/dispatcher/jetty-lowresources.xml;${ceptor.home}/dispatcher/jetty-rewrite.xml"/>
<!-- Uncomment to load SCL -->
<!--
			    <property name="additionalservlets" value="scl1,sclssl"/>
			    <property name="servlet.scl1.class" value="dk.itp.scl.server.tunnel.TunnelServlet"/>
                <property name="servlet.scl1.server.name" value="scltunnel1"/>			    
                <property name="servlet.scl1.urlpattern" value="/scltunnel;/pp/cryptoserver"/>
                <property name="servlet.sclssl.class" value="dk.itp.scl.server.tunnel.TunnelServlet"/>
                <property name="servlet.sclssl.server.name" value="scl_ssltunnel"/>
                <property name="servlet.sclssl.urlpattern" value="/pp/ssltunnel"/>             
-->
                <property name="alpn.protocols" value="ssl,alpn,h2,h2-17,h2-16,h2-15,h2-14,http/1.1"/>
                
				<webserver webapp="${ceptor.home}/dispatcher/webapp"
                    http2="true"
					bindaddress="0.0.0.0" httpport="4080" sslport="4443" keystoretype="JKS"
					keystore="${ceptor.home}/dispatcher/portalprotect.key"
					password="changeit" minthreads="2" maxthreads="500"
					maxpostsize="67108864" maxidletime="10000"
					wantclientauth="true"
					allowrenegotiate="false"
					truststore="${ceptor.home}/config/x509/issuer/certissuer.pfx" excludeprotocols="SSLv3"
					trustpassword="password" truststoretype="PKCS12" truststoreprovider="BC"					
                    excludeciphersuites=".*NULL.*,.*RC4.*,.*MD5.*,.*DSS.*"
                    includeciphersuites="TLS_ECDHE.*,SSL_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA"
					responseheadersize="32768"
					outputbuffersize="32768"
					/>
			</service>
		</classloader>
	</jvm>
</ceptorlauncher>

Let us look at the structure of the file:

<ceptorlauncher port="21211" launcherclasspath="classes/launcher;lib/CeptorAgent.jar;extlib/logback-core-1.1.5.jar;extlib/logback-classic-1.1.5.jar;extlib/slf4j-api-1.7.16.jar" jvmstartdelay="5">

Here, port 21211 is specified – when not running in standalone mode, the port is used by the server JVM which listens for connections from client VMs

The launcherclasspath is relative to the ceptor.home (can be specified using –ceptorhome) and must point to CeptorAgent.jar and the version of the .jar file containing log4j in use. Any .jar files in the patches directory will automatically be placed first in the classpath. When logging to windows event log, see the section later in this document for additional .jars needed here.

jvmstartdelay can specify the number of seconds of delay between each JVM client process is started, in case the launcher should start more than a single client process.

<jvm name="ppserver" vmargs="-Xmx1024M -Djava.awt.headless=true -Xnoclassgc -XX:+HeapDumpOnOutOfMemoryError -XX:+ExitOnOutOfMemoryError" systemclasspath="">

Here we define a JVM called "ppserver" (just a logical name, it doesn't matter which as long as it is unique) and we give it some options, such as maximum memory.

<jvm name="ppserver" vmargs="-server -Xmx1024M" vm="/myjdk/bin/java.exe">

Optionally we could have specified a particular VM launcher to use when launcing this JVM, by default the same JVM as the one which launced the launcher itself will be used.

<jvm name="ppserver" vmargs="-server -Xmx1024M" systemclasspath="/somewhere/abc.jar">

The system classpath can also be specified if required, when new JVM processes are launched, anything mentioned within is added to the system classpath. This is the place to put eventual .jar files which uses JNI or for other reasons needs to be located in the system classpath.

<config servers="loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false" />

For each JVM, we specify how to reach the configuration server – this will be used by all the services within the JVM.

<classloader name="config">

Within each JVM, we can define one or more classloaders to use – all services specified within a single classloader will be loaded by it, unless the options –separateclassloader or –sharedclassloader are specified on the commandline, since they override this behavior and forces use of either a separate classloader for each service, or the same.

<service name="configserver1" launcherclass="dk.itp.managed.service.ConfigServerLauncher">
  <property name="configuration" value="${ceptor.home}/config/ceptor-configuration.xml" />
  <webserver webapp="${ceptor.home}/ppserver/webapp" httpport="4242" sslport="4243" keystoretype="JKS" keystore="${ceptor.home}/ppserver/portalprotect.key" password="changeit" contextpath="/" bindaddress="0.0.0.0" />
</service>
<service name="logserver1" serviceclass="dk.itp.peer2peer.log.server.LogServer" />

Here, a couple of services are defined. Depending on the type of service, either a launcherclass or serviceclass must be defined – ask support if in doubt.
For the service configserver1 a property is defined pointing the the location of the ceptor-configuration.xml file, additionally an embedded webserver is defined causing the configuration server to be available at http://servername:4242 and https://servername:4243.

For the webserver, the keystore, keystoretype and password point to an SSL server certificate. Note that the password can be obfuscated/encrypted with PasswordUtils – see Encrypting or Obfuscating Passwords for more information about how to do this.

If sslport or httpport is set to 0, it will not listen on that particular port. minthreads/maxthreads can be used to set the size of the thread pool controlling how many simultaneous connections are allowed.

If you specify a bindaddress, the socket will be bound to the specified local IP address, this is useful for restricting the listen to certain network interfaces.

You can also specify a contextpath, or virtualhosts which is a semicolon separated list of virtual hostnames relevant for this service.

Specify maxidletime to change the socket timeout in milliseconds. Jettys default is 200000 (200 seconds which is much too large for most situations).

Specify maxpostsize to change the number of bytes a POST request maximum is allowed to be. The default jetty size is 200000.

You can specify outputbuffersize, requestheadersize and responseheadersize to override the corresponding jetty default values if needed.

Note that if you reuse the same bindaddress, httpport and sslport for an additional webserver configuration within the same classloader; the previously defined server will be reused.

Additional SSL attributes:

You can specify the following additional SSL attributes (besides the ones listed above):

Additionally, you can add a custom XML Jetty configuration, by setting

<property name="ws.jettyxml" value="${ceptor.home}/config/jettyconfig.xml" />

This will allow you to customize any other setting you might need, refer to the Jetty documentation if you need to do this.
You should set it to "${ceptor.home}/dispatcher/jetty-rewrite.xml" to add the Jetty Rewrite Module – it adds known security headers, please refer to (and edit) jetty-rewrite.xml.

You can add additional .jar files or directories containing .jar files by setting the attribute extraclasspath on the classloader definition. This can be used to add extra .jar files only to specific classloaders, e.g. so you add JSP support to a webapp, but not to the dispatcher or the rest of the services in the PP server.

If needed, you can use ${systempropertyname} in classpath definitions, configserver, vmargs, properties and all attributes on webserver definition – the value will be replaced with the value of the corresponding system property which you can define when starting the launcher. To pass system properties on to child JVMs, add "–Dmyproperty=${myproperty}" to the vmargs for each JVM that needs this property.

Logging

Ceptor uses SLF4J for logging, SLF4J is a generic logging API that allows for logs to be redirected to a number of different logging frameworks such as log4j, java.util.logging or logback. You can find more information about slf4j at http://www.slf4j.org/ and from there you can download a number of different adapters that redirect logging.
By default, Ceptor now uses logback – this can be considered a modern version of log4j, and information is available here: http://logback.qos.ch/ You can find detailed information on how to configure logback here: http://logback.qos.ch/manual/index.html
Ceptor Agent contains special appenders for log4j and logback-classic, both allow an agent to send log entries to Ceptor LogServer, where they can be consolidated or viewed online using the Ceptor Console.
Logging is configured by logback.xml in the classes directory within the distribution.

Required .jar files in classpath

Ceptor Agent requires slf4j-api-1.7.5.jar and at least one more .jar file of an application which implement the SLF4J API. For logback, this is logback-core-1.0.13.jar and logback-classic-1.0.13.jar.
Ceptor Server components log the same way as the agent does, but the Ceptor LogServer will both log4j and logback .jar files in its classpath, since it is able to receive both log4j and logback events from agents/log clients.
If you want to configure Ceptor Server to log using log4j instead of logback, you need to make sure that slf4j-log4j12-1.7.5.jar is in the classpath BEFORE logback-classic-1.0.13.jar, or logback will be used instead. If you are running PP server in a web app, you might need to rename slf4j-log4j12-1.7.5.jar to e.g. a_slf4j-log4j12-1.7.5.jar to get your web container to load it before logback-classic.

Configuring Ceptor Log Appenders in Your Own Applications

You can send log events from your own applications to Ceptor, all it requires is that you configure a logback or log4j appender and tell it to send its log to Ceptor LogServer.
You do this like this for log4j:

log4j.appender.ITPLog=dk.itp.peer2peer.log.RemoteLogAppender
log4j.appender.ITPLog.LocationInfo=false
log4j.appender.ITPLog.Servers=nio://ceptorserver.mycompany.com:21236
log4j.appender.ITPLog.PeerName=my_app_name

and for logback:

<appender name="PPRemoteLog" class="dk.itp.peer2peer.log.RemoteLogbackAppender">
  <Servers>nio://ceptorserver.mycompany.com:21236</Servers>
  <PeerName>my_app_name</PeerName>
</appender>

Switching to log4j

If you wish to log to log4j, you will still need slf4j-api-1.7.5.jar, but must also add slf4j-log4j12-1.7.5.jar, and log4j-1.2.16.jar, these extra jar files are available in the PP distribution in the samples/log4j directory.
If log4j is used, logback.xml is no longer read, so you will instead need log4j.properties in the classes directory, sample files can be found in samples/log4j directory.
If using Ceptor Launcher, your ceptor_launch.xml will need a launcherclasspath like the following:

launcherclasspath="classes/launcher;lib/CeptorAgent.jar;extlib/log4j-1.2.16.jar;extlib/slf4j-api-1.7.5.jar;extlib/slf4j-log4j12-1.7.5.jar">

When using the default logger implementation, logback, the launcherclasspath in ceptor_launch.xml must look like this:

launcherclasspath="classes/launcher;lib/CeptorAgent.jar;extlib/logback-core-1.1.5.jar;extlib/logback-classic-1.1.5.jar;extlib/slf4j-api-1.7.16.jar"

Ceptor LogServer logging

Ceptor LogServer versions before 5.0 used log4jserver.properties to load its log4j logger configuration used to log consolidated logger events sent to it by various agents and PP components. Now, the log server will by default attempt to load logback_server.xml from the classpath and use this to configure logback. If this file is not found, it will fallback to log4j_server.properties and attempt to load that and log4j to log any events it receives from agents/clients.

Logging to Windows Event Log with log4jna

We recommend you use log4jna if you need to log to the windows event log.
samples/log4j/config/log4j.properties already contains a log4j appender ready for use, just add it to the list of active appenders.
To use event logging from the launcher, you need to add a few .jars to the launcher .xml file launcherclasspath entry; extlib_extras/log4jna/jna.jar;extlib_extras/log4jna/platform.jar;extlib_extras/log4jna/log4jna.jar"
Like this example.:

 launcherclasspath="classes/launcher;lib/CeptorAgent.jar;extlib/log4j-1.2.16.jar;extlib_extras/log4jna/jna.jar;extlib_extras/log4jna/platform.jar;extlib_extras/log4jna/log4jna.jar"

Then you need to add the same .jar files to extraclasspath for each classloader or simply copy the .jar files from extlib_extra/log4jna to extlib to get them there automatically.

If you wish to use logback with windows event logging, there is an example in classes/logback.xml you can uncomment, and add the appender to the ROOT appender – you still need jna.jar and platform.jar on your classpath, but the appender itself is already within CeptorAgent.jar

<appender name="WindowsEventLog" class="dk.itp.log.Log4JnaLogbackAppender">
  <layout class="ch.qos.logback.classic.PatternLayout">
    <pattern>%d{ISO8601} [%t] %-5level %logger %X{sessionid} - %msg%n%throwable</pattern>
  </layout>
  <source>pp_log</source>
  <server>Ceptor</server>
</appender>

For this to work, you will need to add a key to the windows registry using regedit
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\eventlog\Ceptor\pp_logEventMessageFile="C:\Windows\System32\Win32EventLogAppender.dll"
Make sure you adjust the path to where you have copied Win32EventLogAppender.dll – you can find it in extlib_extras/log4jna the last part of the path, the source pp_log must match the entry in <source> in logback.xml – you can change this if you run multiple different JVMs with different ceptor instances on the same machine.

Clustering

When running multiple Ceptor Server instances in a cluster, each instance should have its unique list of servers, e.g. server1 should have configserver1, sessionctrl1 etc. and server2 should have logserver2, sesssionctrl2.
So you will need a different launcher xml on server2, simply replace all xxxxx1 with xxxxx2 and add the new servers to ceptor-configuration.xml and you have your cluster configuration.
It is also possible to use the same launcher XML file with multiple clusters, by defining multiple different JVMs, each with their own services, and on each machine you can then specify the –jvms xxxx parameter to limit startup to only some JVMs on each machine.

File permissions and Security

The Ceptor Installer allows you to select a user account to create the service for when installing. Depending on the type of operating system you install on, there can be subtle differences in the behaviour.
On Windows, the installed service is using the specified account, or if no account it uses the default localsystem Windows account. Note that the account needs the "Logon as a service" permission, or installation of the service will not complete. If an account is specified, the service account gets full access filepermissions added to all the installed files. But, the installer is unable to remove permissions, which means that any administrator users on the machine will have access to the files – you should change the permissions manually to limit access as much as possible.
On Unix-based systems, the ownership is controlled by permissions, and if a service account is specified in the installer, the owner will be changed to the specified account, and all file permissions will be set so only the owner has access.
Note that on unix-based system, you will need to be root to listen on port 80/443 – but it is in general not a good idea to run as root since in the event of a security breach, the process has access to too many other files.
One efficient way of getting around this limitation, is to let PP Dispatcher listen on port 4080/4443 and use ipchains or iptables to redirect the traffic from port 80 to 4080 and from 443 to 4443 (or whatever other port you prefer).
You can find a bit of information and examples of the syntax of these commands here: http://wiki.eclipse.org/Jetty/Howto/Port80
Note that Jetty itself allows setUid to switch userid after listening initially, but we do not recommend or support this, as it requires a bit of extra native code and can cause annoying problems with regards to file permissions.

if [ ! $USER = "userName" ]; then
     echo Switching user to userName
     exec su - userName $prg_dir/$progname $@
fi 

if [ ! "$USER" = "userName" ]; then
     echo Switching user to userName
     exec su userName -c "$0 $@"
fi