# CLI Configuration ```{warning} This project is still evolving, so these docs may be incomplete or out-of-date. ``` Jumpstarter can be configured as either a client, an exporter, or both depending on your use case and deployment strategy. By default, a local client and exporter session are automatically initialized when running test scripts through `jmp shell` command. This allows for easy testing of new drivers, client libraries, or verifying that tests work on your local bench. When interacting with remote exporters in a CLI or CI environment, multiple clients can be configured on the same system and used to interact with different devices and different exporter instances. Similarly, multiple exporters can be configured on a single host system to interact with many different devices. However, each exporter instance is independent, making it possible to stop, restart, and add new exporters while others are executing tests. ## User Configuration Jumpstarter stores user-specific configs in the `~/.config/jumpstarter` directory within the user's home folder. The user config file defines the current client config and any user-specific configurations for `jmp` CLI tool. ```yaml # ~/.config/jumpstarter/config.yaml apiVersion: jumpstarter.dev/v1alpha1 kind: UserConfig config: current-client: default ``` ## Clients Client configurations are stored in the Jumpstarter user configuration directory `~/.config/jumpstarter/clients`. Each client config is a YAML file that contains the client name, access token, and any configuration parameters. ### Client Config ```yaml # ~/.config/jumpstarter/clients/myclient.yaml apiVersion: jumpstarter.dev/v1alpha1 kind: Client metadata: name: myclient namespace: jumpstarter-lab tls: insecure: false ca: "" endpoint: "jumpstarter.my-lab.com:1443" token: "dGhpc2lzYXRva2VuLTEyMzQxMjM0MTIzNEyMzQtc2Rxd3Jxd2VycXdlcnF3ZXJxd2VyLTEyMzQxMjM0MTIz" drivers: # Wildcards are supported allow: ["jumpstarter_drivers_*", "vendorpackage.*"] ``` - `endpoint` - The gRPC endpoint of the Jumpstarter controller server. - `token` - A client auth token generated by the controller. - `drivers` - Driver client library configuration. - `allow` - A list of allowed driver namespaces to automatically load. - `unsafe: true` - Should all drivers be allowed to load? - `tls` - `insecure` - Set to `true` to disable TLS verification of the gRPC endpoint. - `ca` - Path to a custom CA certificate file to use for TLS verification. ## Multiple Clients Multiple client configs can be added to the `~/.config/jumpstarter/clients` directory manually or by using the Jumpstarter CLI. Similar to kubectl, Jumpstarter allows you to switch between different client configurations using the CLI tool. A `default` client is automatically configured when installing the Jumpstarter Helm chart with `jmp install`. ## Creating a client in the distributed service To create a new client in the distributed service you must use the `jmp admin create` subcommand, please follow the instructions in the [Jumpstarter service CLI](../cli/clients.md). ## Importing a client created by the administrator Importing a new client is as simple as copying the administrator provided yaml file to `~/.config/jumpstarter/clients/`, alternatively if we have the token and endpoint the `jmp config client create ` command can be used to create the config file. To switch between different client configs, use the `jmp config client use ` command: ```bash $ jmp config client use another Using client config '/home/jdoe/.config/jumpstarter/clients/another.yaml' ``` All client configurations can be listed with `jmp config client list`: ```bash $ jmp config client list CURRENT NAME ENDPOINT PATH * default jumpstarter1.my-lab.com:1443 /home/jdoe/.config/jumpstarter/clients/default.yaml myclient jumpstarter2.my-lab.com:1443 /home/jdoe/.config/jumpstarter/clients/myclient.yaml another jumpstarter3.my-lab.com:1443 /home/jdoe/.config/jumpstarter/clients/another.yaml ``` Clients can also be removed using `jmp config client delete `: ```bash $ jmp config client delete myclient Deleted client config '/home/jdoe/.config/jumpstarter/clients/myclient.yaml' ``` ## Client Environment Variables The client configuration may also be provided by environment variables which may be useful in CI or when writing a script that uses Jumpstarter. - `JUMPSTARTER_GRPC_INSECURE` - Set to `1` to disable TLS verification. - `JMP_CLIENT_CONFIG` - A path to a client configuration YAML file to use. - `JMP_CLIENT` - The name of a registered client config to use. - `JMP_NAMESPACE` - The namespace in the jumpstarter-controller to use, like `metadata.namespace`. - `JMP_NAME` - The client/exporter name in the jumpstarter-controller to use, like `metadata.name`. - `JMP_ENDPOINT` - The gRPC endpoint of the Jumpstarter controller server (overrides the config value). - `JMP_TOKEN` - A client auth token generated by the controller (overrides the config value). - `JMP_DRIVERS_ALLOW` - A comma-separated list of allowed driver namespaces to automatically load. Can be set to `UNSAFE` to allow unsafe loading of drivers. - `JUMPSTARTER_FORCE_SYSTEM_CERTS` - Set to `1` to force the system CA certificates, which is the behavior by default for all systems but MacOS (see [bug](https://github.com/jumpstarter-dev/jumpstarter/issues/362)) ## System Configuration Jumpstarter stores system configs in the `/etc/jumpstarter` directory. This configuration directory is primarily used by the exporters `/etc/jumpstarter/exporters` as they often run as daemon services on the host system. ## Exporters Exporter configurations are by default stored globally in the Jumpstarter config directory `/etc/jumpstarter/exporters`. Each exporter config is a YAML file that provides connection details and a list of exporter drivers. ### Exporter Config Exporters can be configured using a pure-YAML format, which allows for the configuration of built-in drivers and any additional driver packages registered by the user. ```yaml # /etc/jumpstarter/exporters/myexporter.yaml apiVersion: jumpstarter.dev/v1alpha1 kind: Exporter metadata: name: myexporter namespace: jumpstarter-lab tls: insecure: false ca: "" endpoint: "jumpstarter.my-lab.com:1443" token: "dGhpc2lzYXRva2VuLTEyMzQxMjM0MTIzNEyMzQtc2Rxd3Jxd2VycXdlcnF3ZXJxd2VyLTEyMzQxMjM0MTIz" export: power: type: "jumpstarter_driver_power.driver.PduPower" config: host: "192.168.1.111" port: 1234 username: "admin" password: "secret" serial: type: "jumpstarter_driver_pyserial.driver.PySerial" config: url: "/dev/ttyUSB0" baudrate: 115200 custom: type: "vendorpackage.CustomDriver" config: hello: "world" ``` - `metadata` - Name/namespace information for the jumsptarter controller to identify the exporter along the token. - `endpoint` - The gRPC endpoint of the Jumpstarter controller server. - `token` - An exporter auth token generated by the controller. - `export` - Exporter driver configuration. - `tls` - `insecure` - Set to `true` to disable TLS verification of the gRPC endpoint. - `ca` - Path to a custom CA certificate file to use for TLS verification. ### Exporter CLI Commands ### Creating a exporter in the distributed service To create a new exporter in the distributed service you must use the `jmp admin create` command, please follow the instructions in the [Jumpstarter service CLI](../cli/exporters.md). ### Creating a exporter configuration file To create a new exporter configuration file from a know endpoint and token the `jmp config exporter create ` command can be used. ```bash $ jmp config exporter create myexporter Endpoint: grpc.jumpstarter.my.domain.com Token: <> ``` To use a specific config when starting the exporter: ```bash $ jmp run --exporter my-exporter Using exporter config '/etc/jumpstarter/exporters/another/exporter.yaml' ``` The path to a config can also be provided: ```bash jmp run --exporter-config /etc/jumpstarter/exporters/another/exporter.yaml ``` All exporter configurations can be listed with `jmp config exporter list`: ```bash $ jmp config exporter list ALIAS PATH test-exporter-2 /etc/jumpstarter/exporters/test-exporter-2.yaml my-exporter /etc/jumpstarter/exporters/my-exporter.yaml ``` Exporters can also be removed using `jmp config exporter delete `: ```bash $ jmp config exporter delete myexporter Deleted exporter config '/etc/jumpstarter/exporters/myexporter.yaml' ``` ### Exporter Environment Variables The exporter configuration may also be provided by environment variables which may be useful in CI or when writing a script that uses Jumpstarter. - `JUMPSTARTER_GRPC_INSECURE` - Set to `1` to disable TLS verification. to use. - `JMP_ENDPOINT` - The gRPC endpoint of the Jumpstarter controller server (overrides the config value). - `JMP_TOKEN` - An exporter auth token generated by the controller (overrides the config value). - `JMP_NAMESPACE` - The namespace in the jumpstarter-controller to use, like `metadata.namespace`. - `JMP_NAME` - The client/exporter name in the jumpstarter-controller to use, like `metadata.name`. ## Running an Exporter The exporter service can be run as a container either within the same cluster (using node affinity) or on a remote machine that has access to the cluster over the network. ### Running using Podman To run the exporter container on a test runner using Podman: ```{code-block} bash :substitutions: $ sudo podman run --rm -ti --name my-exporter --net=host --privileged \ -v /run/udev:/run/udev -v /dev:/dev -v /etc/jumpstarter:/etc/jumpstarter \ quay.io/jumpstarter-dev/jumpstarter:{{version}} \ jmp run --exporter my-exporter INFO:jumpstarter.exporter.exporter:Registering exporter with controller INFO:jumpstarter.exporter.exporter:Currently not leased ``` This will run the exporter in the foreground and allow you to observe the behavior. Please note that we are running the exporter as root, with access to all devices and network interfaces, this is most likely necessary for the exporter to access the interface devices that will allow it to control the target DUT(s). Once we are satisfied with the behavior we can install the exporter as a systemd service: #### Running as a Service To run the exporter as a service podman-systemd is recommended, by using podman-systemd you can simply create a systemd service file at `/etc/containers/systemd/my-exporter.container` with the following content: ```{code-block} ini :substitutions: [Unit] Description=My exporter [Container] ContainerName=my-exporter Exec=/jumpstarter/bin/jmp run --exporter my-exporter Image=quay.io/jumpstarter-dev/jumpstarter:{{version}} Network=host PodmanArgs=--privileged Volume=/run/udev:/run/udev Volume=/dev:/dev Volume=/etc/jumpstarter:/etc/jumpstarter [Service] Restart=always StartLimitBurst=0 [Install] WantedBy=multi-user.target default.target ``` Then enable and start the service: ```bash sudo systemctl daemon-reload sudo systemctl enable --now my-exporter ```