mirror of
https://github.com/outbackdingo/matchbox.git
synced 2026-01-27 10:19:35 +00:00
de0b88839c
* Publish matchbox docs to https://matchbox.psdn.io * Remove references to https://coreos.com/matchbox/docs
107 lines
4.8 KiB
Markdown
107 lines
4.8 KiB
Markdown
|
|
# 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
|
|
|
|
```sh
|
|
$ ./bin/matchbox -version
|
|
$ sudo docker run quay.io/poseidon/matchbox:latest -version
|
|
```
|
|
|
|
## Usage
|
|
|
|
Run the binary.
|
|
|
|
```sh
|
|
$ ./bin/matchbox -address=0.0.0.0:8080 -log-level=debug -data-path=examples -assets-path=examples/assets
|
|
```
|
|
|
|
Run the latest Docker image.
|
|
|
|
```sh
|
|
$ 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.
|
|
|
|
```sh
|
|
$ 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`.
|
|
|
|
```sh
|
|
$ ./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.
|
|
|
|
```sh
|
|
$ ./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`.
|
|
|
|
```sh
|
|
$ 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.
|
|
|
|
```sh
|
|
$ ./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](openpgp.md)
|
|
|
|
Run with the binary with a test key.
|
|
|
|
```sh
|
|
$ 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.
|
|
|
|
```sh
|
|
$ 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
|
|
```
|