Reference
SHRINE uses the Typesafe Config library to parse config files. SHRINE's config files are expressed in HOCON, a superset of JSON. A detailed description of this config file format follows.
Shrine.conf
Supported Data Types
Basic: Booleans, and Strings, and Integers
For example:
isQueryable = true setSizeObfuscation = false shrineDatabaseType = "mysql" adapterLockoutAttemptsThreshold = 42
Durations
Durations in older parts of the code are specified as a block containing a single numeric property with a name of either milliseconds, seconds, minutes, hours, or days. For example :
maxSignatureAge { days = 5 } maxQueryWaitTime { minutes = 0.5 }
In 1.23 we will convert all of these blocks to a format that matches Typesafe Config and Scala Durations
maxSignatureAge = "5 days" maxQueryWaitTime = "30 seconds"
Endpoints
Endpoints are URLs with parameters, specified as blocks with the following properties:
- url (mandatory string): the URL of the endpoint
- acceptAllCerts (optional boolean, default is false): determines whether SSL certs should be checked, or if all certs should be accepted regardless of being self-signed, expired, etc. (Useful for testing with self-signed certs).
- timeout (optional duration, default is infinity): how long should clients wait for responses from this endpoint before throwing an exception.
For example:
crcEndpoint { url = "http://example.com/i2b2" } crcEndpoint { url = "http://example.com/i2b2" acceptAllCerts = true timeout { minutes = 1 } }
Credentials
Credentials are specified as blocks with the following properties:
- domain (optional string): the user's domain, if any
- username (mandatory string): the user's username
- password (mandatory string): the user's password
For example:
sheriffCredentials { username = "sheriffUsername" password = "sheriffPassword" } fooCredentials { domain = "shrine" username = "foo" password = "bar" }
i2b2 Hive Credentials
i2b2 hive credentials for use with a CRC or other i2b2 cell are specified as blocks with the following properties:
domain (mandatory string): the user's i2b2 domain
- username (mandatory string): the user's username
- password (mandatory string): the user's password
- crcProjectId (mandatory string): the user's i2b2 project id for use when logging into the CRC
- ontProjectId (mandatory string): the user's i2b2 project id for use when logging into the Ontology cell
For example:
hiveCredentials { domain = "HarvardDemo" username = "demo" password = "demouser" crcProjectId = "Demo" ontProjectId = "SHRINE" }
Keystore Parameters
Keystore parameters are expressed using a block with the following properties:
- file (mandatory string): the name of the keystore file on the classpath
- password (mandatory string): the keystore's passwordkeystoreType (String, default is 'JKS'): the type of the keystore. Allowed values are 'JKS' and 'PKCS12'.
- privateKeyAlias (optional string): In the keystore, the alias of the cert with private key component used to identify this node. The cert with this alias will be used to sign outbound queries.
- keyStoreType (optional string): A string describing the format of the keystore. Allowed values are 'JKS' and 'PKCS12'; the default is 'PKCS12'.
- caCertAliases (optional array of strings): In the keystore, the aliases, if any certs belonging to certificate authorities this node should trust
For example:
keystore { file = "shrine.keystore" password = "changethisplease" privateKeyAlias = "test-cert" keyStoreType = "PKCS12" caCertAliases = [shrine-ca, some-other-ca] }
SHRINE Proxy
The SHRINE proxy is configured by a block with a single property, timeout, a duration. Timeout specifies the amount of time the proxy should wait for a response from the url being proxied. The default is to wait forever.
For example:
proxy { timeout { minutes = 5 } }
Shrine.conf Example
An example shrine.conf can be found here:
Shrine.conf Property Reference
- hiveCredentials (mandatory i2b2 credentials block): The credentials to use when talking to the i2b2 hive.
- pmEndpoint (mandatory endpoint block): An endpoint containing the URL of the i2b2 PM cell SHRINE should authenticate users against.
- ontEndpoint (mandatory endpoint block): An endpoint containing the URL of the i2b2 ontology cell SHRINE should communicate with.
- networkStatusQuery (mandatory string): A string representing a term from the SHRINE ontology that should be used when making test queries to verify the status of the adapter.
- humanReadableNodeName (mandatory string): A string containing the descriptive name this node should use to identify itself.
- shrineDatabaseType (mandatory string): A name identifying the type of database system used by SHRINE. (Note that this is distinct from the i2b2 db.) Allowed values are 'mysql', 'oracle', and 'sqlserver'.
- keystore (mandatory keystore block): parameters pertaining to this node's keystore.
- adapterConfig (optional adapter config block): used if this node is an adapter.
- hubConfig (optional hub config block): used if this node is a hub (broadcaster).
- queryEntryPointConfig (optional entry point config block): used if queries can originate from this node.
- proxyConfig (optional proxy config block): optionally used to configure the SHRINE proxy.
- breakdownResultOutputTypes (optional block): describes breakdown result output types; must match i2b2
Adapter Config
If a node is an adapter, add an adapter block to shrine.conf:
adapter { create = true ... }
Adapter Config Property Reference
- create (boolean, default is true): true to create an adapter at this node.
- crcEndpoint (optional endpoint block): the location of the i2b2 CRC this SHRINE node should run queries against, if this node is queryable.
- setSizeObfuscation (mandatory boolean): should this node obfuscate results obtained from the CRC.
- adapterLockoutAttemptsThreshold (mandatory integer): How many times should a user be able to run the same query in the recent past before they are prevented from making further queries.
- adapterMappingsFileName (mandatory string): The name of a file on the classpath that SHRINE should load to obtain mappings between terms in the SHRINE and local i2b2 ontologies. Usually, this is called 'AdapterMappings.xml'.
- maxSignatureAge (mandatory duration): The length of time the signature on an incoming query should be considered valid. Queries with signatures older than this value will be rejected.
- auidit.database.slickProfileClassName (A Slick driver class name. One of "slick.driver.MySQLDriver$", "freeslick.OracleProfile$", or "freeslick.MSSQLServerProfile$" . Default is "slick.driver.MySQLDriver$" .): The name of the appropriate Slick driver for your JDBC driver.
For example:
adapter { crcEndpoint { url = "http://services.i2b2.org/i2b2/rest/QueryToolService/" acceptAllCerts = true timeout { seconds = 1 } } setSizeObfuscation = true adapterLockoutAttemptsThreshold = 10 adapterMappingsFileName = "AdapterMappings.xml" maxSignatureAge { minutes = 5 } }
Hub (Broadcaster) Config
If a node is a hub (broadcaster), add a hub block to shrine.conf:
hub { create = true ... }
Hub Config Property Reference
- create (boolean, default is false): true to create a hub at this node.
- maxQueryWaitTime (mandatory duration): When querying, how long to wait for results from all downstream nodes before timing out.
- downstreamNodes (optional downstream node block): a mapping of node names to URLs of downstream nodes. Nodes in this mapping will have queries broadcast to them. If this property is omitted, the node will not broadcast queries to any other nodes.
- shouldQuerySelf (optional boolean, default is false): If this value is true, the node will proadcast to itself.
For example:
hub { create = true maxQueryWaitTime { minutes = 4.5 } downstreamNodes { "some hospital" = "http://example.com/foo" CHB = "http://example.com/chb" PHS = "http://example.com/phs" } shouldQuerySelf = true }
Query Entry Point Config
If a node is an entry point—a node that can receive queries from a web UI and perform them on the network—add a queryEntryPoint block to shrine.conf:
queryEntryPoint { create = true ... }
Query Entry Point Config Reference
- create (boolean, default is true): true to create a query entry point at this node.
- authenticationType (optional authentication type, default is "pm"): Describes how the query entry point should authenticate incoming queries
- authorizationType (optional authorization type, default is "none"): Describes how the query entry point should perform additional authorization of incoming queries.
- sheriffEndpoint (optional endpoint block, HMS only): the location of the Shrine Sheriff application to use for authorizing users.
- sheriffCredentials (optional credentials block, HMS only): the credentials to use when authenticating with the Sheriff application, if applicable.
- includeAggregateResults (mandatory boolean): Should this node include an aggregate result with total counts. In the past, this has been false.
- maxQueryWaitTime (mandatory duration): When querying, how long to wait for results from the hub (broadcaster) before timing out.
- broadcasterServiceEndpoint (optional endpoint): An optional endpoint containing the URL of the remote hub (broadcaster) to submit queries to. If this property is omitted, a local broadcaster is used.
- attachSigningCert (optional boolean): An optional boolean describing whether the cert used to sign outgoing queries should be attached to the outbound query. If this value is true, the cert used to sign outbound queries must be signed by a certificate authority that is trusted by the adapters that will receive the query. The default value is false.
- auidit.database.slickProfileClassName (A Slick driver class name. One of "slick.driver.MySQLDriver$", "freeslick.OracleProfile$", or "freeslick.MSSQLServerProfile$" Default is "slick.driver.MySQLDriver$"): The name of the appropriate Slick driver for your JDBC driver.
Authentication types
- "ecommons" (only usable by nodes on the HMS deployment of Shrine): authenticates users against an i2b2 PM and checks that users have a property specifying a Harvard ecommons username)
- "pm": authenticates users against an i2b2 PM
- "none": no authentication of incoming queries is performed
Note: the "ecommons" and "pm" authentication schemes will use the i2b2 PM described by the shrine.pmEndpoint property.
Authorization types
- "shrine-steward": use the SHRINE Data Steward introduced in SHRINE 1.19.x. Requires deployment and configuration of steward.war as well as Tomcat 7 or newer. The shrineSteward block in shrine.conf must also be set up properly.
- "hms-steward" (only usable by nodes on the HMS deployment of Shrine): use a data steward (Sheriff) instance to authorize incoming queries. For this to work, the sheriffEndpoint and sheriffCredentials properties must be set.
- "none": Don't perform additional authorization of incoming queries.
Note: the "hms-steward" authorization type is compatible ONLY with the "ecommons" authentication type.
For example:
queryEntryPoint { authenticationType = "pm" authorizationType = "shrine-steward" // BEGIN properties for hms-steward // sheriffEndpoint { // url = "http://localhost:8080/shrine-hms-authorization/queryAuthorization" // acceptAllCerts = true // timeout { // seconds = 1 // } // } // // sheriffCredentials { // username = "sheriffUsername" // password = "sheriffPassword" // } // END properties for hms-steward // BEGIN properties for shrine-steward shrineSteward { qepUserName = "qep" // name of user the steward will submit queries as qepPassword = "trustme" stewardBaseUrl = "https://localhost:6443" // typically hostname+port of Tomcat server running steward.war } // END properties for shrine-steward includeAggregateResults = false maxQueryWaitTime { minutes = 5 } broadcasterServiceEndpoint { url = "http://example.com/shrine/rest/broadcaster/broadcast" acceptAllCerts = true timeout { seconds = 1 } } attachSigningCert = true }
Breakdown Result Output Types Config
As of Shrine 1.18.0+, it is required to specify the names of result types corresponding to breakdown queries. There names must match the names of result output types defined in the i2b2 DB of every node on your Shrine network. For example, on a network comprised of nodes backed by i2b2 demo VMs, add this to shrine.conf:
shrine { ... breakdownResultOutputTypes { PATIENT_AGE_COUNT_XML { description = "Age patient breakdown" } PATIENT_RACE_COUNT_XML { description = "Race patient breakdown" } PATIENT_VITALSTATUS_COUNT_XML { description = "Vital Status patient breakdown" } PATIENT_GENDER_COUNT_XML { description = "Gender patient breakdown" } } ... }
the format is
breakdownResultOutputTypes { <breakdown-result-output-type-name 0> { description = <string human-readable-description 0> } ... <breakdown-result-output-type-name N> { description = <string human-readable-description N> } }
note that shrine.breakdownResultOutputTypes can contain 0 or more child elements.
Since this breakdown result output type information will be shared by many nodes on a network, it's also possible to define it in its own file, breakdowns.conf, which can be shared among sites without revealing URLs or credentials. That file should contain only the enclosing shrine { ... } block and the breakdownResultOutputTypes {... } block, like
shrine { breakdownResultOutputTypes { PATIENT_AGE_COUNT_XML { description = "Age patient breakdown" } PATIENT_RACE_COUNT_XML { description = "Race patient breakdown" } PATIENT_VITALSTATUS_COUNT_XML { description = "Vital Status patient breakdown" } PATIENT_GENDER_COUNT_XML { description = "Gender patient breakdown" } } }
If breakdowns.conf is present and no shrine.breakdownResultOutputTypes block is defined in shrine.conf, values from breakdowns.conf will be used.