Carbide Admin CLI

carbide-admin-cli is the command-line tool for managing a Carbide site. It communicates with carbide-api over gRPC with mutual TLS (mTLS).

Building

From the repository root:

1
# Debug build (faster compile, larger binary)
2
cargo build -p carbide-admin-cli
3
4
# Release build (optimized, for deployment)
5
cargo build -p carbide-admin-cli --release

The binary is written to:

• target/debug/carbide-admin-cli (debug)
• target/release/carbide-admin-cli (release)

Connecting to carbide-api

The CLI needs three things to connect:

1. API URL — where carbide-api is listening
2. Root CA certificate — to verify the server’s TLS certificate
3. Client certificate + key — to authenticate this client to the server

TLS options

Config file

Instead of passing flags every time, create $HOME/.config/carbide_api_cli.json:

1
{
2
  "carbide_api_url": "https://carbide-api.example.com:1079",
3
  "forge_root_ca_path": "/etc/carbide/certs/ca.crt",
4
  "client_cert_path": "/etc/carbide/certs/client.crt",
5
  "client_key_path": "/etc/carbide/certs/client.key"
6
}

Example invocations

1
# Explicit flags
2
carbide-admin-cli \
3
  -c https://carbide-api.example.com:1079 \
4
  --forge-root-ca-path /etc/carbide/certs/ca.crt \
5
  --client-cert-path /etc/carbide/certs/client.crt \
6
  --client-key-path /etc/carbide/certs/client.key \
7
  version
8
9
# With config file (no flags needed)
10
carbide-admin-cli version

SOCKS5 proxy support

If the CLI needs to reach carbide-api through a SOCKS5 proxy, set one of: http_proxy, https_proxy, HTTP_PROXY, or HTTPS_PROXY. Only the socks5:// scheme is supported.

Generating client certificates

carbide-api uses mTLS: the server verifies the client’s certificate against a trusted CA.

Creating an admin CA and client cert with OpenSSL

The following creates a self-contained CA and client certificate. In production you would typically use your organization’s existing PKI instead of a self-signed CA.

1
# 1. Generate the CA key and self-signed certificate
2
openssl ecparam -name prime256v1 -genkey -noout -out admin-ca.key
3
openssl req -x509 -new -key admin-ca.key -sha256 -days 3650 \
4
  -out admin-ca.crt \
5
  -subj "/O=ExampleCo/CN=ExampleCo Carbide Admin CA"
6
7
# 2. Generate a client key
8
openssl ecparam -name prime256v1 -genkey -noout -out client.key
9
10
# 3. Create a CSR with operator identity in the subject
11
#    - O  = organization (matched by required_equals if configured)
12
#    - OU = group (used for role-based authorization via group_from)
13
#    - CN = username (used for audit logging via username_from)
14
openssl req -new -key client.key -out client.csr \
15
  -subj "/O=ExampleCo/OU=site-admins/CN=jdoe"
16
17
# 4. Create an extensions file for clientAuth
18
cat > client_ext.cnf <<EOF
19
basicConstraints = CA:FALSE
20
keyUsage = digitalSignature, keyEncipherment
21
extendedKeyUsage = clientAuth
22
EOF
23
24
# 5. Sign the client certificate with the CA
25
openssl x509 -req -in client.csr \
26
  -CA admin-ca.crt -CAkey admin-ca.key -CAcreateserial \
27
  -out client.crt -days 365 -sha256 \
28
  -extfile client_ext.cnf
29
30
# 6. Clean up intermediate files
31
rm -f client.csr client_ext.cnf admin-ca.srl

This produces:

Certificate subject fields and how they map to authorization

The [auth.cli_certs] section in carbide-api-config.toml controls how certificate fields are interpreted:

The available CertComponent values are:

• IssuerO, IssuerOU, IssuerCN — from the certificate issuer
• SubjectO, SubjectOU, SubjectCN — from the certificate subject

Server-side configuration (carbide-api)

TLS section

The [tls] section of carbide-api-config.toml tells carbide-api where to find its own server certificate and which CAs to trust for client authentication:

1
[tls]
2
identity_pemfile_path = "/path/to/server.crt"
3
identity_keyfile_path = "/path/to/server.key"
4
root_cafile_path = "/path/to/internal-ca.crt"
5
admin_root_cafile_path = "/path/to/admin-ca.crt"

carbide-api loads both root_cafile_path and admin_root_cafile_path into its TLS trust store. A client presenting a certificate signed by either CA will pass the TLS handshake.

Configuring authorization

Authorization is configured in the [auth] section of carbide-api-config.toml.

Casbin policy

carbide-api uses Casbin with an RBAC model for authorization. The model is compiled into the binary and uses two rule types:

• g (grouping) rules — map a principal identifier to a role name
• p (policy) rules — allow a principal or role to call a gRPC method (glob matching is supported on the method name)

The policy file is a CSV referenced by casbin_policy_file:

1
[auth]
2
permissive_mode = false
3
casbin_policy_file = "/path/to/casbin-policy.csv"

How principals are identified

