Amygdala Configuration File

The majority of the configuration is optional and can be omitted. For a list of the required fields, see the migration guide.

TL;DR

• Required Server Fields
  • deployment_root
  • default_deployment
  • server_runtime_root
• Required Client Fields
  • client_runtime_root

Lazy Loading

The configuration file is read once when it is first required. All subsequent uses will use the cached version of the config and changes to the file will require a restart of the launcher. If the process is being managed by systemd, it is possible to request a restart from the client.

If it is not possible to read the config file for any reason, the request will fail and the client will be sent details of the error. In this case, subsequent requests will attempt to read the config again and changes will be reflected if they haven't already been loaded.

Full Config Example

The majority of these fields are optional

subnet = "12.34.56.0/23"

deployment_root = "/path/to/deployment_root"
default_deployment = "version_1"
shutdown_timeout = 13
status_port = 23456
startup_file_directory = "/tmp/startup_files"
log_directory = "/tmp/amygdala_logs"
client_runtime_root = "/tmp/gda_client"
server_runtime_root = "/tmp/gda_server"

[layout]
client = "client/client-bin"
server = "server/server-bin"
config = "config"

[env]
COMMON_FOO = "BAR"
[system]
"common.foo" = "bar"

[server.env]
SERVER_FOO = "BAR"
[server.system]
"server.foo" = "bar"

[client.env]
CLIENT_FOO = "BAR"
[client.system]
"client.foo" = "bar"

[[hooks.pre_start]]
command = "pre_start_command"
args = ["one", "two"]
env = {"VARIABLE": "VALUE"}

[[hooks.post_start]]
command = "post_start"

Launcher specific configuration

These items control the way the launcher daemon is run and doesn't affect the server or clients it starts.

All launcher fields are optional

Optional Fields

Port

amygdala serve --port 8765

port = 9876

Subnet

subnet = "12.34.56.00/21"

This restricts the hosts from which the client can connect. It is intended to restrict clients to the beamline network so that the server for a beamline cannot be started unless you are on the beamline. This is intended mainly to prevent the wrong server being started more than as a security feature as it is easy to circumvent by SSHing to a beamline workstation.

There is no default subnet and clients will be able to connect from any machine that can reach the control machine. No default

Server configuration

Required Fields

Deployment Root

deployment_root = "/dls_sw/ixx/software/gda_version/"

The parent directory of all the GDA deployments for a beamline. For Diamond, this is will almost always be the gda_versions directory.

Default Deployment

default_deployment = "gda"

The directory within the deployment root that should be used by default if an alternative deployment is not specified. This is currently required but may become optional in future if gda becomes the de facto default in practice.

Optional Fields

Shutdown Timeout

shutdown_timeout = 10

The time in seconds when shutting down a server between sending SIGINT interrupt and assuming it has crashed and sending a SIGKILL. Default: 10s

Status Port

status_port = 19999

This is the port used to determine when the server has reached a 'ready' state. It is also used to determine if a server is running that was started by an external process (eg the previous script launcher or the IDE if developing locally). Default: 19999

Startup File Directory

startup_file_directory = "/tmp/"

The directory where GDA should write any errors encountered during start up. This is used to relay the top level error to the client without having to read through the main logs. The individual files only exist for the startup process and are immediately removed on either failure or success. Default: $XDG_RUNTIME_DIR (or /tmp if undefined)

Log Directory

log_directory = "/dls_sw/ixx/logs"

The parent directory of the gda-servers-output and gda-client-output. It has no effect on the directory where GDA writes its main log files. Note that the output subdirectories are not created and must already exist. Default: /tmp/

Server Runtime Root

server_runtime_root = "gda_launcher"

The directory where the server workspace and config directories should be created. In the previous scripts this would be in gda2's home directory. A relative path here will be relative to the working directory when the daemon is started. Default: /tmp/

Layout

[layout]
client = "client/gda-ixx"
config = "ixx-config"
server = "server/gda-server"

This describes the layout of each deployment. It is optional and individual fields can be overridden if needed (it's not all or nothing). For most beamlines, the defaults will be ok. Relative paths are resolved against the deployment being used. Absolute paths are used as they are but aren't recommended as changing deployments will have no effect.

• Default server: server/gda-server
• Default client: client/gda-$BEAMLINE (or gda-example if $BEAMLINE is not set).
• Default config: config

System Properties and Environment Variables

[server.system]
"gda.system.property" = "value"
"other.system.property" = "other value"
[server.env]
"SERVER_ENV" = "value"

Any system properties that should be passed to the server or environment variables that should be set for the server process. This is where defaults specific to this installation should go (as opposed to the config.toml file in the beamline configuration). No defaults

Hooks

It is possible to specify external programs that should be run on certain events in the life cycle of the GDA server. The four currently available extension points are before and after the GDA server starts and shuts down. There can be multiple hooks at each point in which case they will run sequentially in the order they are defined in the configuration.

For each hook, a path to the command is required. This can either be an absolute path to a command or a command name on the $PATH of the user running the daemon. There can also, optionally, be a list of arguments to pass to the command as well as any environment variables that should be set.

The four hook names are

• pre_start - If these exit with a non-zero exit code, the launch is aborted.
• post_start - These are not run if the server fails to start. If these fail to run after an otherwise successful launch, the error is reported to the user but the server is left running.
• pre_shutdown - This includes before shutting down the server when the user has requested a restart. If these fail, the shutdown is aborted (and therefore also the subsequent start for a restart).
• post_shutdown - These don't currently block the server starting if they fail during a restart to maintain consistency with the case where there is nothing that can be done if a post_shutdown hook fails when calling stop.

Each hook should be defined in the same way with the appropriate hook name used.

[[hooks.pre_start]]
command = "/path/to/command"
args = ["one", "two"]
env = { "VAR_ONE": "VALUE_ONE", "VAR_TWO": "VALUE_TWO" }

Hooks can be specified in any order but should all be together at the end of the config file due to TOML restrictions. No defaults

Client Configuration

Required Fields

Client Runtime Root

client_runtime_root = "/tmp/"

The parent directory of the client workspace and config directories. The actual directories used will be in a tree below this directory based on the user name of the user starting the client and the deployment and build of the client being run.

Optional Fields

System Properties and Environment Variables

[client.system]
"gda.system.property" = "value"
"other.system.property" = "other value"
[client.env]
"CLIENT_ENV" = "value"

The client equivalent of the server fields. No defaults

Common Configuration

Optional Fields

System Properties and Environment Variables

[system]
"common.system.property" = "common value"
[env]
GDA_VAR = "/path/to/var/directory"
GDA_MODE = "live"

Any system properties or environment variables that are common to both the server and the client. This is probably the best place for GDA_VAR and GDA_MODE to be defined. No defaults