EMIR Server Configuration
-------------------------

The EMIR server comes with a well documented configuration file (CONF/emir.config), containing a 
number of options to setup registry hierarchy, p2p, security, http server, and database. The settings in the configuration file 
are pre-defined to start-up the server in a non-production environment, however the administrator needs to review before deploying on the
production Grid environments.    

General Configuration
~~~~~~~~~~~~~~~~~~~~

The server configuration options in the CONF/emir.config are:

	*  Server address (plain or SSL)
	*  Settings of the type of the registry node, i.e. whether the current EMIR server instance
	   is a child of some other (a parent) EMIR server node or a top/global registry in a hierarchy.
	      
[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
4+^e|Server general settings
|emir.address|string|-|The address/URL of the EMIR server on which it receives registration and query requests. It should either start with http or https (SSL/TLS) mode, if "https" mode is selected the Authentication and Authorisation properties must be properly configured
|emir.anonymousPort|Unsigned Integer|-|The anonymous http port number. Setting the property will start an additional 'http' server (without SSL/TLS) only if the above server address is 'https' (with SSL/TLS). It will provide 'anonymous' access to the query interface (i.e. /services REST Web Service).   
|=========================

PKI Trust Settings Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

EMIR endorses Public Key Infrastructure (PKI) trust settings to validate certificates using EMI's https://twiki.cern.ch/twiki/bin/view/EMI/EMIcaNl[caNL] (JAVA version). The validation is performed
when a connection with a remote peer is initiated over the network, using the SSL (or TLS) protocol, i.e. +emir.address+ value has _https_ scheme.

Certificates validation is primarily configured using a set of initially trusted certificates of so called 
Certificate Authorities (CAs). Those trusted certificates are also known as _trust anchors_ and their collection
is called as a _truststore_. 

The validation mechanism except the _trust anchors_ can use additional input for checking if a certificate being checked 
was not revoked and if its subject is in a permitted namesapce.

EMIR allows different types of truststores. All of them are configured using a set of specific properties in _CONF/emir.config_ file.

OpenSSL Truststore
^^^^^^^^^^^^^^^^^^

It allows using a directory with CA certificates stored in PEM format, with precisely
defined names: Certificate Authorities (CA), Certificate Revocation List (CRL), signing policy and namespaces files are named as 
<hash>.0, <hash>.r0, <hash>.signing_policy and <hash>.namespaces respectively. Hash is the old hash of the trusted CA certificate
subject name - in OpenSSL version newer than 1.0.0 use -suject_hash_old switch to generate it. If multiple certificates
have the same hash then the default zero number must be incremented. It is suggested when a common truststore with EMI (and Globus) 
middlewares is needed.

Directory Truststore
^^^^^^^^^^^^^^^^^^^^

It allows to use a list of wildcard expressions, concrete paths of files, or URLs to remote files as a set of trusted 
CAs and CRLs. The truststore is configured as a directory containing all the trusted certificates (or with a 
specified extension). The directory with stored IGTF trust anchors can be set as a EMIR truststore for instance.

Java Keystore (JKS) Truststore
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A single repository (or a binary file) of X.509 public key certificates with (optionally) accompanying private key certificates. 
The Java JDK already bundles http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html[keytool] utility - a certificate manage utility 
to create JKS truststores.

PKCS#12 Truststore
^^^^^^^^^^^^^^^^^^

Similar to JKS trustore, single binary file can be used to store X.509 public with (optionally) accompanying private key certificates. The *OpenSSL pkcs12*
command can be used to parse, read, and create these files; the extension for PKCS#12 files is ".p12".


include::sec-ref-trustProperties.txt[]

Examples
^^^^^^^^

Directory truststore, with a minimal set of options:
	
emir.security.truststore.type=directory
emir.security.truststore.directoryLocations.1=/trust/dir/*.pem
emir.security.truststore.directoryLocations.2=/other/dir/*.pem
emir.security.truststore.crlLocations=/trust/dir/*.crl

Directory truststore, with complete set of options:

 emir.security.truststore.type=directory
 emir.security.truststore.allowProxy=DENY
 emir.security.truststore.updateInterval=1234
 emir.security.truststore.directoryLocations.1=/trust/dir/*.pem
 emir.security.truststore.directoryLocations.2=http://caserver/ca.pem
 emir.security.truststore.directoryEncoding=PEM
 emir.security.truststore.directoryConnectionTimeout=100
 emir.security.truststore.directoryDiskCachePath=/tmp
 emir.security.truststore.crlLocations=/trust/dir/*.crl http://caserver/crl.pem
 emir.security.truststore.crlUpdateInterval=400
 emir.security.truststore.crlMode=REQUIRE
 emir.security.truststore.crlConnectionTimeout=200
 emir.security.truststore.crlDiskCachePath=/tmp

Openssl truststore:

 emir.security.truststore.type=openssl
 emir.security.truststore.opensslPath=path/to/truststores/openssl
 emir.security.truststore.opensslNsMode=EUGRIDPMA_GLOBUS_REQUIRE
 emir.security.truststore.allowProxy=ALLOW
 emir.security.truststore.updateInterval=1234
 emir.security.truststore.crlMode=IF_VALID

Java keystore used as a truststore:

 emir.security.truststore.type=keystore
 emir.security.truststore.keystorePath=path/to/truststores/emir-truststore.jks
 emir.security.truststore.keystoreFormat=JKS
 emir.security.truststore.keystorePassword=xxxxxx


Configuring the Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~

EMIR uses private key and a corresponding certificate (called together as a _credential_) 
to identify clients and servers. The credentials can be provided in several formats. The following table list all possible 
variants and corresponding parameters.

include::sec-ref-credProperties.txt[]

Examples
^^^^^^^^

Credential as a pair of DER files:

 emir.security.credential.format=der
 emir.security.credential.password=emi
 emir.security.credential.path=path/to/credentials/cert-1.der
 emir.security.credential.keyPath=path/to/credentials/pk-1.der

Credential as a JKS file (type can be autodetected in almost every case):

 emir.security.credential.path=path/to/credentials/server1.jks
 emir.security.credential.password=xxxxxx

ACL Based Authorization
~~~~~~~~~~~~~~~~~~~~~~~

The EMIR offers two alternative options to authorise its' clients.

	* Using Access Control List (ACL)
	* XACML Policy based authorization

This is the default mechanism to access control the _Create_,_Update_, and _Delete_ operations on EMIR's SER database. The client SERP or child DSR
registering SERPs with a parent DSR/GSR get authorised while matching it's distinguished name (DN) against the pre-defined ACL file (CONF/emir.acl). 
Whereas the file contains a list of DN and role pairs, separated by *'::'* symbol, see the example below:

the property in the +CONF/emir.config+ file

[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
|emir.security.accesscontrol.acl|filesystem path|CONF/emir.acl|The location of the ACL file
|===========================================================

.Example ACL file contents
-----------------
emailAddress=emiregistry@user.eu,CN=EMIRegistry-Demo-User,OU=JSC,O=Forschungszentrum Juelich GmbH,L=Juelich,C=DE :: serviceowner
emailAddress=emiregistry@user.eu-admin,CN=EMIRegistry-Demo-User-Admin,OU=JSC,O=Forschungszentrum Juelich GmbH,L=Juelich,C=DE :: admin   
-----------------

The public key certificate or DN should be sent to the DSR administrator for successfull SER registrations. 

_Roles:_ There are only two pre-defined roles within the scope of ACL file: 

	* the +admin+ is a super user who can change any registration, owned by anyone, and
	* the +serviceowner+ is only allowed to create new or modify his created SERPs.

IMPORTANT: The ACL based authorisation is only activated when the DSR/GSR is running on SSL/TLS mode


Policy Based Authorization with XACML
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using XACML 2.0 is an alternative way to authorize clients (User, EMIR-SERP, DSR, or GSR) in a fine grained manner. The administrator should 
review the policies defined in the +CONF/xacml2Policies/+ folder and change them according to her infrastructure
needs. However the already defined policies provides a good starting point to the administrators to define/modify the
policies. 

IMPORTANT: the XACML policy based authorization will be ignored, if the ACL based authorisation is activated

In order to enable the XACML based authorization: attribute sources and policies must be configured.

Setting Attribute Sources
^^^^^^^^^^^^^^^^^^^^^^^^^

EMIR only supports file based attribute sources; the client DNs can be included in the attributes file.

.File Attribute Source Settings
[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
|emir.security.attributes.order|string|FILE|This property is a space separated list of attribute source names, which are then configured in detail below. The named attribute sources are queried in the given order.
|emir.security.attributes.FILE.class|string|eu.emi.emir.aip.FileAttributeSource|configuration of the 'FILE' attribute source
|emir.security.attributes.FILE.matching|[strict, regexp]|-|Specifies the matching or client DNs
|emir.security.attributes.FILE.file|filesystem path|CONF/users/testUd-strict.xml or CONF/users/testUd-regexp.xml|The path to the file containing subjects' DNs. The file suffixed with +strict+ use strict checking of DNs, whereas the file suffixed with +regexp+ contain entries using regualr expressions
|===========================================================


Setting XACML Policies
^^^^^^^^^^^^^^^^^^^^^^

.Policy settings
[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
|emir.security.accesscontrol.pdpConfig|filesystem path|CONF/xacml2.config|The path to the XACML2 configuration, containing the rules of executing the policies
|emir.security.accesscontrol.pdp|string|eu.unicore.uas.pdp.local.LocalHerasafPDP|The name of the pdp class to endorse, for the xacml2 policies execution
|===========================================================


The +CONF/xacml2.config+ file contains raw xacml polices, enable EMIR (DSR or GSR) administrators to write their own rules.

MongoDB Database Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The EMIR uses MongoDB to store and index the SER collections. It must be configured and running before deploying any EMIR (DSR or GSR) server.

[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
4+^e|Connection Settings
|emir.mongodb.hostName|string|localhost|Fully qualified host name of the machine on which MongoDB is setup
|emir.mongodb.port|Integer|27017|The port number
4+^e|Database Settings
|emir.mongodb.dbName|string|emiregistry|The name of the database to store the SERP records
|emir.mongodb.colName|string|services|The name of the collection (of the database) in which the records will be stored 
4+^e|Login Settings
|emir.mongodb.userName|string|-|The username to access the MongoDB database 
|emir.mongodb.password|string|-|The password to access the MongoDB database 
|========================= 

For high loads, especially at the GSR level, it is recommended to setup MongoDB http://www.mongodb.org/display/DOCS/Replication[replication] for enhanced scalability and performance.


Building EMIR Network
~~~~~~~~~~~~~~~~~~~~~

EMIR allows building a network of registries participating in a Grid infrastructure or federation. The network can be of type hierarchical 
or Peer-to-Peer (P2P). In an hierarchical network, the SER collections are propagated from leaf DSR node to the top level root node, called GSR.
Each DSR has only one parent, either DSR or GSR to which it pushes it's SER collections. At the root level the P2P network of GSR is formed to replicate
the SER collections among multiple GSRs by referring a pre-configured +Global list+. The global list contains a listing of URLs of all the GSRs, each of which should be able to access the URLs.

[NOTE]  
  The machines running the EMIR servers should be time synchronised, either by NTP or any alternative mechanism
   
    
How to Setup DSR?
^^^^^^^^^^^^^^^^^

In order to build hierarchy of DSRs must be able to propagate the SER collections to any *single* parent DSR or a GSR.

.Parent DSR Settings
[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
4+^e|EMIR's DSR settings
|emir.parentAddress|string|-|The address/URL (http or https) of the EMIR DSR server to which it propagates its SER collection
|=========================

IMPORTANT: Add DN of child DSR into the parent DSRs CONF/emir.acl or CONF/users/testUd-(strict | regsexp).xml

How to Setup GSR?
^^^^^^^^^^^^^^^^^

The root level GSR has two primary functions:

	* aggregation of children DSR SER collections
	* replicating the SER collections among other GSRs (visible of _Global List_)

.GSR Settings
[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
4+^e|General GSR Settings
|emir.global.enable|boolean|false|If set to true, indicating the registry node is global. It will then replicate the state among peer global registries (GSRs), the 'emir.parentAddress' property will be ignored (if enabled), as the root registry should not contain any parent.
|emir.global.sparsity|Unsigned Integer|2|It determines the number of neighbors as a function of the actual number of member nodes of the network.
|emir.global.retry|Unsigned Integer|5|It specifies a number of attempts if communication to another GSR is failed.
|emir.global.etValid|Unsigned Integer|12|Specifies period in hours for checking the entries in the soft state database and strip the expired entries (but still keeps them).
|emir.global.softStateDelay|Integer|2|Extend the expiration time with this time delay in hours.
|emir.global.etRemove|Integer|24|Specifies period in hours for checking the entries in the soft state database and remove the expired entries.
4+^e|Global List Settings
|emir.global.providerList|URL or filesystem path|-|Link to the document listing GSR URLs. The URL(s) is/are important for building the GSR's P2P network at the global level.
|=========================

IMPORTANT: Add DN of child DSR into the GSRs CONF/emir.acl or CONF/users/testUd-(strict | regsexp).xml


Service Endpoint Record (SER) Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Setting Service Endpoint Records (SER) Lifetime
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In EMIR, every SER has associated lifetime or (Time-To-Live) TTL. The settings can be defined in DSR or GSR to restrict the maximum assignable lifetime and assign default lifetime if missing from the registration.

.SER TTL Settings
[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
|emir.record.expiryMaximum|Unsigned Integer (in days)|-|Maximum assignable lifetime for the SERs containing the Service_ExpireOn property, defined in days, minimum value: 1.
|emir.record.expiryDefault|Unsigned Integer (in days)|-|The default lifetime will be set from the given property if the incoming registration is without the Service_ExpireOn attribute.
|===========================================================

Filtering Service Endpoint Records (SER)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

EMIR offers a way to block 

	* SERs from being registered via DSR or EMIR-SERP
	* SERs from being propagated to it's parent DSR or GSR

.SER Filter Settings
[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
|emir.record.blockList.incoming|filesystem path|CONF/inputfilters|The file containing list of SER IDs, matching services will be blocked from registration to it's index
|emir.record.blockList.outgoing|filesystem path|CONF/outputfilters|The file containing list of SER IDs, matching services will be blocked from propagation to it's parent DSR
|===========================================================

Validation of Mandatory Attributes 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Usually the DSR or GSR does not allow the SER to be registered(or updated) without having mandatory attributes. 
This validity check can be disabled to allow the publishers to register a SER with custom attributes to 
the EMIR server. Hence providing a flexibility to the publishers, whereas the consumers have to examine 
all the attributes while performing some operation on the service (contained in the SER) itself. 

.Enable/Disable Validity Checks 
[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
|emir.record.attributeCheckingMode|String|strict|There are two possible modes: 'strict' or 'flexible'. If set to 'strict' the emir server will check mandatory attributes in the record being updated or registered. If set to 'flexible' only SERVICE_ENDPOINT_ID will be checked.
|===========================================================

Logging Configuration
~~~~~~~~~~~~~~~~~~~~~~

The EMIR server uses http://logging.apache.org/log4j/1.2/index.html[log4j] to provide log facilities to record all but some of the server activities. In order to 
change the logging configuration, CONF/log4j.properties should be reviewed by the administrator.




Advanced HTTP Server Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

EMIR uses Eclipse's Jetty server to host REST Web services. Following table lists the important properties.

IMPORTANT: Do not set *emir.jetty.requireClientAuthn* and *emir.jetty.wantClientAuthn*  in CONF/emir.config file, as they are automatically set by the EMIR server on start-up.

include::sec-ref-jettyProperties.txt[]