CARTA configuration schema

Schema defining configuration options for the CARTA server

carta_config

type

object

properties

  • $schema

Reference to configuration schema file

type

string

  • authProviders

AuthProviders

Configuration option for authentication providers

type

object

default

pam

publicKeyLocation

/etc/carta/carta_public.pem

privateKeyLocation

/etc/carta/carta_private.pem

issuer

carta

properties

  • google

Google AuthProvider

Google AuthProvider

  • pam

PAM AuthProvider

Local AuthProvider

  • ldap

LDAP AuthProvider

LDAP AuthProvider

  • external

External AuthProvider

External AuthProvider

  • oidc

OpenID Connect AuthProvider

OpenID Connect AuthProvider

  • database

Database configuration

type

object

default

uri

mongodb://localhost:27017

databaseName

CARTA

properties

  • uri

MongoDB connection URI used to connect to a MongoDB deployment

type

string

pattern

^mongodb://

default

mongodb://localhost:27017

format

uri

  • databaseName

Default database to connect to

type

string

default

CARTA

additionalProperties

False

  • serverPort

Port to listen on. It is advised to listen on a port other than 80 or 443, behind an SSL proxy

type

integer / string

examples

8000

8080

/run/carta-controller

var/run/carta

maximum

65535

minimum

0

minLength

2

default

8000

  • serverInterface

Host interface to listen on. If empty, all interfaces are used

type

string

examples

localhost

127.0.0.1

  • httpOnly

Allow HTTP-only connections. For testing or internal networks only

type

boolean

default

False

  • serverAddress

Public-facing server address. If this is specified, all requests will be redirected to this address, otherwise any address used will be preserved

type

string

format

uri

  • dashboardAddress

Optional parameter for explicitly configuring the dashboard address. This can be absolute or relative. This is required if running the controller on a subdirectory

type

string

examples

https://my-server.com/carta/dashboard

/carta/dashboard

/carta-versions/dev/dashboard

format

uri-reference

  • apiAddress

Optional parameter for explicitly configuring a custom API base address. This can be absolute or relative. This is required if running the controller on a subdirectory

type

string

examples

https://my-server.com/carta/api

/carta/api

/carta-versions/dev/api

format

uri-reference

  • frontendPath

Path to the built frontend folder. If no path is provided, the packaged version will be used

type

string

  • backendPorts

Port range to use for the CARTA backend process

type

object

default

min

3003

max

3500

properties

  • min

type

integer

maximum

65535

minimum

1024

  • max

type

integer

maximum

65535

minimum

1024

additionalProperties

False

  • processCommand

Path to CARTA backend executable

type

string

examples

/usr/bin/carta_backend

/usr/local/bin/carta_backend

default

/usr/bin/carta_backend

  • preserveEnv

Use the –preserve-env argument when calling sudo

type

boolean

default

True

  • killCommand

Path to CARTA kill script

type

string

examples

/usr/local/bin/carta-kill-script

default

/usr/local/bin/carta-kill-script

  • rootFolderTemplate

Top-level path of directories accessible to CARTA. The {username} placeholder will be replaced with the username. Defaults to /usr/share/carta if it exists, or /usr/local/share/carta if it exists. If neither exists and no default is provided, the controller exits with an error

type

string

examples

/home/{username}

/

  • baseFolderTemplate

Starting directory of CARTA. Must be a subfolder of rootFolderTemplate. The {username} placeholder will be replaced with the username. Defaults to the same value as rootFolderTemplate

type

string

examples

/home/{username}/CARTA

/data

/

  • logFileTemplate

Location of log file. The {username}, {pid} and {datetime} placeholders will be replaced with the username, process ID. and dat/time formatted as YYYYMMDD.h_mm_ss respectively

type

string

examples

/var/log/carta/{username}_{pid}.log

/home/{username}/CARTA/log/{datatime}_{pid}.log

default

/var/log/carta/{username}_{datetime}_{pid}.log

  • additionalArgs

Additional arguments to be passed to the backend process, defined as an array of strings. See backend documentation for details.

type

array

examples

–omp_threads

4

–initial_timeout

30

–exit_timeout

0

items

type

string

  • startDelay

Wait time before checking whether started process is still running and sending a response to the connecting client

type

integer

minimum

0

default

250

  • dashboard

Dashboard appearance configuration

type

object

properties

  • backgroundColor

Background color for the dashboard

type

string

examples

red

rgb(171 66 66)

#ff11ee

default

#f6f8fa

  • bannerColor

Background color for the institutional logo banner

type

string

examples

red

rgb(171 66 66)

