Flags and variables¶
Configuration arguments can be provided as flags or as environment variables.
| flag | variable | default | example |
|---|---|---|---|
| -address | MATCHBOX_ADDRESS | 127.0.0.1:8080 | 0.0.0.0:8080 |
| -log-level | MATCHBOX_LOG_LEVEL | info | critical, error, warning, notice, info, debug |
| -data-path | MATCHBOX_DATA_PATH | /var/lib/matchbox | ./examples |
| -assets-path | MATCHBOX_ASSETS_PATH | /var/lib/matchbox/assets | ./examples/assets |
| -rpc-address | MATCHBOX_RPC_ADDRESS | (gRPC API disabled) | 0.0.0.0:8081 |
| -cert-file | MATCHBOX_CERT_FILE | /etc/matchbox/server.crt | ./examples/etc/matchbox/server.crt |
| -key-file | MATCHBOX_KEY_FILE | /etc/matchbox/server.key | ./examples/etc/matchbox/server.key |
| -ca-file | MATCHBOX_CA_FILE | /etc/matchbox/ca.crt | ./examples/etc/matchbox/ca.crt |
| -key-ring-path | MATCHBOX_KEY_RING_PATH | (no key ring) | ~/.secrets/vault/matchbox/secring.gpg |
| (no flag) | MATCHBOX_PASSPHRASE | (no passphrase) | "secret passphrase" |
Files and directories¶
| Data | Default Location |
|---|---|
| data | /var/lib/matchbox/{profiles,groups,ignition,cloud,generic} |
| assets | /var/lib/matchbox/assets |
| gRPC API TLS Credentials | Default Location |
|---|---|
| CA certificate | /etc/matchbox/ca.crt |
| Server certificate | /etc/matchbox/server.crt |
| Server private key | /etc/matchbox/server.key |
| Client certificate | /etc/matchbox/client.crt |
| Client private key | /etc/matchbox/client.key |
Version¶
$ ./bin/matchbox -version
$ sudo docker run quay.io/poseidon/matchbox:latest -version
Usage¶
Run the binary.
$ ./bin/matchbox -address=0.0.0.0:8080 -log-level=debug -data-path=examples -assets-path=examples/assets
Run the latest Docker image.
$ sudo docker run -p 8080:8080 --rm -v $PWD/examples/assets:/var/lib/matchbox/assets:Z quay.io/poseidon/matchbox:latest -address=0.0.0.0:8080 -log-level=debug
With examples¶
Mount examples to pre-load the example machine groups and profiles. Run the container.
$ sudo docker run -p 8080:8080 --rm -v $PWD/examples:/var/lib/matchbox:Z -v $PWD/examples/groups/etcd:/var/lib/matchbox/groups:Z quay.io/poseidon/matchbox:latest -address=0.0.0.0:8080 -log-level=debug
With gRPC API¶
The gRPC API allows clients with a TLS client certificate and key to make RPC requests to programmatically create or update matchbox resources. The API can be enabled with the -rpc-address flag and by providing a TLS server certificate and key with -cert-file and -key-file and a CA certificate for authenticating clients with -ca-file.
Run the binary with TLS credentials from examples/etc/matchbox.
$ ./bin/matchbox -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081 -log-level=debug -data-path=examples -assets-path=examples/assets -cert-file examples/etc/matchbox/server.crt -key-file examples/etc/matchbox/server.key -ca-file examples/etc/matchbox/ca.crt
Clients, such as bootcmd, verify the server's certificate with a CA bundle passed via -ca-file and present a client certificate and key via -cert-file and -key-file to cal the gRPC API.
$ ./bin/bootcmd profile list --endpoints 127.0.0.1:8081 --ca-file examples/etc/matchbox/ca.crt --cert-file examples/etc/matchbox/client.crt --key-file examples/etc/matchbox/client.key
With docker¶
Run the Docker image with TLS credentials from examples/etc/matchbox.
$ sudo docker run -p 8080:8080 -p 8081:8081 --rm -v $PWD/examples:/var/lib/matchbox:Z -v $PWD/examples/etc/matchbox:/etc/matchbox:Z,ro -v $PWD/examples/groups/etcd:/var/lib/matchbox/groups:Z quay.io/poseidon/matchbox:latest -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081 -log-level=debug
A bootcmd client can call the gRPC API running at the IP used in the Docker example.
$ ./bin/bootcmd profile list --endpoints 127.0.0.1:8081 --ca-file examples/etc/matchbox/ca.crt --cert-file examples/etc/matchbox/client.crt --key-file examples/etc/matchbox/client.key
With openPGP Signing¶
Run with the binary with a test key.
$ export MATCHBOX_PASSPHRASE=test
$ ./bin/matchbox -address=0.0.0.0:8080 -key-ring-path matchbox/sign/fixtures/secring.gpg -data-path=examples -assets-path=examples/assets
Run the container image with a test key.
$ sudo docker run -p 8080:8080 --rm --env MATCHBOX_PASSPHRASE=test -v $PWD/examples:/var/lib/matchbox:Z -v $PWD/examples/groups/etcd:/var/lib/matchbox/groups:Z -v $PWD/matchbox/sign/fixtures:/secrets:Z quay.io/poseidon/matchbox:latest -address=0.0.0.0:8080 -log-level=debug -key-ring-path secrets/secring.gpg