• Home

  • Documents

  • UNICORE G · In this way, only a single open port in a site’s firewall has to be configured....
23
UNICORE Gateway UNICORE G ATEWAY UNICORE Team Document Version: 1.1.0 Component Version: 8.0.3 Date: 29 04 2020 This work is co-funded by the EC EMI project under the FP7 Collaborative Projects Grant Agreement Nr. INFSO-RI-261611.

UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

  • Upload
    others

  • View
    0

  • Download
    0

Embed Size (px)

Citation preview

Page 1: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 2: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 3: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 4: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 5: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 6: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 7: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 8: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 9: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 10: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 11: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 12: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 13: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 14: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 15: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 16: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 17: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 18: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 19: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 20: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 21: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 22: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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
Page 23: UNICORE G · In this way, only a single open port in a site’s firewall has to be configured. LIMITATIONS This forwarding process only works for “most” HTTP requests, and is

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

Migrating Unicore Network Packet Processing Applications to Multicore

Migrating Unicore Network Packet Processing Applications to Multicore

Documents
UNICORE TSI: Manual · 2014. 7. 11. · UNICORE TSI: Manual 1 1Overview The UNICORE TSI is a Perl daemon running on the frontend of the target resource (e.g. a cluster login node)

UNICORE TSI: Manual · 2014. 7. 11. · UNICORE TSI: Manual 1 1Overview The UNICORE TSI is a Perl daemon running on the frontend of the target resource (e.g. a cluster login node)

Documents
General Introduction to UNICORE 6

General Introduction to UNICORE 6

Documents
Amsterdam, 28 June 2006DEISA UNICORE tutorial UNICORE and the DEISA supercomputing grid Jules Wolfrat wolfrat@sara.nl

Amsterdam, 28 June 2006DEISA UNICORE tutorial UNICORE and the DEISA supercomputing grid Jules Wolfrat [email protected]

Documents
UNICORE TSI: ManualUNICORE TSI: Manual UNICORE TSI: MANUAL UNICORE Team Document Version: 1.0.0 Component Version: 7.2.0 Date: 08 12 2014 This work is co-funded by the EC EMI project

UNICORE TSI: ManualUNICORE TSI: Manual UNICORE TSI: MANUAL UNICORE Team Document Version: 1.0.0 Component Version: 7.2.0 Date: 08 12 2014 This work is co-funded by the EC EMI project

Documents
Table of Contents - UNICORE€¦ · UNICORE’s modular architecture and open-source character provide for ease of extensibility. Scalable Multiple UNICORE installations can be combined

Table of Contents - UNICORE€¦ · UNICORE’s modular architecture and open-source character provide for ease of extensibility. Scalable Multiple UNICORE installations can be combined

Documents
Online retrieval, evaluation and UNICORE 6 workflow system

Online retrieval, evaluation and UNICORE 6 workflow system

Documents
Table of Contents - UNICORE€¦ · Scalable Multiple UNICORE installations can be combined to form a distributed, multi-organizational Grid allowing for thousands of jobs. April

Table of Contents - UNICORE€¦ · Scalable Multiple UNICORE installations can be combined to form a distributed, multi-organizational Grid allowing for thousands of jobs. April

Documents
Installation Guide for UNICORE Server Components · Installation Guide for UNICORE Server Components ... Slurm, etc. This document is ... Installation Guide for UNICORE Server Components

Installation Guide for UNICORE Server Components · Installation Guide for UNICORE Server Components ... Slurm, etc. This document is ... Installation Guide for UNICORE Server Components

Documents
Web application firewall - Netsparker

Web application firewall - Netsparker

Documents
Case Study - V4 · Catalyst 3850 Series Switches and an ASA 5515X firewall, fully configured with a VPN tunnelled back to the Rathbone Place HQ. Connected Homes also took the opportunity

Case Study - V4 · Catalyst 3850 Series Switches and an ASA 5515X firewall, fully configured with a VPN tunnelled back to the Rathbone Place HQ. Connected Homes also took the opportunity

Documents
GLOBUS UNICORE

GLOBUS UNICORE

