System package

Extend command launcher's built-in function with system package

What is a System Package #

A System Package is like any other Command Launcher package, with one manifest.mf file in it to describe the commands, and containing binaries, scripts, and resources to execute those commands.

The difference is that a System Package contains system commands, and it can only be installed from a central repository (not as a dropin package).

You can customize your Command Launcher by providing a system package. In a system package, you can define system commands as functional hooks to extend Command Launcher’s built-in functionalities, for example, login and metrics.

Define system package #

To specify which package is the system package, use the configuration system_package.

cola config system_package your-system-package-name

An example system package manifest looks like this:

pkgName: system-package-demo
version: 1.0.0
cmds:
    - name: __login__
      type: system
      executable: "{{.PackageDir}}/hooks/login-hook"
    - name: __metrics__
      type: system
      executable: "{{.PackageDir}}/hooks/metrics-hook"
    - name: other-commands
      type: executable
      executable: "{{.PackageDir}}/scripts/other-cmd.sh"

NOTE: The system command will be ignored if the package is not defined as system package.

System commands #

To extend Command Launcher built-in functionality, you need to specify some system type commands in a system package. The following table lists available system commands:

System command __login__ #

The built-in login command will trigger the __login__ system command. It takes two arguments:

• username
• password

__login__ [username] [password]

The __login__ system command outputs the credentials to be stored by command launcher in a JSON format. The credentials could be one or many of following items:

For example: the following output tells command launcher to store the username and the auth_token, but not store the password.

{
    "username": "joe",
    "auth_token": "DZ4OfC4vS38!"
}

To use these credentials see Manage resources

System command __metrics__ #

At the end of each Command Launcher execution, the __metrics__ system hook will be triggered. The following arguments will be passed to the __metrics__ system command in order:

1. repository/registry name (see remote command)
2. package name
3. command group name, or “default” if no group
4. command name
5. user partition
6. command exit code
7. command execution duration in nano seconds
8. error message or “nil” if no error
9. command start timestamp in seconds

Here is an example:

__metrics__ default example cola-example hello 2 0 5000000 nil 1668363339

Note: the __metrics__ hook will be called at the end of each Command Launcher call, please make sure it ends fast to reduce the footprint.