Handler Files

New commands can be added by including new *.json files in the handler_configs directory. This directory is specified in the paths.handler_configs configuration item in the main Edge Agent configuration file (/etc/edge-agent/agent-data.json, points to this directory). Typically, this directory is /etc/edge-agent/handler-configs.

A handler consists of the following fields:

Table 1.
Field	Required	Description
name	Yes	Name of the handler
capabilities	No	Array of capabilities provided by the handler
path	Yes	Location of the handler's commands
commands		List of commands supported by the handler

A command consists of the following fields:

Table 2.
Field	Required	Description
bin	Yes	Location of the executable file on the system
needs_task_id	No	If set to `true` this will pass a task ID to the command. Defaults to `false` if omitted. For more information see Writing Package Deployment Commands.

The format of the file is:

{
    "handlers": {
        "Machine": {
            "capabilities": [
                {
                    "name": "SomeCapability",
                    "version": "1.0"
                }
            ],
            "path": "/opt/something/machine_handlers",
            "commands": {
                "some-command": {
                    "bin": "some-exe",
                    "needs_task_id": true
                }
            }
        },
        "Host": {
            "capabilities": [
                {
                    "name": "Dir",
                    "version": "0.1"
                },
                {
                    "name": "Date",
                    "version": "1.1"
                }
            ],
            "path": "/bin",
            "commands": {
                "ls": {
                    "bin": "ls"
                },
                "date": {
                    "bin": "date"
                }
            }
        }
    }
}

In this example, "Machine" and "Host" are the handler names.

"Machine" provides version 1.0 of the SomeCapability capability. It supports a single command, some-command, that is implemented by some-exe, which is given a task ID. It expects these commands to be in /opt/something/machine_handlers.

"Host" provides version 0.1 of the Dir capability and version 1.1 of the Date capability. It supports two commands, ls and date. They are implemented by ls and date respectively. It expects these commands to be in /bin.

Capabilities are defined in the glossary.

Loading Handler Files

All *.json files in the handler configuration directory are loaded in lexical order. If a handler of a specified name has already been loaded and a handler of the same name is specified in a later configuration file, the new file is skipped, an error is logged, and the next file (if present) is processed.

Handlers are loaded only once, when the dispatcher is started. In order to reload the configuration files, the dispatcher (e.g., systemctl restart edge-agent-dispatcher) should be restarted.

Validation of Handler Files

If a file is invalid, it is skipped, an error is logged, and the next configuration handler file (if present) is processed.

The following checks will be performed on all handler files to ensure correctness.

Verification of the validity of the JSON file
handlers is the top level key of the handler config file and a single handlers key should be specified
The handler name cannot be empty
Duplicate handlers are not allowed
If capabilities are specified:
- must be an array
- must contain a non-empty name
- must contain a non-empty version
commands must be specified as part of a handler and the name of each command must be specified.
The command bin must be specified and the path must point to a valid executable file.