Documents
Code Compaction for UniCore on Link-Time Optimization Platform

Code Compaction for UniCore on Link-Time Optimization Platform

Documents
A Unicore Globus Interoperability Layerzzcgukj/D4.1b_draft.pdfA Unicore Globus Interoperability Layer (Draft of a Use Case Study for GPA WG This draft is subject to review and revision)

A Unicore Globus Interoperability Layerzzcgukj/D4.1b_draft.pdfA Unicore Globus Interoperability Layer (Draft of a Use Case Study for GPA WG This draft is subject to review and revision)

Documents
Vision of UNICORE – UniGrids and beyond

Vision of UNICORE – UniGrids and beyond

Documents
Mignis: A semantic based tool for firewall configurationpadao/projects/ComFormCrypt… · Mignis: A semantic based tool for firewall configuration P. Adao˜ SQIG, Instituto de

Mignis: A semantic based tool for firewall configurationpadao/projects/ComFormCrypt… · Mignis: A semantic based tool for firewall configuration P. Adao˜ SQIG, Instituto de

Documents
UNICORE - Dipartimento di Matematica e Applicazioni

UNICORE - Dipartimento di Matematica e Applicazioni

Documents
UNICORE and EUROGRID: Grid Computing in EUROPE

UNICORE and EUROGRID: Grid Computing in EUROPE

Documents
The UNICORE GRID Project

The UNICORE GRID Project

Documents
Grid and Cloud Computing UNICORE

Grid and Cloud Computing UNICORE

Documents
Scientific Computing with UNICORE - Inventive

Scientific Computing with UNICORE - Inventive

Documents
UNICORE and the DEISA supercomputing grid

UNICORE and the DEISA supercomputing grid

Documents
UNICORE OPTIMIZATION William Jalby · independent instructions Key unicore performance ... the hardware will try to overlap ... front end, now a major issue

UNICORE OPTIMIZATION William Jalby · independent instructions Key unicore performance ... the hardware will try to overlap ... front end, now a major issue

Documents
Unicore-UniGrids: Activities and strategies for Open Source Grids

Unicore-UniGrids: Activities and strategies for Open Source Grids

Documents
UNICORE in XSEDE: The Journey Down the Road Less Traveled By UNICORE Summit 30 May 2012

UNICORE in XSEDE: The Journey Down the Road Less Traveled By UNICORE Summit 30 May 2012

Documents
UNICORE-based Workflows for the Simulation of Organic ... · MMM@HPC project overview 25/05/2012 Stefan Bozic – UNICORE Summit - University of Technology, Dresden - 30 May 2012

UNICORE-based Workflows for the Simulation of Organic ... · MMM@HPC project overview 25/05/2012 Stefan Bozic – UNICORE Summit - University of Technology, Dresden - 30 May 2012

Documents
Perspectives for RESTful services in UNICORE · UNICORE Summit 2014, Leipzig, 24 June 2014 Slide 2 Outline Motivation and Human Brain use case WS(RF) vs RESTful UNICORE Services Environment

Perspectives for RESTful services in UNICORE · UNICORE Summit 2014, Leipzig, 24 June 2014 Slide 2 Outline Motivation and Human Brain use case WS(RF) vs RESTful UNICORE Services Environment

Documents
Einsatz von UNICORE in Rechenzentren · UNICORE UNIform Access to COmputing REsources Site: a resource such as an HPC system including storage Job: submitted through JSDL including

Einsatz von UNICORE in Rechenzentren · UNICORE UNIform Access to COmputing REsources Site: a resource such as an HPC system including storage Job: submitted through JSDL including

Documents
GRIP: Interoperability between UNICORE and Globus

GRIP: Interoperability between UNICORE and Globus

Documents
Office suite and firewall - Netfilter · Office suite and firewall É. Leblond Stamus Networks 2016 June 27 É. Leblond (Stamus Networks) Office suite and firewall 2016 June 27

Office suite and firewall - Netfilter · Office suite and firewall É. Leblond Stamus Networks 2016 June 27 É. Leblond (Stamus Networks) Office suite and firewall 2016 June 27

Documents