#ff11ee

default

#606f7e

  • bannerImage

Path to institutional logo in PNG or SVG format

type

string

  • infoText

Text displayed before and after sign in. Plain text or HTML

type

string

examples

Welcome to the server

<span>Welcome to <b>the</b> server</span>

  • loginText

Text displayed before sign-in only. Plain text or HTML

type

string

examples

Please enter your username and password

<span>Click <b>Sign in</b> to log in via Google</span>

  • footerText

Footer text. Plain text or HTML

type

string

examples

Please contact the CARTA helpdesk for more information

<span>If you would like to access the server, or have any problems, comments or suggestions, please <a href=’mailto:test@test.com’>contact us.</a></span>

  • scriptingAccess

Control scripting access for users.

type

string

enum

enabled-all-users, disabled-all-users, opt-in

default

disabled-all-users

additionalProperties

False

if

properties

  • serverPort

type

string

then

properties

  • serverInterface

type

null

keyAlgorithm

Algorithm used for public/private keys

type

string

enum

HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

default

RS256

Google AuthProvider

Authentication configuration when using Google authentication

type

object

properties

  • clientId

Google application client ID

type

string

examples

my-app-id.apps.googleusercontent.com

pattern

^\S+.apps.googleusercontent.com$

  • validDomain

Valid domains to accept. If this is empty or undefined, all domains are accepted. Domain specified by hd field in Google authentication configuration.

type

string

examples

gmail.com

my-google-domain.com

  • useEmailAsId

Whether to use the email field as a unique identifier

type

boolean

examples

True

False

default

True

  • userLookupTable

Path of user lookup table as text file in format <unique user ID> <system user>. Example table given in usertable.txt.stub

type

string

examples

/etc/carta/userlookup.txt

  • publicKeyLocation

Path to public key (in PEM format) used for verifying JWTs

type

string

examples

/etc/carta/carta_public.pem

  • privateKeyLocation

Path to private key (in PEM format) used for signing JWTs

type

string

examples

/etc/carta/carta_private.pem

  • keyAlgorithm

default

RS256

keyAlgorithm

  • issuer

Issuer field for JWT

type

string

examples

my-carta-server

  • refreshTokenAge

Lifetime of refresh tokens

type

string

examples

1w

15h

2d

default

1w

  • accessTokenAge

Lifetime of access tokens

type

string

examples

90s

1h

15m

default

15m

  • scriptingTokenAge

Lifetime of scripting tokens

type

string

examples

1w

5d

10h

default

1w

additionalProperties

False

Local AuthProvider

Authentication configuration when using PAM-based authentication

type

object

properties

  • publicKeyLocation

Path to public key (in PEM format) used for verifying JWTs

type

string

examples

/etc/carta/carta_public.pem

  • privateKeyLocation

Path to private key (in PEM format) used for signing JWTs

type

string

examples

/etc/carta/carta_private.pem

  • keyAlgorithm

default

RS256

keyAlgorithm

  • issuer

Issuer field for JWT

type

string

examples

my-carta-server

  • refreshTokenAge

Lifetime of refresh tokens

type

string

examples

1w

15h

2d

default

1w

  • accessTokenAge

Lifetime of access tokens

type

string

examples

90s

1h

15m

default

15m

  • scriptingTokenAge

Lifetime of scripting tokens

type

string

examples

1w

5d

10h

default

1w

additionalProperties

False

LDAP AuthProvider

Authentication configuration when using LDAP-based authentication

type

object

properties

  • publicKeyLocation

Path to public key (in PEM format) used for verifying JWTs

type

string

examples

/etc/carta/carta_public.pem

  • privateKeyLocation

Path to private key (in PEM format) used for signing JWTs

type

string

examples

/etc/carta/carta_private.pem

  • keyAlgorithm

default

RS256

keyAlgorithm

  • issuer

Issuer field for JWT

type

string

examples

my-carta-server

  • refreshTokenAge

Lifetime of refresh tokens

type

string

examples

1w

15h

2d

default

1w

  • accessTokenAge

Lifetime of access tokens

type

string

examples

90s

1h

15m

default

15m

  • scriptingTokenAge

Lifetime of scripting tokens

type

string

examples

1w

5d

10h

default

1w

  • ldapOptions

Options to path through to the LDAP auth instance

type

object

properties

  • url

LDAP connection URI

type

string

pattern

^ldaps?://

format

uri

  • searchBase

Search base

type

string

  • searchFilter

Search filter to use

type

string

default

uid={{username}}

  • starttls

Whether to start TLS when making a connection

type

boolean

default

