unicore g · in this way, only a single open port in a site’s firewall has to be configured....
TRANSCRIPT
UNICORE Gateway
UNICORE GATEWAY
UNICORE Team
Document Version 110Component Version 803Date 29 04 2020
This work is co-funded by the EC EMI project under the FP7 Collaborative Projects GrantAgreement Nr INFSO-RI-261611
UNICORE Gateway
Contents
1 Introduction 1
2 Installation 2
21 Installation from the core server bundle 2
22 Installation from a Linux package (rpm or deb) 2
3 Upgrading 3
4 Configuration 3
41 Java and environment settings startupproperties 3
42 Configuring sites connectionsproperties 3
43 Main server settings gatewayproperties 4
44 Require end-user certificates 15
45 Logging 16
5 Using Apache httpd as a frontend 18
6 Using the Gateway for failover andor loadbalancing of UNICORE sites 18
61 Configuration 19
62 Available Strategies 19
7 Gateway failover and migration 20
71 Gatewayrsquos migration 20
72 Failover and loadbalancing of the Gateway 21
8 Building the Gateway from source 21
UNICORE Gateway 1
This user manual provides information on running and using the UNICORE Gateway Pleasenote also the following places for getting more information
UNICORE Website httpswwwunicoreeu
Support list unicore-supportlistssfnet
Developerrsquos list unicore-devellistssfnet
1 Introduction
The Gateway is the entry point into a UNICORE site routing HTTPS traffic to servers likeUNICOREX It is installed in front of any networking firewall It (optionally) authenticatesincoming messages and forwards them to their intended destination The Gateway receives thereply and sends it back to the client In this way only a single open port in a sitersquos firewall hasto be configured
LIMITATIONSThis forwarding process only works for ldquomostrdquo HTTP requests and is not a complete HTTPreverse proxy implementation For example it is not possible to run a full complex web ap-plication like the UNICORE Portal behind the Gateway Check the respective componentsrsquosmanual whether it can be run behind the Gateway
In effect traffic to a virtual URL eg httpsmygateway8088Alpha is forwarded to the realURL eg httpshost17777
The mappings of virtual URL to real URL for the available sites are listed in a configurationfile connectionsproperties Additionally the Gateway supports dynamic registrationof sites
The second functionality of the Gateway is (optional) authentication of incoming requests Con-nections to the Gateway are made using SSL so the Gateway can be configured to checkwhether the caller presents a certificate issued by a trusted authority Information about theclient is forwarded to services behind the Gateway in UNICORE proprietary format (as a SOAPor HTTP header)
The Gateway will forward the IP address of the client to the back-end server
Last not least the Gateway can be configured as a HTTP load balancer
UNICORE Gateway 2
IMPORTANT NOTE ON PATHSThe UNICORE Gateway is distributed either as a platform independent and portable bundle(as a part of the UNICORE core server package) or as an installable platform dependentpackage format such as RPMDepending on the installation method the paths to various Gateway files are different Ifinstalling using a distribution-specific package the following paths are used
CONF=etcunicoregatewayBIN=usrsbinLOG=varlogunicoregateway
If installing using the portable bundle all Gateway files are installed under a single directoryPath prefixes then are as follows where INST is a directory where the Gateway was installed
CONF=INSTconfBIN=INSTbinLOG=INSTlog
The above variables (CONF BIN and LOG) are used throughout the rest of this manual
2 Installation
The UNICORE Gateway is distributed in the following formats
1 As a part of platform independent installation bundle called UNICORE core server bun-dle The UNICORE core server bundle is provided in two forms one with a graphicalinstaller and one with a command line installer
2 As a binary platform-specific package available currently for RedHat (Centos) and De-bian platforms Those packages are not tested on all possible platforms but should workwithout any problems with other versions of similar distributions eg SL6 Centos orFedora
21 Installation from the core server bundle
Download the core server bundle from the UNICORE project website
If you use the graphical installer follow the on-screen instructions and do not forget to enablethe Gateway checkbox when prompted
If you use the console installer please review the README file available after extracting thebundle You donrsquot have to change any defaults as the Gateway is installed by default
22 Installation from a Linux package (rpm or deb)
Use your distributionrsquos package manager to install
UNICORE Gateway 3
3 Upgrading
The general update procedure is presented below with possible variations
1 Stop the old Gateway
2 Update the server package This step mostly applies for RPMDEB managed installationsFor Quickstart installation it is enough to replace the jar files with the new ones
3 Start the newly installed Gateway
4 Verify log file and fix any problems reported
4 Configuration
The Gateway is configured using a set of configuration files which reside in the CONF subdi-rectory
41 Java and environment settings startupproperties
This file contains settings related to the Java VM such as the Java command to use memorysettings library paths etc
42 Configuring sites connectionsproperties
This is a simple list connecting the names of sites and their physical addresses An example is
DEMO-SITE = httpslocalhost7777REGISTRY = httpslocalhost7778
If this file is modified the Gateway will re-read it at runtime so there is no need to restart theGateway in order to add or remove sites
Optionally administrator can enable a possibility for dynamic site registration at runtime seeSection 433 for details Then this file should contain only the static entries (or none if all sitesregister dynamically)
Further options for back-end sites configuration are presented in Section 6
UNICORE Gateway 4
43 Main server settings gatewayproperties
Use the gatewayhostname property to configure the network interface and port the Gate-way will listen on You can also select between https and http protocol though in almost allcases https will be used
Example
gatewayhostname = https1921681001238080
NoteIf you set the host to 0000 the Gateway will listen on all network interfaces of the hostmachine else it will listen only on the specified one
If the scheme of the hostname URL is set to https the Gateway uses the configuration data fromsecurityproperties to configure the HTTPS settings
431 Credential and truststore settings
The Gateway credential and truststore is configured using the following properties
Property name Type Defaultvalue mandatory
Description
gatewaycredentialpathfilesystem path mandatoryto be set
Credential location In caseof jks pkcs12 and pem storeit is the only locationrequired In case whencredential is provided intwo files it is the certificatefile path
gatewaycredentialformat[jks pkcs12der pem]
- Format of the credential Itis guessed when not givenNote that pem might beeither a PEM keystore withcertificates and keys (inPEM format) or a pair ofPEM files (one withcertificate and second withprivate key)
gatewaycredentialpasswordstring - Password required to loadthe credential
UNICORE Gateway 5
Property name Type Defaultvalue mandatory
Description
gatewaycredentialkeyPathstring - Location of the private keyif stored separately fromthe main credential(applicable for pem and dertypes only)
gatewaycredentialkeyPasswordstring - Private key passwordwhich might be neededonly for jks or pkcs12 ifkey is encrypted withdifferent password then themain credential password
gatewaycredentialkeyAliasstring - Keystore alias of the keyentry to be used Can beignored if the keystorecontains only one key entryOnly applicable for jks andpkcs12
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreallowProxy[ALLOWDENY]
ALLOW Controls whether proxycertificates are supported
gatewaytruststoretype[keystoreopenssldirectory]
mandatoryto be set
The truststore type
gatewaytruststoreupdateIntervalinteger number 600 How often the truststoreshould be reloaded inseconds Set to negativevalue to disable refreshingat runtime (runtimeupdateable)
--- Directory type settings ---gatewaytruststoredirectoryConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CAcertificates in seconds
UNICORE Gateway 6
Property name Type Defaultvalue mandatory
Description
gatewaytruststoredirectoryDiskCachePathfilesystem path - Directory where CAcertificates should becached after downloadingthem from a remote sourceCan be left undefined if nodisk cache should be usedNote that directory shouldbe secured ie normalusers should not be allowedto write to it
gatewaytruststoredirectoryEncoding[PEM DER] PEM For directory truststorecontrols whethercertificates are encoded inPEM or DER Note that thePEM file can containarbitrary number ofconcatenatedPEM-encoded certificates
gatewaytruststoredirectoryLocationslist ofproperties witha commonprefix
- List of CA certificateslocations Can containURLs local files andwildcard expressions(runtime updateable)
--- Keystore type settings ---gatewaytruststorekeystoreFormatstring - The keystore type (jks
pkcs12) in case of truststoreof keystore type
gatewaytruststorekeystorePasswordstring - The password of thekeystore type truststore
gatewaytruststorekeystorePathstring - The keystore path in case oftruststore of keystore type
--- Openssl type settings ---gatewaytruststoreopensslNewStoreFormat[true false] false In case of openssl
truststore specifies whetherthe trust store is in openssl100+ format (true) orolder openssl 0x format(false)
UNICORE Gateway 7
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreopensslNsMode[GLOBUS_EUGRIDPMAEU-GRIDPMA_GLOBUSGLOBUSEUGRIDPMAGLOBUS_EUGRIDPMA_REQUIREEU-GRIDPMA_GLOBUS_REQUIREGLOBUS_REQUIREEU-GRIDPMA_REQUIREEU-GRIDPMA_AND_GLOBUSEU-GRIDPMA_AND_GLOBUS_REQUIREIGNORE]
EUGRIDPMA_GLOBUSIn case of openssltruststore controls which(and in which order)namespace checking rulesshould be applied TheREQUIRE settings willcause that all configurednamespace definitions filesmust be present for eachtrusted CA certificate(otherwise checking willfail) The AND settings willcause to check both existingnamespace files Otherwisethe first found is checked(in the order defined by theproperty)
gatewaytruststoreopensslPathfilesystem path etcgrid-securitycertificatesDirectory to be used foropeenssl truststore
--- Revocation settings ---gatewaytruststorecrlConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CRLsin seconds (not used forOpenssl truststores)
gatewaytruststorecrlDiskCachePathfilesystem path - Directory where CRLsshould be cached afterdownloading them fromremote source Can be leftundefined if no disk cacheshould be used Note thatdirectory should besecured ie normal usersshould not be allowed towrite to it Not used forOpenssl truststores
gatewaytruststorecrlLocationslist ofproperties witha commonprefix
- List of CRLs locations Cancontain URLs local filesand wildcard expressionsNot used for Openssltruststores (runtimeupdateable)
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway
Contents
1 Introduction 1
2 Installation 2
21 Installation from the core server bundle 2
22 Installation from a Linux package (rpm or deb) 2
3 Upgrading 3
4 Configuration 3
41 Java and environment settings startupproperties 3
42 Configuring sites connectionsproperties 3
43 Main server settings gatewayproperties 4
44 Require end-user certificates 15
45 Logging 16
5 Using Apache httpd as a frontend 18
6 Using the Gateway for failover andor loadbalancing of UNICORE sites 18
61 Configuration 19
62 Available Strategies 19
7 Gateway failover and migration 20
71 Gatewayrsquos migration 20
72 Failover and loadbalancing of the Gateway 21
8 Building the Gateway from source 21
UNICORE Gateway 1
This user manual provides information on running and using the UNICORE Gateway Pleasenote also the following places for getting more information
UNICORE Website httpswwwunicoreeu
Support list unicore-supportlistssfnet
Developerrsquos list unicore-devellistssfnet
1 Introduction
The Gateway is the entry point into a UNICORE site routing HTTPS traffic to servers likeUNICOREX It is installed in front of any networking firewall It (optionally) authenticatesincoming messages and forwards them to their intended destination The Gateway receives thereply and sends it back to the client In this way only a single open port in a sitersquos firewall hasto be configured
LIMITATIONSThis forwarding process only works for ldquomostrdquo HTTP requests and is not a complete HTTPreverse proxy implementation For example it is not possible to run a full complex web ap-plication like the UNICORE Portal behind the Gateway Check the respective componentsrsquosmanual whether it can be run behind the Gateway
In effect traffic to a virtual URL eg httpsmygateway8088Alpha is forwarded to the realURL eg httpshost17777
The mappings of virtual URL to real URL for the available sites are listed in a configurationfile connectionsproperties Additionally the Gateway supports dynamic registrationof sites
The second functionality of the Gateway is (optional) authentication of incoming requests Con-nections to the Gateway are made using SSL so the Gateway can be configured to checkwhether the caller presents a certificate issued by a trusted authority Information about theclient is forwarded to services behind the Gateway in UNICORE proprietary format (as a SOAPor HTTP header)
The Gateway will forward the IP address of the client to the back-end server
Last not least the Gateway can be configured as a HTTP load balancer
UNICORE Gateway 2
IMPORTANT NOTE ON PATHSThe UNICORE Gateway is distributed either as a platform independent and portable bundle(as a part of the UNICORE core server package) or as an installable platform dependentpackage format such as RPMDepending on the installation method the paths to various Gateway files are different Ifinstalling using a distribution-specific package the following paths are used
CONF=etcunicoregatewayBIN=usrsbinLOG=varlogunicoregateway
If installing using the portable bundle all Gateway files are installed under a single directoryPath prefixes then are as follows where INST is a directory where the Gateway was installed
CONF=INSTconfBIN=INSTbinLOG=INSTlog
The above variables (CONF BIN and LOG) are used throughout the rest of this manual
2 Installation
The UNICORE Gateway is distributed in the following formats
1 As a part of platform independent installation bundle called UNICORE core server bun-dle The UNICORE core server bundle is provided in two forms one with a graphicalinstaller and one with a command line installer
2 As a binary platform-specific package available currently for RedHat (Centos) and De-bian platforms Those packages are not tested on all possible platforms but should workwithout any problems with other versions of similar distributions eg SL6 Centos orFedora
21 Installation from the core server bundle
Download the core server bundle from the UNICORE project website
If you use the graphical installer follow the on-screen instructions and do not forget to enablethe Gateway checkbox when prompted
If you use the console installer please review the README file available after extracting thebundle You donrsquot have to change any defaults as the Gateway is installed by default
22 Installation from a Linux package (rpm or deb)
Use your distributionrsquos package manager to install
UNICORE Gateway 3
3 Upgrading
The general update procedure is presented below with possible variations
1 Stop the old Gateway
2 Update the server package This step mostly applies for RPMDEB managed installationsFor Quickstart installation it is enough to replace the jar files with the new ones
3 Start the newly installed Gateway
4 Verify log file and fix any problems reported
4 Configuration
The Gateway is configured using a set of configuration files which reside in the CONF subdi-rectory
41 Java and environment settings startupproperties
This file contains settings related to the Java VM such as the Java command to use memorysettings library paths etc
42 Configuring sites connectionsproperties
This is a simple list connecting the names of sites and their physical addresses An example is
DEMO-SITE = httpslocalhost7777REGISTRY = httpslocalhost7778
If this file is modified the Gateway will re-read it at runtime so there is no need to restart theGateway in order to add or remove sites
Optionally administrator can enable a possibility for dynamic site registration at runtime seeSection 433 for details Then this file should contain only the static entries (or none if all sitesregister dynamically)
Further options for back-end sites configuration are presented in Section 6
UNICORE Gateway 4
43 Main server settings gatewayproperties
Use the gatewayhostname property to configure the network interface and port the Gate-way will listen on You can also select between https and http protocol though in almost allcases https will be used
Example
gatewayhostname = https1921681001238080
NoteIf you set the host to 0000 the Gateway will listen on all network interfaces of the hostmachine else it will listen only on the specified one
If the scheme of the hostname URL is set to https the Gateway uses the configuration data fromsecurityproperties to configure the HTTPS settings
431 Credential and truststore settings
The Gateway credential and truststore is configured using the following properties
Property name Type Defaultvalue mandatory
Description
gatewaycredentialpathfilesystem path mandatoryto be set
Credential location In caseof jks pkcs12 and pem storeit is the only locationrequired In case whencredential is provided intwo files it is the certificatefile path
gatewaycredentialformat[jks pkcs12der pem]
- Format of the credential Itis guessed when not givenNote that pem might beeither a PEM keystore withcertificates and keys (inPEM format) or a pair ofPEM files (one withcertificate and second withprivate key)
gatewaycredentialpasswordstring - Password required to loadthe credential
UNICORE Gateway 5
Property name Type Defaultvalue mandatory
Description
gatewaycredentialkeyPathstring - Location of the private keyif stored separately fromthe main credential(applicable for pem and dertypes only)
gatewaycredentialkeyPasswordstring - Private key passwordwhich might be neededonly for jks or pkcs12 ifkey is encrypted withdifferent password then themain credential password
gatewaycredentialkeyAliasstring - Keystore alias of the keyentry to be used Can beignored if the keystorecontains only one key entryOnly applicable for jks andpkcs12
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreallowProxy[ALLOWDENY]
ALLOW Controls whether proxycertificates are supported
gatewaytruststoretype[keystoreopenssldirectory]
mandatoryto be set
The truststore type
gatewaytruststoreupdateIntervalinteger number 600 How often the truststoreshould be reloaded inseconds Set to negativevalue to disable refreshingat runtime (runtimeupdateable)
--- Directory type settings ---gatewaytruststoredirectoryConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CAcertificates in seconds
UNICORE Gateway 6
Property name Type Defaultvalue mandatory
Description
gatewaytruststoredirectoryDiskCachePathfilesystem path - Directory where CAcertificates should becached after downloadingthem from a remote sourceCan be left undefined if nodisk cache should be usedNote that directory shouldbe secured ie normalusers should not be allowedto write to it
gatewaytruststoredirectoryEncoding[PEM DER] PEM For directory truststorecontrols whethercertificates are encoded inPEM or DER Note that thePEM file can containarbitrary number ofconcatenatedPEM-encoded certificates
gatewaytruststoredirectoryLocationslist ofproperties witha commonprefix
- List of CA certificateslocations Can containURLs local files andwildcard expressions(runtime updateable)
--- Keystore type settings ---gatewaytruststorekeystoreFormatstring - The keystore type (jks
pkcs12) in case of truststoreof keystore type
gatewaytruststorekeystorePasswordstring - The password of thekeystore type truststore
gatewaytruststorekeystorePathstring - The keystore path in case oftruststore of keystore type
--- Openssl type settings ---gatewaytruststoreopensslNewStoreFormat[true false] false In case of openssl
truststore specifies whetherthe trust store is in openssl100+ format (true) orolder openssl 0x format(false)
UNICORE Gateway 7
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreopensslNsMode[GLOBUS_EUGRIDPMAEU-GRIDPMA_GLOBUSGLOBUSEUGRIDPMAGLOBUS_EUGRIDPMA_REQUIREEU-GRIDPMA_GLOBUS_REQUIREGLOBUS_REQUIREEU-GRIDPMA_REQUIREEU-GRIDPMA_AND_GLOBUSEU-GRIDPMA_AND_GLOBUS_REQUIREIGNORE]
EUGRIDPMA_GLOBUSIn case of openssltruststore controls which(and in which order)namespace checking rulesshould be applied TheREQUIRE settings willcause that all configurednamespace definitions filesmust be present for eachtrusted CA certificate(otherwise checking willfail) The AND settings willcause to check both existingnamespace files Otherwisethe first found is checked(in the order defined by theproperty)
gatewaytruststoreopensslPathfilesystem path etcgrid-securitycertificatesDirectory to be used foropeenssl truststore
--- Revocation settings ---gatewaytruststorecrlConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CRLsin seconds (not used forOpenssl truststores)
gatewaytruststorecrlDiskCachePathfilesystem path - Directory where CRLsshould be cached afterdownloading them fromremote source Can be leftundefined if no disk cacheshould be used Note thatdirectory should besecured ie normal usersshould not be allowed towrite to it Not used forOpenssl truststores
gatewaytruststorecrlLocationslist ofproperties witha commonprefix
- List of CRLs locations Cancontain URLs local filesand wildcard expressionsNot used for Openssltruststores (runtimeupdateable)
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 1
This user manual provides information on running and using the UNICORE Gateway Pleasenote also the following places for getting more information
UNICORE Website httpswwwunicoreeu
Support list unicore-supportlistssfnet
Developerrsquos list unicore-devellistssfnet
1 Introduction
The Gateway is the entry point into a UNICORE site routing HTTPS traffic to servers likeUNICOREX It is installed in front of any networking firewall It (optionally) authenticatesincoming messages and forwards them to their intended destination The Gateway receives thereply and sends it back to the client In this way only a single open port in a sitersquos firewall hasto be configured
LIMITATIONSThis forwarding process only works for ldquomostrdquo HTTP requests and is not a complete HTTPreverse proxy implementation For example it is not possible to run a full complex web ap-plication like the UNICORE Portal behind the Gateway Check the respective componentsrsquosmanual whether it can be run behind the Gateway
In effect traffic to a virtual URL eg httpsmygateway8088Alpha is forwarded to the realURL eg httpshost17777
The mappings of virtual URL to real URL for the available sites are listed in a configurationfile connectionsproperties Additionally the Gateway supports dynamic registrationof sites
The second functionality of the Gateway is (optional) authentication of incoming requests Con-nections to the Gateway are made using SSL so the Gateway can be configured to checkwhether the caller presents a certificate issued by a trusted authority Information about theclient is forwarded to services behind the Gateway in UNICORE proprietary format (as a SOAPor HTTP header)
The Gateway will forward the IP address of the client to the back-end server
Last not least the Gateway can be configured as a HTTP load balancer
UNICORE Gateway 2
IMPORTANT NOTE ON PATHSThe UNICORE Gateway is distributed either as a platform independent and portable bundle(as a part of the UNICORE core server package) or as an installable platform dependentpackage format such as RPMDepending on the installation method the paths to various Gateway files are different Ifinstalling using a distribution-specific package the following paths are used
CONF=etcunicoregatewayBIN=usrsbinLOG=varlogunicoregateway
If installing using the portable bundle all Gateway files are installed under a single directoryPath prefixes then are as follows where INST is a directory where the Gateway was installed
CONF=INSTconfBIN=INSTbinLOG=INSTlog
The above variables (CONF BIN and LOG) are used throughout the rest of this manual
2 Installation
The UNICORE Gateway is distributed in the following formats
1 As a part of platform independent installation bundle called UNICORE core server bun-dle The UNICORE core server bundle is provided in two forms one with a graphicalinstaller and one with a command line installer
2 As a binary platform-specific package available currently for RedHat (Centos) and De-bian platforms Those packages are not tested on all possible platforms but should workwithout any problems with other versions of similar distributions eg SL6 Centos orFedora
21 Installation from the core server bundle
Download the core server bundle from the UNICORE project website
If you use the graphical installer follow the on-screen instructions and do not forget to enablethe Gateway checkbox when prompted
If you use the console installer please review the README file available after extracting thebundle You donrsquot have to change any defaults as the Gateway is installed by default
22 Installation from a Linux package (rpm or deb)
Use your distributionrsquos package manager to install
UNICORE Gateway 3
3 Upgrading
The general update procedure is presented below with possible variations
1 Stop the old Gateway
2 Update the server package This step mostly applies for RPMDEB managed installationsFor Quickstart installation it is enough to replace the jar files with the new ones
3 Start the newly installed Gateway
4 Verify log file and fix any problems reported
4 Configuration
The Gateway is configured using a set of configuration files which reside in the CONF subdi-rectory
41 Java and environment settings startupproperties
This file contains settings related to the Java VM such as the Java command to use memorysettings library paths etc
42 Configuring sites connectionsproperties
This is a simple list connecting the names of sites and their physical addresses An example is
DEMO-SITE = httpslocalhost7777REGISTRY = httpslocalhost7778
If this file is modified the Gateway will re-read it at runtime so there is no need to restart theGateway in order to add or remove sites
Optionally administrator can enable a possibility for dynamic site registration at runtime seeSection 433 for details Then this file should contain only the static entries (or none if all sitesregister dynamically)
Further options for back-end sites configuration are presented in Section 6
UNICORE Gateway 4
43 Main server settings gatewayproperties
Use the gatewayhostname property to configure the network interface and port the Gate-way will listen on You can also select between https and http protocol though in almost allcases https will be used
Example
gatewayhostname = https1921681001238080
NoteIf you set the host to 0000 the Gateway will listen on all network interfaces of the hostmachine else it will listen only on the specified one
If the scheme of the hostname URL is set to https the Gateway uses the configuration data fromsecurityproperties to configure the HTTPS settings
431 Credential and truststore settings
The Gateway credential and truststore is configured using the following properties
Property name Type Defaultvalue mandatory
Description
gatewaycredentialpathfilesystem path mandatoryto be set
Credential location In caseof jks pkcs12 and pem storeit is the only locationrequired In case whencredential is provided intwo files it is the certificatefile path
gatewaycredentialformat[jks pkcs12der pem]
- Format of the credential Itis guessed when not givenNote that pem might beeither a PEM keystore withcertificates and keys (inPEM format) or a pair ofPEM files (one withcertificate and second withprivate key)
gatewaycredentialpasswordstring - Password required to loadthe credential
UNICORE Gateway 5
Property name Type Defaultvalue mandatory
Description
gatewaycredentialkeyPathstring - Location of the private keyif stored separately fromthe main credential(applicable for pem and dertypes only)
gatewaycredentialkeyPasswordstring - Private key passwordwhich might be neededonly for jks or pkcs12 ifkey is encrypted withdifferent password then themain credential password
gatewaycredentialkeyAliasstring - Keystore alias of the keyentry to be used Can beignored if the keystorecontains only one key entryOnly applicable for jks andpkcs12
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreallowProxy[ALLOWDENY]
ALLOW Controls whether proxycertificates are supported
gatewaytruststoretype[keystoreopenssldirectory]
mandatoryto be set
The truststore type
gatewaytruststoreupdateIntervalinteger number 600 How often the truststoreshould be reloaded inseconds Set to negativevalue to disable refreshingat runtime (runtimeupdateable)
--- Directory type settings ---gatewaytruststoredirectoryConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CAcertificates in seconds
UNICORE Gateway 6
Property name Type Defaultvalue mandatory
Description
gatewaytruststoredirectoryDiskCachePathfilesystem path - Directory where CAcertificates should becached after downloadingthem from a remote sourceCan be left undefined if nodisk cache should be usedNote that directory shouldbe secured ie normalusers should not be allowedto write to it
gatewaytruststoredirectoryEncoding[PEM DER] PEM For directory truststorecontrols whethercertificates are encoded inPEM or DER Note that thePEM file can containarbitrary number ofconcatenatedPEM-encoded certificates
gatewaytruststoredirectoryLocationslist ofproperties witha commonprefix
- List of CA certificateslocations Can containURLs local files andwildcard expressions(runtime updateable)
--- Keystore type settings ---gatewaytruststorekeystoreFormatstring - The keystore type (jks
pkcs12) in case of truststoreof keystore type
gatewaytruststorekeystorePasswordstring - The password of thekeystore type truststore
gatewaytruststorekeystorePathstring - The keystore path in case oftruststore of keystore type
--- Openssl type settings ---gatewaytruststoreopensslNewStoreFormat[true false] false In case of openssl
truststore specifies whetherthe trust store is in openssl100+ format (true) orolder openssl 0x format(false)
UNICORE Gateway 7
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreopensslNsMode[GLOBUS_EUGRIDPMAEU-GRIDPMA_GLOBUSGLOBUSEUGRIDPMAGLOBUS_EUGRIDPMA_REQUIREEU-GRIDPMA_GLOBUS_REQUIREGLOBUS_REQUIREEU-GRIDPMA_REQUIREEU-GRIDPMA_AND_GLOBUSEU-GRIDPMA_AND_GLOBUS_REQUIREIGNORE]
EUGRIDPMA_GLOBUSIn case of openssltruststore controls which(and in which order)namespace checking rulesshould be applied TheREQUIRE settings willcause that all configurednamespace definitions filesmust be present for eachtrusted CA certificate(otherwise checking willfail) The AND settings willcause to check both existingnamespace files Otherwisethe first found is checked(in the order defined by theproperty)
gatewaytruststoreopensslPathfilesystem path etcgrid-securitycertificatesDirectory to be used foropeenssl truststore
--- Revocation settings ---gatewaytruststorecrlConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CRLsin seconds (not used forOpenssl truststores)
gatewaytruststorecrlDiskCachePathfilesystem path - Directory where CRLsshould be cached afterdownloading them fromremote source Can be leftundefined if no disk cacheshould be used Note thatdirectory should besecured ie normal usersshould not be allowed towrite to it Not used forOpenssl truststores
gatewaytruststorecrlLocationslist ofproperties witha commonprefix
- List of CRLs locations Cancontain URLs local filesand wildcard expressionsNot used for Openssltruststores (runtimeupdateable)
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 2
IMPORTANT NOTE ON PATHSThe UNICORE Gateway is distributed either as a platform independent and portable bundle(as a part of the UNICORE core server package) or as an installable platform dependentpackage format such as RPMDepending on the installation method the paths to various Gateway files are different Ifinstalling using a distribution-specific package the following paths are used
CONF=etcunicoregatewayBIN=usrsbinLOG=varlogunicoregateway
If installing using the portable bundle all Gateway files are installed under a single directoryPath prefixes then are as follows where INST is a directory where the Gateway was installed
CONF=INSTconfBIN=INSTbinLOG=INSTlog
The above variables (CONF BIN and LOG) are used throughout the rest of this manual
2 Installation
The UNICORE Gateway is distributed in the following formats
1 As a part of platform independent installation bundle called UNICORE core server bun-dle The UNICORE core server bundle is provided in two forms one with a graphicalinstaller and one with a command line installer
2 As a binary platform-specific package available currently for RedHat (Centos) and De-bian platforms Those packages are not tested on all possible platforms but should workwithout any problems with other versions of similar distributions eg SL6 Centos orFedora
21 Installation from the core server bundle
Download the core server bundle from the UNICORE project website
If you use the graphical installer follow the on-screen instructions and do not forget to enablethe Gateway checkbox when prompted
If you use the console installer please review the README file available after extracting thebundle You donrsquot have to change any defaults as the Gateway is installed by default
22 Installation from a Linux package (rpm or deb)
Use your distributionrsquos package manager to install
UNICORE Gateway 3
3 Upgrading
The general update procedure is presented below with possible variations
1 Stop the old Gateway
2 Update the server package This step mostly applies for RPMDEB managed installationsFor Quickstart installation it is enough to replace the jar files with the new ones
3 Start the newly installed Gateway
4 Verify log file and fix any problems reported
4 Configuration
The Gateway is configured using a set of configuration files which reside in the CONF subdi-rectory
41 Java and environment settings startupproperties
This file contains settings related to the Java VM such as the Java command to use memorysettings library paths etc
42 Configuring sites connectionsproperties
This is a simple list connecting the names of sites and their physical addresses An example is
DEMO-SITE = httpslocalhost7777REGISTRY = httpslocalhost7778
If this file is modified the Gateway will re-read it at runtime so there is no need to restart theGateway in order to add or remove sites
Optionally administrator can enable a possibility for dynamic site registration at runtime seeSection 433 for details Then this file should contain only the static entries (or none if all sitesregister dynamically)
Further options for back-end sites configuration are presented in Section 6
UNICORE Gateway 4
43 Main server settings gatewayproperties
Use the gatewayhostname property to configure the network interface and port the Gate-way will listen on You can also select between https and http protocol though in almost allcases https will be used
Example
gatewayhostname = https1921681001238080
NoteIf you set the host to 0000 the Gateway will listen on all network interfaces of the hostmachine else it will listen only on the specified one
If the scheme of the hostname URL is set to https the Gateway uses the configuration data fromsecurityproperties to configure the HTTPS settings
431 Credential and truststore settings
The Gateway credential and truststore is configured using the following properties
Property name Type Defaultvalue mandatory
Description
gatewaycredentialpathfilesystem path mandatoryto be set
Credential location In caseof jks pkcs12 and pem storeit is the only locationrequired In case whencredential is provided intwo files it is the certificatefile path
gatewaycredentialformat[jks pkcs12der pem]
- Format of the credential Itis guessed when not givenNote that pem might beeither a PEM keystore withcertificates and keys (inPEM format) or a pair ofPEM files (one withcertificate and second withprivate key)
gatewaycredentialpasswordstring - Password required to loadthe credential
UNICORE Gateway 5
Property name Type Defaultvalue mandatory
Description
gatewaycredentialkeyPathstring - Location of the private keyif stored separately fromthe main credential(applicable for pem and dertypes only)
gatewaycredentialkeyPasswordstring - Private key passwordwhich might be neededonly for jks or pkcs12 ifkey is encrypted withdifferent password then themain credential password
gatewaycredentialkeyAliasstring - Keystore alias of the keyentry to be used Can beignored if the keystorecontains only one key entryOnly applicable for jks andpkcs12
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreallowProxy[ALLOWDENY]
ALLOW Controls whether proxycertificates are supported
gatewaytruststoretype[keystoreopenssldirectory]
mandatoryto be set
The truststore type
gatewaytruststoreupdateIntervalinteger number 600 How often the truststoreshould be reloaded inseconds Set to negativevalue to disable refreshingat runtime (runtimeupdateable)
--- Directory type settings ---gatewaytruststoredirectoryConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CAcertificates in seconds
UNICORE Gateway 6
Property name Type Defaultvalue mandatory
Description
gatewaytruststoredirectoryDiskCachePathfilesystem path - Directory where CAcertificates should becached after downloadingthem from a remote sourceCan be left undefined if nodisk cache should be usedNote that directory shouldbe secured ie normalusers should not be allowedto write to it
gatewaytruststoredirectoryEncoding[PEM DER] PEM For directory truststorecontrols whethercertificates are encoded inPEM or DER Note that thePEM file can containarbitrary number ofconcatenatedPEM-encoded certificates
gatewaytruststoredirectoryLocationslist ofproperties witha commonprefix
- List of CA certificateslocations Can containURLs local files andwildcard expressions(runtime updateable)
--- Keystore type settings ---gatewaytruststorekeystoreFormatstring - The keystore type (jks
pkcs12) in case of truststoreof keystore type
gatewaytruststorekeystorePasswordstring - The password of thekeystore type truststore
gatewaytruststorekeystorePathstring - The keystore path in case oftruststore of keystore type
--- Openssl type settings ---gatewaytruststoreopensslNewStoreFormat[true false] false In case of openssl
truststore specifies whetherthe trust store is in openssl100+ format (true) orolder openssl 0x format(false)
UNICORE Gateway 7
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreopensslNsMode[GLOBUS_EUGRIDPMAEU-GRIDPMA_GLOBUSGLOBUSEUGRIDPMAGLOBUS_EUGRIDPMA_REQUIREEU-GRIDPMA_GLOBUS_REQUIREGLOBUS_REQUIREEU-GRIDPMA_REQUIREEU-GRIDPMA_AND_GLOBUSEU-GRIDPMA_AND_GLOBUS_REQUIREIGNORE]
EUGRIDPMA_GLOBUSIn case of openssltruststore controls which(and in which order)namespace checking rulesshould be applied TheREQUIRE settings willcause that all configurednamespace definitions filesmust be present for eachtrusted CA certificate(otherwise checking willfail) The AND settings willcause to check both existingnamespace files Otherwisethe first found is checked(in the order defined by theproperty)
gatewaytruststoreopensslPathfilesystem path etcgrid-securitycertificatesDirectory to be used foropeenssl truststore
--- Revocation settings ---gatewaytruststorecrlConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CRLsin seconds (not used forOpenssl truststores)
gatewaytruststorecrlDiskCachePathfilesystem path - Directory where CRLsshould be cached afterdownloading them fromremote source Can be leftundefined if no disk cacheshould be used Note thatdirectory should besecured ie normal usersshould not be allowed towrite to it Not used forOpenssl truststores
gatewaytruststorecrlLocationslist ofproperties witha commonprefix
- List of CRLs locations Cancontain URLs local filesand wildcard expressionsNot used for Openssltruststores (runtimeupdateable)
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 3
3 Upgrading
The general update procedure is presented below with possible variations
1 Stop the old Gateway
2 Update the server package This step mostly applies for RPMDEB managed installationsFor Quickstart installation it is enough to replace the jar files with the new ones
3 Start the newly installed Gateway
4 Verify log file and fix any problems reported
4 Configuration
The Gateway is configured using a set of configuration files which reside in the CONF subdi-rectory
41 Java and environment settings startupproperties
This file contains settings related to the Java VM such as the Java command to use memorysettings library paths etc
42 Configuring sites connectionsproperties
This is a simple list connecting the names of sites and their physical addresses An example is
DEMO-SITE = httpslocalhost7777REGISTRY = httpslocalhost7778
If this file is modified the Gateway will re-read it at runtime so there is no need to restart theGateway in order to add or remove sites
Optionally administrator can enable a possibility for dynamic site registration at runtime seeSection 433 for details Then this file should contain only the static entries (or none if all sitesregister dynamically)
Further options for back-end sites configuration are presented in Section 6
UNICORE Gateway 4
43 Main server settings gatewayproperties
Use the gatewayhostname property to configure the network interface and port the Gate-way will listen on You can also select between https and http protocol though in almost allcases https will be used
Example
gatewayhostname = https1921681001238080
NoteIf you set the host to 0000 the Gateway will listen on all network interfaces of the hostmachine else it will listen only on the specified one
If the scheme of the hostname URL is set to https the Gateway uses the configuration data fromsecurityproperties to configure the HTTPS settings
431 Credential and truststore settings
The Gateway credential and truststore is configured using the following properties
Property name Type Defaultvalue mandatory
Description
gatewaycredentialpathfilesystem path mandatoryto be set
Credential location In caseof jks pkcs12 and pem storeit is the only locationrequired In case whencredential is provided intwo files it is the certificatefile path
gatewaycredentialformat[jks pkcs12der pem]
- Format of the credential Itis guessed when not givenNote that pem might beeither a PEM keystore withcertificates and keys (inPEM format) or a pair ofPEM files (one withcertificate and second withprivate key)
gatewaycredentialpasswordstring - Password required to loadthe credential
UNICORE Gateway 5
Property name Type Defaultvalue mandatory
Description
gatewaycredentialkeyPathstring - Location of the private keyif stored separately fromthe main credential(applicable for pem and dertypes only)
gatewaycredentialkeyPasswordstring - Private key passwordwhich might be neededonly for jks or pkcs12 ifkey is encrypted withdifferent password then themain credential password
gatewaycredentialkeyAliasstring - Keystore alias of the keyentry to be used Can beignored if the keystorecontains only one key entryOnly applicable for jks andpkcs12
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreallowProxy[ALLOWDENY]
ALLOW Controls whether proxycertificates are supported
gatewaytruststoretype[keystoreopenssldirectory]
mandatoryto be set
The truststore type
gatewaytruststoreupdateIntervalinteger number 600 How often the truststoreshould be reloaded inseconds Set to negativevalue to disable refreshingat runtime (runtimeupdateable)
--- Directory type settings ---gatewaytruststoredirectoryConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CAcertificates in seconds
UNICORE Gateway 6
Property name Type Defaultvalue mandatory
Description
gatewaytruststoredirectoryDiskCachePathfilesystem path - Directory where CAcertificates should becached after downloadingthem from a remote sourceCan be left undefined if nodisk cache should be usedNote that directory shouldbe secured ie normalusers should not be allowedto write to it
gatewaytruststoredirectoryEncoding[PEM DER] PEM For directory truststorecontrols whethercertificates are encoded inPEM or DER Note that thePEM file can containarbitrary number ofconcatenatedPEM-encoded certificates
gatewaytruststoredirectoryLocationslist ofproperties witha commonprefix
- List of CA certificateslocations Can containURLs local files andwildcard expressions(runtime updateable)
--- Keystore type settings ---gatewaytruststorekeystoreFormatstring - The keystore type (jks
pkcs12) in case of truststoreof keystore type
gatewaytruststorekeystorePasswordstring - The password of thekeystore type truststore
gatewaytruststorekeystorePathstring - The keystore path in case oftruststore of keystore type
--- Openssl type settings ---gatewaytruststoreopensslNewStoreFormat[true false] false In case of openssl
truststore specifies whetherthe trust store is in openssl100+ format (true) orolder openssl 0x format(false)
UNICORE Gateway 7
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreopensslNsMode[GLOBUS_EUGRIDPMAEU-GRIDPMA_GLOBUSGLOBUSEUGRIDPMAGLOBUS_EUGRIDPMA_REQUIREEU-GRIDPMA_GLOBUS_REQUIREGLOBUS_REQUIREEU-GRIDPMA_REQUIREEU-GRIDPMA_AND_GLOBUSEU-GRIDPMA_AND_GLOBUS_REQUIREIGNORE]
EUGRIDPMA_GLOBUSIn case of openssltruststore controls which(and in which order)namespace checking rulesshould be applied TheREQUIRE settings willcause that all configurednamespace definitions filesmust be present for eachtrusted CA certificate(otherwise checking willfail) The AND settings willcause to check both existingnamespace files Otherwisethe first found is checked(in the order defined by theproperty)
gatewaytruststoreopensslPathfilesystem path etcgrid-securitycertificatesDirectory to be used foropeenssl truststore
--- Revocation settings ---gatewaytruststorecrlConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CRLsin seconds (not used forOpenssl truststores)
gatewaytruststorecrlDiskCachePathfilesystem path - Directory where CRLsshould be cached afterdownloading them fromremote source Can be leftundefined if no disk cacheshould be used Note thatdirectory should besecured ie normal usersshould not be allowed towrite to it Not used forOpenssl truststores
gatewaytruststorecrlLocationslist ofproperties witha commonprefix
- List of CRLs locations Cancontain URLs local filesand wildcard expressionsNot used for Openssltruststores (runtimeupdateable)
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 4
43 Main server settings gatewayproperties
Use the gatewayhostname property to configure the network interface and port the Gate-way will listen on You can also select between https and http protocol though in almost allcases https will be used
Example
gatewayhostname = https1921681001238080
NoteIf you set the host to 0000 the Gateway will listen on all network interfaces of the hostmachine else it will listen only on the specified one
If the scheme of the hostname URL is set to https the Gateway uses the configuration data fromsecurityproperties to configure the HTTPS settings
431 Credential and truststore settings
The Gateway credential and truststore is configured using the following properties
Property name Type Defaultvalue mandatory
Description
gatewaycredentialpathfilesystem path mandatoryto be set
Credential location In caseof jks pkcs12 and pem storeit is the only locationrequired In case whencredential is provided intwo files it is the certificatefile path
gatewaycredentialformat[jks pkcs12der pem]
- Format of the credential Itis guessed when not givenNote that pem might beeither a PEM keystore withcertificates and keys (inPEM format) or a pair ofPEM files (one withcertificate and second withprivate key)
gatewaycredentialpasswordstring - Password required to loadthe credential
UNICORE Gateway 5
Property name Type Defaultvalue mandatory
Description
gatewaycredentialkeyPathstring - Location of the private keyif stored separately fromthe main credential(applicable for pem and dertypes only)
gatewaycredentialkeyPasswordstring - Private key passwordwhich might be neededonly for jks or pkcs12 ifkey is encrypted withdifferent password then themain credential password
gatewaycredentialkeyAliasstring - Keystore alias of the keyentry to be used Can beignored if the keystorecontains only one key entryOnly applicable for jks andpkcs12
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreallowProxy[ALLOWDENY]
ALLOW Controls whether proxycertificates are supported
gatewaytruststoretype[keystoreopenssldirectory]
mandatoryto be set
The truststore type
gatewaytruststoreupdateIntervalinteger number 600 How often the truststoreshould be reloaded inseconds Set to negativevalue to disable refreshingat runtime (runtimeupdateable)
--- Directory type settings ---gatewaytruststoredirectoryConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CAcertificates in seconds
UNICORE Gateway 6
Property name Type Defaultvalue mandatory
Description
gatewaytruststoredirectoryDiskCachePathfilesystem path - Directory where CAcertificates should becached after downloadingthem from a remote sourceCan be left undefined if nodisk cache should be usedNote that directory shouldbe secured ie normalusers should not be allowedto write to it
gatewaytruststoredirectoryEncoding[PEM DER] PEM For directory truststorecontrols whethercertificates are encoded inPEM or DER Note that thePEM file can containarbitrary number ofconcatenatedPEM-encoded certificates
gatewaytruststoredirectoryLocationslist ofproperties witha commonprefix
- List of CA certificateslocations Can containURLs local files andwildcard expressions(runtime updateable)
--- Keystore type settings ---gatewaytruststorekeystoreFormatstring - The keystore type (jks
pkcs12) in case of truststoreof keystore type
gatewaytruststorekeystorePasswordstring - The password of thekeystore type truststore
gatewaytruststorekeystorePathstring - The keystore path in case oftruststore of keystore type
--- Openssl type settings ---gatewaytruststoreopensslNewStoreFormat[true false] false In case of openssl
truststore specifies whetherthe trust store is in openssl100+ format (true) orolder openssl 0x format(false)
UNICORE Gateway 7
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreopensslNsMode[GLOBUS_EUGRIDPMAEU-GRIDPMA_GLOBUSGLOBUSEUGRIDPMAGLOBUS_EUGRIDPMA_REQUIREEU-GRIDPMA_GLOBUS_REQUIREGLOBUS_REQUIREEU-GRIDPMA_REQUIREEU-GRIDPMA_AND_GLOBUSEU-GRIDPMA_AND_GLOBUS_REQUIREIGNORE]
EUGRIDPMA_GLOBUSIn case of openssltruststore controls which(and in which order)namespace checking rulesshould be applied TheREQUIRE settings willcause that all configurednamespace definitions filesmust be present for eachtrusted CA certificate(otherwise checking willfail) The AND settings willcause to check both existingnamespace files Otherwisethe first found is checked(in the order defined by theproperty)
gatewaytruststoreopensslPathfilesystem path etcgrid-securitycertificatesDirectory to be used foropeenssl truststore
--- Revocation settings ---gatewaytruststorecrlConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CRLsin seconds (not used forOpenssl truststores)
gatewaytruststorecrlDiskCachePathfilesystem path - Directory where CRLsshould be cached afterdownloading them fromremote source Can be leftundefined if no disk cacheshould be used Note thatdirectory should besecured ie normal usersshould not be allowed towrite to it Not used forOpenssl truststores
gatewaytruststorecrlLocationslist ofproperties witha commonprefix
- List of CRLs locations Cancontain URLs local filesand wildcard expressionsNot used for Openssltruststores (runtimeupdateable)
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 5
Property name Type Defaultvalue mandatory
Description
gatewaycredentialkeyPathstring - Location of the private keyif stored separately fromthe main credential(applicable for pem and dertypes only)
gatewaycredentialkeyPasswordstring - Private key passwordwhich might be neededonly for jks or pkcs12 ifkey is encrypted withdifferent password then themain credential password
gatewaycredentialkeyAliasstring - Keystore alias of the keyentry to be used Can beignored if the keystorecontains only one key entryOnly applicable for jks andpkcs12
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreallowProxy[ALLOWDENY]
ALLOW Controls whether proxycertificates are supported
gatewaytruststoretype[keystoreopenssldirectory]
mandatoryto be set
The truststore type
gatewaytruststoreupdateIntervalinteger number 600 How often the truststoreshould be reloaded inseconds Set to negativevalue to disable refreshingat runtime (runtimeupdateable)
--- Directory type settings ---gatewaytruststoredirectoryConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CAcertificates in seconds
UNICORE Gateway 6
Property name Type Defaultvalue mandatory
Description
gatewaytruststoredirectoryDiskCachePathfilesystem path - Directory where CAcertificates should becached after downloadingthem from a remote sourceCan be left undefined if nodisk cache should be usedNote that directory shouldbe secured ie normalusers should not be allowedto write to it
gatewaytruststoredirectoryEncoding[PEM DER] PEM For directory truststorecontrols whethercertificates are encoded inPEM or DER Note that thePEM file can containarbitrary number ofconcatenatedPEM-encoded certificates
gatewaytruststoredirectoryLocationslist ofproperties witha commonprefix
- List of CA certificateslocations Can containURLs local files andwildcard expressions(runtime updateable)
--- Keystore type settings ---gatewaytruststorekeystoreFormatstring - The keystore type (jks
pkcs12) in case of truststoreof keystore type
gatewaytruststorekeystorePasswordstring - The password of thekeystore type truststore
gatewaytruststorekeystorePathstring - The keystore path in case oftruststore of keystore type
--- Openssl type settings ---gatewaytruststoreopensslNewStoreFormat[true false] false In case of openssl
truststore specifies whetherthe trust store is in openssl100+ format (true) orolder openssl 0x format(false)
UNICORE Gateway 7
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreopensslNsMode[GLOBUS_EUGRIDPMAEU-GRIDPMA_GLOBUSGLOBUSEUGRIDPMAGLOBUS_EUGRIDPMA_REQUIREEU-GRIDPMA_GLOBUS_REQUIREGLOBUS_REQUIREEU-GRIDPMA_REQUIREEU-GRIDPMA_AND_GLOBUSEU-GRIDPMA_AND_GLOBUS_REQUIREIGNORE]
EUGRIDPMA_GLOBUSIn case of openssltruststore controls which(and in which order)namespace checking rulesshould be applied TheREQUIRE settings willcause that all configurednamespace definitions filesmust be present for eachtrusted CA certificate(otherwise checking willfail) The AND settings willcause to check both existingnamespace files Otherwisethe first found is checked(in the order defined by theproperty)
gatewaytruststoreopensslPathfilesystem path etcgrid-securitycertificatesDirectory to be used foropeenssl truststore
--- Revocation settings ---gatewaytruststorecrlConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CRLsin seconds (not used forOpenssl truststores)
gatewaytruststorecrlDiskCachePathfilesystem path - Directory where CRLsshould be cached afterdownloading them fromremote source Can be leftundefined if no disk cacheshould be used Note thatdirectory should besecured ie normal usersshould not be allowed towrite to it Not used forOpenssl truststores
gatewaytruststorecrlLocationslist ofproperties witha commonprefix
- List of CRLs locations Cancontain URLs local filesand wildcard expressionsNot used for Openssltruststores (runtimeupdateable)
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 6
Property name Type Defaultvalue mandatory
Description
gatewaytruststoredirectoryDiskCachePathfilesystem path - Directory where CAcertificates should becached after downloadingthem from a remote sourceCan be left undefined if nodisk cache should be usedNote that directory shouldbe secured ie normalusers should not be allowedto write to it
gatewaytruststoredirectoryEncoding[PEM DER] PEM For directory truststorecontrols whethercertificates are encoded inPEM or DER Note that thePEM file can containarbitrary number ofconcatenatedPEM-encoded certificates
gatewaytruststoredirectoryLocationslist ofproperties witha commonprefix
- List of CA certificateslocations Can containURLs local files andwildcard expressions(runtime updateable)
--- Keystore type settings ---gatewaytruststorekeystoreFormatstring - The keystore type (jks
pkcs12) in case of truststoreof keystore type
gatewaytruststorekeystorePasswordstring - The password of thekeystore type truststore
gatewaytruststorekeystorePathstring - The keystore path in case oftruststore of keystore type
--- Openssl type settings ---gatewaytruststoreopensslNewStoreFormat[true false] false In case of openssl
truststore specifies whetherthe trust store is in openssl100+ format (true) orolder openssl 0x format(false)
UNICORE Gateway 7
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreopensslNsMode[GLOBUS_EUGRIDPMAEU-GRIDPMA_GLOBUSGLOBUSEUGRIDPMAGLOBUS_EUGRIDPMA_REQUIREEU-GRIDPMA_GLOBUS_REQUIREGLOBUS_REQUIREEU-GRIDPMA_REQUIREEU-GRIDPMA_AND_GLOBUSEU-GRIDPMA_AND_GLOBUS_REQUIREIGNORE]
EUGRIDPMA_GLOBUSIn case of openssltruststore controls which(and in which order)namespace checking rulesshould be applied TheREQUIRE settings willcause that all configurednamespace definitions filesmust be present for eachtrusted CA certificate(otherwise checking willfail) The AND settings willcause to check both existingnamespace files Otherwisethe first found is checked(in the order defined by theproperty)
gatewaytruststoreopensslPathfilesystem path etcgrid-securitycertificatesDirectory to be used foropeenssl truststore
--- Revocation settings ---gatewaytruststorecrlConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CRLsin seconds (not used forOpenssl truststores)
gatewaytruststorecrlDiskCachePathfilesystem path - Directory where CRLsshould be cached afterdownloading them fromremote source Can be leftundefined if no disk cacheshould be used Note thatdirectory should besecured ie normal usersshould not be allowed towrite to it Not used forOpenssl truststores
gatewaytruststorecrlLocationslist ofproperties witha commonprefix
- List of CRLs locations Cancontain URLs local filesand wildcard expressionsNot used for Openssltruststores (runtimeupdateable)
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 7
Property name Type Defaultvalue mandatory
Description
gatewaytruststoreopensslNsMode[GLOBUS_EUGRIDPMAEU-GRIDPMA_GLOBUSGLOBUSEUGRIDPMAGLOBUS_EUGRIDPMA_REQUIREEU-GRIDPMA_GLOBUS_REQUIREGLOBUS_REQUIREEU-GRIDPMA_REQUIREEU-GRIDPMA_AND_GLOBUSEU-GRIDPMA_AND_GLOBUS_REQUIREIGNORE]
EUGRIDPMA_GLOBUSIn case of openssltruststore controls which(and in which order)namespace checking rulesshould be applied TheREQUIRE settings willcause that all configurednamespace definitions filesmust be present for eachtrusted CA certificate(otherwise checking willfail) The AND settings willcause to check both existingnamespace files Otherwisethe first found is checked(in the order defined by theproperty)
gatewaytruststoreopensslPathfilesystem path etcgrid-securitycertificatesDirectory to be used foropeenssl truststore
--- Revocation settings ---gatewaytruststorecrlConnectionTimeoutinteger number 15 Connection timeout for
fetching the remote CRLsin seconds (not used forOpenssl truststores)
gatewaytruststorecrlDiskCachePathfilesystem path - Directory where CRLsshould be cached afterdownloading them fromremote source Can be leftundefined if no disk cacheshould be used Note thatdirectory should besecured ie normal usersshould not be allowed towrite to it Not used forOpenssl truststores
gatewaytruststorecrlLocationslist ofproperties witha commonprefix
- List of CRLs locations Cancontain URLs local filesand wildcard expressionsNot used for Openssltruststores (runtimeupdateable)
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 8
Property name Type Defaultvalue mandatory
Description
gatewaytruststorecrlMode[REQUIREIF_VALIDIGNORE]
IF_VALID General CRL handlingmode The IF_VALIDsetting turns on CRLchecking only in case theCRL is present
gatewaytruststorecrlUpdateIntervalinteger number 600 How often CRLs should beupdated in seconds Set tonegative value to disablerefreshing at runtime(runtime updateable)
gatewaytruststoreocspCacheTtlinteger number 3600 For how long the OCSPresponses should be locallycached in seconds (this is amaximum value responseswonrsquot be cached afterexpiration)
gatewaytruststoreocspDiskCachefilesystem path - If this property is definedthen OCSP responses willbe cached on disk in thedefined folder
gatewaytruststoreocspLocalRespondersltNUMBERgtlist ofproperties witha commonprefix
- Optional list of local OCSPresponders
gatewaytruststoreocspMode[REQUIREIF_AVAILABLEIGNORE]
IF_AVAILABLEGeneral OCSP ckeckingmode REQUIRE shouldnot be used unless it isguaranteed that for allcertificates an OCSPresponder is defined
gatewaytruststoreocspTimeoutinteger number 10000 Timeout for OCSPconnections in miliseconds
gatewaytruststorerevocationOrder[CRL_OCSPOCSP_CRL]
OCSP_CRL Controls overal revocationsources order
gatewaytruststorerevocationUseAll[true false] false Controls whether alldefined revocation sourcesshould be always checkedeven if the first one alreadyconfirmed that a checkedcertificate is not revoked
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 9
432 Scalability settings
To fine-tune the operational parameters of the embedded Jetty server you can set advancedHTTP server parameters See [informaltable] for details Among others you can use the non-blocking IO connector offered by Jetty which will scale up to higher numbers of concurrentconnections than the default connector
The Gateway acts as a https client for the VSites behind it The number of concurrent calls islimited and controlled by two parameters
maximum total number of concurrent calls to VsitesgatewayclientmaxTotal=100 total number of concurrent calls per sitegatewayclientmaxPerService=20
You can also control the limit on the maximum SOAP header size which is allowed by theGateway Typically you donrsquot have to touch this parameter However if your clients doproduce very big SOAP headers and the Gateway blocks them you can increase the limit Notethat such a giant SOAP header usually means that the client is not behaving in a sane way egis trying to perform a DoS attack
maximum size of an accepted SOAP header in bytesgatewaysoapMaxHeader=102400
Note that Gateway may consume this amount of memory (plus some extra amount for otherdata) for each opened connection Therefore this value multiplied by the number of maximumallowed connections should be significantly lower then the total memory available for theGateway
433 Dynamic registration of Vsites
Dynamic registration is controlled by three properties in CONFgatewayproperties file
gatewayregistrationenable=truegatewayregistrationsecret=ltyour keygt
If set to true the Gateway will accept dynamic registrations which are made by sending a HTTPPOST request to the URL VSITE_REGISTRATION_REQUEST This request must contain aparameter secret which matches the value configured in the gatewayproperties file
Filters can be set to forbid access of certain hosts or to require certain strings in the Vsiteaddresses For example
gatewayregistrationdeny=fooorg exampleorg
will deny registration if the remote hostname contains fooorg or exampleorg Conversely
gatewayregistrationallow=mydomainorg
will only accept registrations if the remote address contains mydomainorg These two (denyand allow) can be combined
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 10
434 Web interface (monkey page)
For testing and simple monitoring purposes the Gateway displays a website showing detailedsite information (the details view can be disabled) Once the Gateway is running open up abrowser and navigate to httpsltgateway_hostgt8080 (or whichever URL the gateway is run-ning on) If the Gateway is configured to do SSL authentication you will need to import asuitable client certificate into your web browser
A HTML form for testing the dynamic registration is available as well by clicking the link inthe footer of the main Gateway page
To disable the Vsite details page set
gatewaydisableWebpage=true
435 Main options reference
Property name Type Defaultvalue mandatory
Description
gatewayhostname string mandatoryto be set
external gateway bindaddress
gatewayregistrationallowstring - Space separated list ofallowed hosts for dynamicregistration
gatewayregistrationdenystring - Space separated list ofdenied hosts for dynamicregistration
gatewayregistrationenable[true false] false Whether dynamicregistration of sites isenabled
gatewayregistrationsecretstring - Required secret fordynamic registration
--- Passing Consignor info ---gatewayconsignorTokenTimeToleranceinteger gt= 0 30 The validity time of the
authenticated clientinformation passed tobackend sites will start thatmany seconds before thereal authentication It isused to mask timesynchronization problemsbetween machines
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 11
Property name Type Defaultvalue mandatory
Description
gatewayconsignorTokenValidityinteger gt= 1 60 What is the validity time ofthe authenticated clientinformation passed tobackend sites Increase it ifthere machines clocks arenot synhronized
gatewaysignConsignorToken[true false] false Controls whetherinformation about theauthenticated client (theconsignor) passed tobackend sites should besigned or not Signing isslower but is requiredwhen sites may be reacheddirectly bypassing theGateway
--- Gatewayrarr Site client ---gatewayclientchunked[true false] true Controls whether chunked
passing of HTTP requeststo backend sites issupported
gatewayclientconnectionTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
gatewayclientexpectContinue[true false] true Controls whether the HTTPexpec-continue mechanismis enaled on connections tobackend sites
gatewayclientgzip[true false] true Controls whether supportfor compression isannounced to backend sites
gatewayclientkeepAlive[true false] true Whether to keep alive theconnections to backendsites
gatewayclientmaxPerServiceinteger number 20 Maximum allowed numberof connections per backendsite
gatewayclientmaxTotalinteger number 100 Maximum total number ofconnections to backendsites allowed
gatewayclientsocketTimeoutinteger number 30000 Connection timeout usedwhen connecting tobackend sites
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 12
Property name Type Defaultvalue mandatory
Description
--- Advanced ---gatewaydisableWebpage[true false] false Whether the (so called
monkey) status web pageshould be disabled
gatewayexternalHostnamestring not set External address of thegateway when it isaccessible through afrontend server as ApacheHTTP
gatewaysoapMaxHeaderinteger [1024mdash1024000000]
102400 Size in bytes of theaccepted SOAP header Inthe most cases you donrsquotneed to change it
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerCORS_allowedHeadersstring CORS comma separatedlist of allowed HTTPheaders (default any)
gatewayhttpServerCORS_allowedMethodsstring GETPUTPOSTDELETEHEADCORS comma separatedlist of allowed HTTP verbs
gatewayhttpServerCORS_allowedOriginsstring CORS allowed scriptorigins
gatewayhttpServerCORS_chainPreflight[true false] false CORS whether preflightOPTION requests arechained (passed on) to theresource or handled via theCORS filter
gatewayhttpServerCORS_exposedHeadersstring LocationContent-TypeCORS comma separatedlist of HTTP headers thatare allowed to be exposedto the client
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 13
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerdisabledCipherSuitesstring emptystring
Space separated list of SSLcipher suites to be disabledNames of the ciphers mustadhere to the standard Javacipher names availableherehttpdocsoraclecom-javase8docstechnotes-guidessecurity-SunProvidershtmlSupportedCipherSuites
gatewayhttpServerenableCORS[true false] false Control whetherCross-Origin ResourceSharing is enabled Enableto allow eg accesingREST services fromclient-side JavaScript
gatewayhttpServerenableHsts[true false] false Control whether HTTPstrict transport security isenabled It is a good andstrongly suggested securitymechanism for allproduction sites At thesame time it can not beused with self-signed or notissued by a generallytrusted CA servercertificates as with HSTS auser canrsquot opt in to entersuch site
gatewayhttpServerfastRandom[true false] false Use insecure but fastpseudo random generator togenerate session ids insteadof secure generator for SSLsockets
gatewayhttpServergzipenable[true false] false Controls whether to enablecompression of HTTPresponses
gatewayhttpServergzipminGzipSizeinteger number 100000 Specifies the minimal sizeof message that should becompressed
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 14
Property name Type Defaultvalue mandatory
Description
gatewayhttpServerhighLoadConnectionsinteger number 200 If the number ofconnections exceeds thisamount then the connectoris put into a special low onresources state Existingconnections will be closedfaster Note that the serverwill also go to the low onresources mode if there areno available threads in thepool You can set this to 0to disable the connectionslimit (and have only threadpool size governed limit) Ifset to a negative numberthen the low on resourcesmode wonrsquot be used at all
gatewayhttpServerlowResourceMaxIdleTimeinteger gt= 1 100 In low resource conditionstime (in ms) before an idleconnection will time out
gatewayhttpServermaxIdleTimeinteger gt= 1 200000 Time (in ms) before an idleconnection will time out Itshould be large enough notto expire connections withslow clients values below30s are getting quite risky
gatewayhttpServermaxThreadsinteger number 255 Maximum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerminThreadsinteger gt= 1 1 Minimum number ofthreads to have in the threadpool for processing HTTPconnections Note that thisnumber will be increasedwith few additional threadsto handle connectors
gatewayhttpServerrequireClientAuthn[true false] true Controls whether the SSLsocket requires client-sideauthentication
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 15
Property name Type Defaultvalue mandatory
Description
gatewayhttpServeruseNIO[true false] true DEPRECATED no effectgatewayhttpServerwantClientAuthn[true false] true Controls whether the SSL
socket accepts (but does notrequire) client-sideauthentication
gatewayhttpServerxFrameAllowedstring httplocalhostURI origin that is allowedto embed web interfaceinside a (i)frameMeaningful only if thexFrameOptions is set toallowFrom The valueshould be in the formhttp[s]host[port]
gatewayhttpServerxFrameOptions[denysameOriginallowFromallow]
deny Defines whether aclickjacking preventionshould be turned on byinsertionof theX-Frame-Options HTTPheader The allow valuedisables the feature See theRFC 7034 for details Notethat for the allowFrom youshould define also thexFrameAllowed option andit is not fully supported byall the browsers
44 Require end-user certificates
In older versions of UNICORE end-users were required to have client certificates Since ver-sion 7 client certificates are optional If you want to require end-user certificates the Gatewaycan be configured accordingly Set following in gatewayproperties
gatewayhttpServerrequireClientAuthn=true
441 Logging
The most important root log categories used by the Gatewayrsquos logging are
unicoregateway General Gateway loggingunicoreconnections Log IPs of clients and the DN after the
SSL handshake
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 16
unicorehttpserver HTTP processing Jetty serverunicoresecurity Certificate details and other security
The Gateway uses the so called MDC (Mapped Diagnostic Context) to provide additionalinformation on the client which is served In the MDC the clientrsquos IP address and clientrsquosDistinguished Name is stored You can control whether to attach MDC to each line by theXentry log4j pattern entry As the entry you can use clientIP or clientNameFor example
log4jappenderA1layoutConversionPattern=d [t] [XclientIP X larrclientName] -5p c1 - mn
45 Logging
UNICORE uses the Log4j logging framework It is configured using a config file By defaultthis file is found in components configuration directory and is named loggingpropertiesThe config file is specified with a Java property log4jconfiguration (which is set instartup script)
Several libraries used by UNICORE also use the Java utils logging facility (the output is two-lines per log entry) For convenience its configuration is also controlled in the same loggingpropertiesfile and is directed to the same destination as the main Log4j output
NoteYou can change the logging configuration at runtime by editing the loggingproperties file Thenew configuration will take effect a few seconds after the file has been modified
By default log files are written to the the LOGS directory
The following example config file configures logging so that log files are rotated daily
Set root logger level to INFO and its only appender to A1log4jrootLogger=INFO A1
A1 is set to be a rolling file appender with default paramslog4jappenderA1=orgapachelog4jDailyRollingFileAppenderlog4jappenderA1File=logsuaslog
configure daily rollover once per day the uaslog will be copiedto a file named eg uaslog2008-12-24log4jappenderA1DatePattern=rsquorsquoyyyy-MM-dd
A1 uses the PatternLayoutlog4jappenderA1layout=orgapachelog4jPatternLayoutlog4jappenderA1layoutConversionPattern=d [t] -5p c1 x - larr
mn
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 17
NoteIn Log4j the log rotation frequency is controlled by the DatePattern Checkhttploggingapacheorglog4j12apidocsorgapachelog4jDailyRollingFileAppenderhtmlfor the details
For more info on controlling the logging we refer to the log4j documentation
bull PatternLayout
bull RollingFileAppender
bull DailyRollingFileAppender
Log4j supports a very wide range of logging options such as date based or size based filerollover logging different things to different files and much more For full information onLog4j we refer to the publicly available documentation for example the Log4j manual
451 Logger categories names and levels
Logger names are hierarchical In UNICORE prefixes are used (eg unicoresecurity) towhich the Java class name is appended For example the XUUDB connector in UNICOREXlogs to the unicoresecurityXUUDBAuthoriser logger
Therefore the logging output produced can be controlled in a fine-grained manner Log levelsin Log4j are (in increasing level of severity)
TRACE on this level huge pieces of unprocessed information are dumped DEBUG on thislevel UNICORE logs (hopefully) admin-friendly verbose information useful for hunting prob-lems INFO standard information not much output WARN warnings are logged when some-thing went wrong (so it should be investigated) but recovery was possible ERROR somethingwent wrong and operation probably failed FATAL something went really wrong - this is usedvery rarely for critical situations like server failure
For example to debug a security problem in the UNICORE security layer you can set
log4jloggerunicoresecurity=DEBUG
If you are just interested in details of credentials handling but not everything related to securityyou can use the following
log4jloggerunicoresecurity=INFOlog4jloggerunicoresecurityCredentialProperties=DEBUG
so the XUUDBAuthoriser will log on DEBUG level while the other security components logon INFO level
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 18
Note(so the full category is printed) and turn on the general DEBUG logging for a while (on uni-core) Then interesting events can be seen and subsequently the logging configuration canbe fine tuned to only show them
5 Using Apache httpd as a frontend
You may wish to use the Apache webserver (httpd) as a frontent for the Gateway (eg forsecurity or fault-tolerance reasons)
Requirements
bull Apache httpd
bull mod_proxy for Apache httpd
External references
bull httpswikieclipseorgJettyHowtoConfigure_mod_proxy
6 Using the Gateway for failover andor loadbalancing of UNI-CORE sites
The Gateway can be used as a simple failover solution andor loadbalancer to achieve highavailability andor higher scalability of UNICOREX sites without additional tools
A site definition (in CONFconnectionsproperties) can be extended so that multiplephysical servers are used for a single virtual site
An example for such a so-called multi-site declaration in the connectionsproperties file looksas follows
declare a multisite with two physical servers
MYSITE=multisitevsites=httpslocalhost7788 httpslocalhost larr7789
This will tell the Gateway that the virtual site MYSITE is indeed a multi-site with the twogiven physical sites
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 19
61 Configuration
Configuration options for the multi-site can be passed in two ways On the one hand they cango into the connectionsproperties file by putting them in the multi-site definition separated by characters
declare a multisite with parameters
MYSITE=multisiteparam1=value1param2=value2param3=value3
The following general parameters exist
vsites List of physical sitesstrategy Class name of the site selection strategy to
use (see below)config Name of a file containing additional
parameters
Using the config option all the parameters can be placed in a separate file for enhancedreadability For example you could define in connectionsproperties
declare a multisite with parameters read from a separate file
MYSITE=multisiteconfig=confmysite-clusterproperties
and give the details in the file confmysite-clusterproperties
example multisite configurationvsites=httpslocalhost7788 httpslocalhost7789
check site health at most every 5 secondsstrategyhealthcheckinterval=5000
62 Available Strategies
A selection strategy is used to decide where a client request will be routed By default thestrategy is Primary with fallback ie the request will go to the first site if it is availableotherwise it will go to the second site
Primary with fallback
This strategy is suitable for a high-availability scenario where a secondary site takes over thework in case the primary one goes down for maintenance or due to a problem This is thedefault strategy so nothing needs to be configured to enable it If you want to explicitely enableit anyway set
strategy=primaryWithFallback
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 20
The strategy will select from the first two defined physical sites The first primary one willbe used if it is available else the second one Health check is done on each request but notmore frequently as specified by the strategyhealthcheckinterval parameter By default thisparameter is set to 5000 milliseconds
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
Round robin
This strategy is suitable for a load-balancing scenario where a random site will be chosen fromthe available ones To enable it set
strategy=roundRobin
Changes to the site health will be logged at INFO level so you can see when the sites go upor down
It is very important to be aware that this strategy requires that all backend sites used in the poolshare a common persistence It is because Gateway does not track clients so particular clientrequests may land at different sites This is typically solved by using a non-default shareddatabase for sites such as MySQL
NoteCurrently loadbalancing of target sites is an experimental feature and is not yet fully functionalIt will be improved in future UNICORE versions
Custom strategy
You can implement and use your own failover strategy in this case use the name of the Javaclass as strategy name
strategy=your_class_name
7 Gateway failover and migration
The Section 6 covered usage of the Gateway to provide failover of backend services Howeverit may be needed to guarantee high-availabilty for the Gateway itself or to move it to othermachine in case of the original onersquos failure
71 Gatewayrsquos migration
The Gateway does not store any state information therefore its migration is easy It is enoughto install the Gateway at the target machine (or even to simply copy it in the case of installation
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-
UNICORE Gateway 21
from the core server bundle) and to make sure that the original Gatewayrsquos configuration ispreserved
If the new machine uses a different address it needs to be reflected in the serverrsquos configurationfile (the listen address) Also the configuration of sites behind the Gateway must be updatedaccordingly
72 Failover and loadbalancing of the Gateway
Gateway itself doesnrsquot provide any features related to its own redundancy However as it isstateless the standard redundancy solutions can be used
The simpliest solution is to use Round Robin DNS where DNS server routes the GatewayrsquosDNS address to a pool of real IP addresses While easy to set up this solution has a significantdrawback DNS server doesnrsquot care about machines being down
The much better choice is to use the Linux-HA software suite often known under the name ofits principal component the heartbeat For details see httpwwwlinux-haorg
Additionally a more advanced HTTP-aware software can be used such as HA-Proxy (httphaproxy1wteu)Currently Gateway and UNICORE donrsquot maintain HTTP sessions so usage of the HTTP-awareload-balancer is not strictly required but such solutions generally provide more general purposefeatures
8 Building the Gateway from source
To checkout the latest version of the Gateway source code do
svn co httpsvncodesfnetpunicoresvngatewaytrunk gateway
You will need to install Maven from httpmavenapacheorg Compile using
mvn install
which compiles the code and runs the tests
The file README-buildingtxt contains instructions for building distributable packages
- Introduction
- Installation
-
- Installation from the core server bundle
- Installation from a Linux package (rpm or deb)
-
- Upgrading
- Configuration
-
- Java and environment settings startupproperties
- Configuring sites connectionsproperties
- Main server settings gatewayproperties
- Require end-user certificates
- Logging
-
- Using Apache httpd as a frontend
- Using the Gateway for failover andor loadbalancing of UNICORE sites
-
- Configuration
- Available Strategies
-
- Gateway failover and migration
-
- Gateways migration
- Failover and loadbalancing of the Gateway
-
- Building the Gateway from source
-