emurestapi

Configuration

The emurestapi server is a multi-threaded, multi-tenanted shim providing an EMu compatible API to any number of EMu clients. A separate shim is not required for each EMu client, nor must the EMu clients exist on the same machine the shim is installed. The system can be configured at two levels. The first is at the server level where options affect the operation of the server. The second is at the tenant level where options can be set on a per tenant basis.

Tenants

The restapi/conf/tenants.conf file defines the EMu environments appearing as EMu tenants. The file is in HOCON format (a superset of JSON). The file contains an outer property called tenants with an array of tenant entries as its value.

tenants = [
  {
    # tenant 1
  },
  {
    # tenant 2
  },
  ...
]

Each tenant entry consists of a number of properties and values. Each property is described below.

tenant

The label to use for the tenant. It is the name used for the first component in an EMu URI (emu://{tenant}/{resource}/{id}). The value does not have to be the same as that used by the corresponding EMu environment, however it generally makes sense to do so.

hostname

The hostname or IP address of the EMu server containing the tenant environment. If the EMu client is on the same machine as the shim then localhost may be used. The address defines which server has the texserver listening for incoming connections for the given EMu client.

port

The port number to use to connect to the EMu server with the given hostname. A number must be used as service names are not supported. The combination of the hostname and port must have an EMu server listening for connections.

irn

The IRN in the EMu eparties table of the record containing the tenant information. The information includes the tenant’s:

  • name (NamOrganisation)
  • email address (AddEmail)
  • url (AddWeb)
  • street address (AddPhysAddress)
  • postcode (AddPhysCode)
  • region (AddPhysState)
  • country (AddPhysCountry)

The information is used to synthesise tenant records for GET /shared/tenants and GET /shared/tenants/{tenant} requests.

signedKey

The secret key used to sign JWT (Java Web Token) tokens. The key is a random 64 digit long hex number known only to the shim and any service wishing to validate the JWT. Please keep it secret as it is effectively a password. A random key can be generated by running openssl rand -hex 32.

passcodeKey

The secret key used to encrypt/decrypt a passcode. A passcode is an encrypted string that can be used in place of a username/password pair or an OpenID Connect token to authenticate with the server. The key is a random 32 digit long hex number. The key should be kept secret as it can be used to decode a passcode and so access sensitive information (e.g. password). A random key can be generated by executing openssl rand -hex 16.

timeout

The number of minutes before a JWT is timed out. Once a token is timed out it can no longer be used, effectively logging the user out. The timeout on a token is reset each time the token is used validly. The value is optional with a default value of 30 minutes.

cursorType

The type of cursor to use for paging results. If a query specifies the limit query parameter then the results may be returned in a series of pages (each with an optional limit). The shim supports two types of paging cursors. The first is file which saves the IRNs of all matching records in a file and returns records based on the file contents and Next-Search header. File based cursors do not use any server resources and can have very long timeout values. The second type of cursor is server. A server cursor maintains a Texpress cursor and so uses resources on the server machine. The cursor is a little faster than a file based cursor but requires shorter timeouts (typically around 15 min, compared to many hours for file based cursors). The value is optional with a default value of file.

localMedia

When retrieving multimedia repository files a call is made to the EMu server to transfer the file from the server to the local machine and then stream the file in the response. If the EMu server and this server reside on the same machine then rather than performing the transfer the multimedia repository may be accessed directly, removing the need to transfer the file. A “true” value enables the use of a local multimedia repository, while a “false” value forces the file transfer. The default value is true.

legacy

Legacy mode alters the JSON Schema generated for a resource. The JSON Schema definition for a resource reflects the logical layout of the data as stored in JSON. When a multi-column nested table (or multi-column grid) is found it is encoded as an array where each entry in the array is a JSON object where each property reflects one of the nested columns. In other words the layout is as you would expect for a multi-column nested table/grid, as you can see the relationship between the various columns. If legacy mode is enabled then multi-column nested tables are broken apart and each column is independent of the other. It is not possible to determine how the columns are related from the JSON Schema. User knowledge is required when designing clients to somehow put the columns back together. Legacy mode should only be used by “legacy” projects. New projects should not enable legacy mode as schema definition information is lost which can lead to data misalignment if care is not taken. Legacy mode is disabled by default.

An example configuration containing two tenants:

tenants = [
  {
    tenant = museum
    hostname = localhost
    port = 20009
    irn = 100085
    signedKey = 955F38A2C240F840D6D65AC584563F11A37713B454B68D1F69E0D69B5FA5270E
    passcodeKey = 138ead4a34ebebc5a6d9210435ff3875
    timeout = 30
    cursorType = server
  },
  {
    tenant = mv
    hostname = swanston.melbourne.axiell.com
    port = 20011
    irn = 102374
    signedKey = 3C3410AC9AB3B72BC72C1E4EC925FFEC3DFA4CBDC26F4377F483F5C4189AF310
    passcodeKey = 9c88bb456f3a1ab766f3beddead89afe
    timeout = 60
    legacy = true
  }
]

The emurestapi shim reads the tenants.conf file when it starts up and caches the data. If changes are made to the tenant’s file then the shim must be restarted or the PATCH /shared/tenants request issued to force the tenant’s file to be re-read.

Server

The server based configuration settings are found in restapi/conf/restapi.conf. The file format is also HOCON with simple property=value settings. Each property can be set three ways. The first is to change the value in the restapi.conf file itself. The second is to set a Java property on the command line using the -D option and the third is setting an environment variable.

Each setting has the form:

setting = "value"
setting = ${?emurestapi.setting}
setting = ${?EMURESTAPI}

where the first entry contains the actual value. The second entry defines the Java property name (emurestapi.setting) and the third entry states the environment variable name (EMURESTAPI_SETTING). When changing values in the restapi.conf file only the first entry should be modified. The order of preference from lowest to highest is a file entry is overridden by a Java property which in term is overridden by an environment variable.

On FreeBSD based machines the preferred way of altering a setting is to use the emurestapi_args variable in /etc/rc.conf. For example to change the value of emurestapi.port to 9094 the following entry should be added to /etc/rc.conf:

emurestapi_args="-Demurestapi.port=9094"

Note the -D option is required when setting Java properties.

On a Linux (systemd) machine the preferred method of changing a setting is via environment variables. To add environment variables for the emurestapi service run systemctl edit emurestapi.service and add the variables to the opened file. For example to change the value of TEXRESTAPI_PORT to 9094 the following entry is required:

[Service]
Environment="TEXRESTAPI_PORT=9094"

In general its recommended server level settings are set as either Java properties or environment variables rather than modifying the restapi.conf file itself. Such an approach ensures settings are maintained when the software is updated.

The following server level variables may be set:

interface = “0.0.0.0”
interface = ${?emurestapi.interface}
interface = ${?EMURESTAPI_INTERFACE}

The IP address of the interface the server should listen for connections on. A value of 0.0.0.0 indicates all interfaces on the local machine should be used. The default value is 0.0.0.0

port = 8084
port = ${?emurestapi.port}
port = ${?EMURESTAPI_PORT}

The port the server should listen on for connections. A number must be used as service names are not supported. The default port is 8084.

requestTimeout = 10 requestTimeout = ${?emurestapi.requestTimeout} requestTimeout = ${?EMURESTAPI_REQUESTTIMEOUT}

The number of minutes in which a request must be serviced. If the request does not send a response in the specified time then the request is cancelled and the connection aborted. The timeout value may need to be increased if large media files are uploaded as the upload time may be considerable. The default value is 10 minutes.

reaperTime = 10
reaperTime = ${?emurestapi.reaperTime}
reaperTime = ${?EMURESTAPI_REAPERTIME}

The number of seconds between each check for expired tokens. A check takes place every reaperTime seconds to see if any JWT tokens have timed out. If a token has expired it is removed from the system effectively logging the user out. Each token has a connection to a Texpress server so when the token is deleted the connection is closed. The default value is 10 seconds.

cursorType = file
cursorType = ${?emurestapi.cursorType}
cursorType = ${?EMURESTAPI_CURSORTYPE}

The default type of cursor use. Two paging cursor types are supported. The first is file which uses a temporary file to maintain a list of all matching records, and the second is server which maintains a Texpress cursor containing the matching records. A server cursor is faster, but uses more resources and has a short timeout period, while a file cursor is slower but may have a very long timeout period. The default value is file.

serverCursorTimeout = 15
serverCursorTimeout = ${?emurestapi.serverCursorTimeout}
serverCursorTimeout = ${?EMURESTAPI_SERVERCURSORTIMEOUT}

The number of minutes a server based cursor is valid. A server cursor contains a list of matching records on a Texpress cursor. The cursor uses system resources so needs to be released in a reasonable time frame. The cursor is released when all matches are retrieved or serverCursorTimeout minutes after the cursor was last accessed. The default value is 15 minutes.

fileCursorTimeout = 4
fileCursorTimeout = ${?emurestapi.fileCursorTimeout}
fileCursorTimeout = ${?EMURESTAPI_FILECURSORTIMEOUT}

The number of hours a file based cursor is valid. When a file paging cursor is created (via the limit query parameter to a GET request) temporary files are used to hold state information. These files need to be purged from time to time. The value is the number of hours a cursor file is kept before being removed. Once the file is removed the cursor can no longer be accessed. The default value is 4 hours.

fileCursorRetry = 500
fileCursorRetry = ${?emurestapi.fileCursorRetry}
fileCursorRetry = ${?EMURESTAPI_FILECURSORRETRY}

The number of milliseconds between checking for new matching records added to a file based cursor. Since searches proceed in the background matches may not be available when a request for more records arrives. A simple polling mechanism is used while waiting for matches to arrive. The fileCursorRetry setting is the time to wait between retries. The default value is 500 milliseconds.

shutdownTime = 3
shutdownTime = ${?emurestapi.shutdownTime}
shutdownTime = ${?EMURESTAPI_SHUTDOWNTIME}

The number of seconds to delay after a shutdown command is issued before the server terminates. A value greater than zero is recommended to allow time for a response to the shutdown command to be transmitted and any outstanding requests to complete. The default value is 3 seconds.

log = false
log = ${?emurestapi.logging}
log = ${?EMURESTAPI_LOGGING}

Each request may be logged by enabling this option. Only the request URL and the response status is logged. If extra information is required then the logHeaders and logBody options should also be enabled. The default value is false.

logHeaders = false
logHeaders = ${?emurestapi.logHeaders}
logHeaders = ${?EMURESTAPI_LOGHEADERS}

The logging of HTTP headers may be enabled for debugging purposes on development systems. It is recommended this setting is NOT enabled on production systems as it affects performance and may result in sensitive information being displayed. The default value is false.

logBody = false
logBody = ${?emurestapi.logBody}
logBody = ${?EMURESTAPI_LOGBODY}

The logging of the body of a HTTP message may be enabled for debugging purposes. Logging should not be enabled on production systems as it impacts performance and may result in sensitive data being displayed. Large amounts of logging data may be generated when this setting is enabled. The default value is false.

admin = emu
admin = ${?emurestapi.admin}
admin = ${?EMURESTAPI_ADMIN}

The user name of the administrator account. The administrator account is allowed to access all aspects of the server, including shutting it down and accessing all tokens. The user name must be registered with the server either in the passwd file, via LDAP or OpenID Connect. The default user name is emu.

Next: Markup