True

  • reconnect

Whether to automatically reconnect to LDAP

type

boolean

default

True

  • bindProperty

Property of the LDAP user object to use when binding to verify the password

type

string

default

dn

  • searchScope

Scope of the search

type

string

enum

base, one, sub

default

sub

  • bindDN

Admin connection DN, e.g. uid=myapp,ou=users,dc=example,dc=org. If not given at all, admin client is not bound.

type

string

  • bindCredentials

Password for bindDN

type

string

  • cache

If true, then up to 100 credentials at a time will be cached for 5 minutes

type

boolean

default

False

  • strictDN

Force strict DN parsing for client methods

type

boolean

default

True

  • idleTimeout

Milliseconds after last activity before client emits idle event

type

number

additionalProperties

True

additionalProperties

False

External AuthProvider

OAuth2-compatible authentication configuration

type

object

properties

  • issuers

List of valid issuers in JWT field

type

array

examples

my-auth-server

my-other-auth-server

items

type

string

minItems

1

  • publicKeyLocation

Path to public key (in PEM format) used for verifying JWTs

type

string

examples

/etc/carta/my_auth_server_public_key.pem

  • keyAlgorithm

default

RS256

keyAlgorithm

  • uniqueField

Name of unique field to use as user ID

type

string

examples

user

sub

user_id

  • tokenRefreshAddress

Route for refreshing access tokens

type

string

pattern

^https?://

format

uri

  • logoutAddress

Route for logging out

type

string

pattern

^https?://

format

uri

  • userLookupTable

Path of user lookup table as text file in format <unique user ID> <system user>. If no user lookup is needed, this should be omitted. Example table given in usertable.txt.stub

type

string

examples

/etc/carta/userlookup.txt

additionalProperties

False

OpenID Connect AuthProvider

OpenID Connect authentication configuration

type

object

properties

  • idpUrl

Base URL for identity provider endpoint

type

string

examples

https://domain.xyz/auth/realms/example

pattern

^https?://

format

uri

  • uniqueField

Name of unique field to use as user ID. Note that as per the OpenID Connect specification only sub/issuer combination is guaranteed to be stable and unique for an arbitrary issuer, though other values such as preferred_username may be usable when the team running the CARTA installation and the issuer are the same.

type

string

examples

sub

preferred_username

default

sub

  • clientId

Client ID as registered with identity provider

type

string

examples

carta

minLength

1

  • clientSecret

Client secret as registered with identity provider

type

string

minLength

1

  • scope

Scopes to request from the OpenID Connect server

type

string

examples

openid

openid groups

default

openid

  • userLookupTable

Path of user lookup table as text file in format <unique user ID> <system user>. If no user lookup is needed, this should be omitted. Example table given in usertable.txt.stub

type

string

examples

/etc/carta/userlookup.txt

  • groupsField

Name of field containing list of user roles/groups

type

string

examples

groups

roles

  • requiredGroup

Role to ensure is included among the values in groupsField

type

string

examples

carta-users

carta-testers

  • localPublicKeyLocation

Path to public key (in PEM format) used for verifying JWTs

type

string

examples

/etc/carta/carta_public.pem

  • localPrivateKeyLocation

Path to private key (in PEM format) used for signing JWTs

type

string

examples

/etc/carta/carta_private.pem

  • keyAlgorithm

default

RS256

keyAlgorithm

  • issuer

Issuer field for JWT

type

string

examples

my-carta-server

  • cacheAccessTokenMinValidity

If an access token was previously issued from the upstream server with at least this many seconds of lifetime remaining, a new upstream query will not be performed and a local token with the previous token’s remaining lifetime will be issued instead

type

integer

default

100

  • symmetricKeyLocation

Path to symmetric key (base64-encoded) used for refresh tokens. At present this uses the A256GCM algorithm which requires 32 bytes of random data which can be generated using openssl rand -base64 32

type

string

examples

/etc/carta/carta_symmetric.pem

  • symmetricKeyType

Selected from the ‘JSON Web Signature and Encryption Algorithms’ section of https://www.iana.org/assignments/jose/jose.xhtml

type

string

default

A256GCM

  • additionalAuthParams

Additional parameters to include in authentication requests to deal with identity providers. The example contains the additional arguments required to ensure that Google provide a refresh token when using it with OIDC.

type

array

examples

access_type

offline

prompt

consent

default

items

type

array

maxItems

2

minItems

2

  • postLogoutRedirect

Optional parameter for specifying an alternate address to redirect to after logout

type

string

examples

https://my-organisation.com/

format

uri-reference

additionalProperties

False