The <group> in external-role/<group> comes from the certificate field specified by group_from in [auth.cli_certs].

Writing policy rules

Sample policy file:

1
# On `g` rules: These associate a principal (second column) with a role name
2
# (third column). This causes the named role to also be looked up as if it were
3
# a principal.
4
#
5
# On `p` rules: These allow a principal or role (second column) to perform the
6
# named action (third column). Glob matching is available on the action field.
7
#
8
9
10
# Map the carbide-dhcp SPIFFE ID to the carbide-dhcp role.
11
# FIXME: verify that this is how these SPIFFE service identifiers look in reality.
12
g, spiffe-service-id/carbide-dhcp, carbide-dhcp
13
g, spiffe-service-id/carbide-dns, carbide-dns
14
g, spiffe-machine-id, machine
15
16
# Allow the carbide-dhcp role to call its methods.
17
p, carbide-dhcp, forge/DiscoverDhcp
18
19
# Same idea for carbide-dns.
20
p, carbide-dns, forge/LookupRecord
21
22
# Anonymous access to endpoints that don't modify state or expose any customer
23
# or site data should be fine.
24
p, anonymous, forge/Version
25
26
# Allow anonymous access to methods used by machines that may not have their
27
# certificates from us yet.
28
p, anonymous, forge/DiscoverMachine
29
p, anonymous, forge/ReportForgeScoutError
30
p, anonymous, forge/AttestQuote
31
32
# Allow anonymous access to methods used by dpu-agent. As of 2023-09-28 there
33
# are probably a fair amount of agents across the environments that don't have a
34
# certificate and are not ready for strict enforcement.
35
p, anonymous, forge/FindInstanceByMachineID
36
p, anonymous, forge/GetManagedHostNetworkConfig
37
p, anonymous, forge/RecordDpuNetworkStatus
38
39
# The client cert generated above has OU=site-admins in its subject.
40
# With group_from = "SubjectOU" in [auth.cli_certs], that becomes the
41
# principal "external-role/site-admins". Map it to a role and grant access.
42
g, external-role/site-admins, site-admin
43
p, site-admin, forge/*
44
45
# Example of a restricted role: a cert with OU=viewers would only get
46
# read access to a handful of methods.
47
g, external-role/viewers, viewer
48
p, viewer, forge/Version
49
p, viewer, forge/GetMachine
50
p, viewer, forge/ListMachines
51
p, viewer, forge/GetInstance
52
p, viewer, forge/ListInstances
53
54
55
# Allow any certificate we trust to hit any Forge method.
56
# FIXME: This should be removed once we have more fine-grained rule coverage.
57
p, trusted-certificate, forge/*

The method names in the forge/<Method> column correspond to the gRPC method names defined in the protobuf service definitions. Glob matching (*) is supported.

Full example: carbide-api config with external admin certs

1
[tls]
2
identity_pemfile_path = "/path/to/server.crt"
3
identity_keyfile_path = "/path/to/server.key"
4
root_cafile_path = "/path/to/internal-ca.crt"
5
admin_root_cafile_path = "/path/to/admin-ca.crt"
6
7
[auth]
8
permissive_mode = false
9
casbin_policy_file = "/path/to/casbin-policy.csv"
10
11
[auth.cli_certs]
12
required_equals = { "IssuerO" = "ExampleCo", "IssuerCN" = "ExampleCo Carbide Admin CA" }
13
group_from = "SubjectOU"
14
username_from = "SubjectCN"
15
16
[auth.trust]
17
spiffe_trust_domain = "forge.local"
18
spiffe_service_base_paths = [
19
  "/forge-system/sa/",
20
  "/default/sa/",
21
  "/elektra-site-agent/sa/",
22
]
23
spiffe_machine_base_path = "/forge-system/machine/"
24
additional_issuer_cns = []

With this configuration, a client certificate with subject /O=ExampleCo/OU=site-admins/CN=jdoe and issuer /O=ExampleCo/CN=ExampleCo Carbide Admin CA would:

1. Pass the required_equals check (IssuerO and IssuerCN match)
2. Be assigned group site-admins (from SubjectOU)
3. Be identified as user jdoe (from SubjectCN)
4. Receive the principal external-role/site-admins
5. Be authorized according to whatever casbin policy rules match that principal

You can see an example of a complete carbide-api configuration file here

Permissive mode

Setting permissive_mode = true in the [auth] section causes the authorization engine to allow all requests, even when the casbin policy would deny them. Denied requests are logged with a warning instead of being rejected:

1
[auth]
2
permissive_mode = true

When permissive mode is active, carbide-api logs messages like:

WARN The policy engine denied this request, but --auth-permissive-mode overrides it.

Use permissive mode only for:

• Initial deployment and bring-up, before certificates are fully configured
• Debugging authorization issues (enable temporarily, check logs, then disable)
• Development environments

Do not leave permissive mode enabled in production. It bypasses all authorization checks. Any client that can complete the TLS handshake (or any client at all, if TLS is also disabled) can call any API method.

You can also set permissive mode via environment variable without editing the config file:

1
CARBIDE_API_AUTH="{permissive_mode=true}"