# The helper contract
Provisioner ships no knowledge of any particular site. It cannot name a node, reach a certificate
authority, pick a broker, or decide which policies a machine should carry, because every one of those
answers differs between deployments and most of them live in systems Provisioner has never heard of.
The helper supplies them. It is a program in any language, named by the `helper` configuration key,
that reads a JSON description of one server on standard input and writes that server's configuration
back on standard output.
The helper runs at the midpoint of the provisioning cycle, once per server. By the time Provisioner
calls it, the fetch steps have already collected everything the node can say about itself: its
verified `provisioning.jwt`, its inventory, and its CSR or ed25519 public key, depending on the
enrollment model. The helper turns that description into a decision. It can return a configuration
map, x509 credentials, a signed-token request, Open Policy Agent and Action Policy documents, and a
version to upgrade to. It can also refuse: `defer` leaves the node unconfigured for a later cycle, and
`shutdown` stops it. Provisioner takes whatever comes back, sends it to the node in a single
`configure` call, and restarts the node.
{{% notice style="note" title="Where it lives" %}}
`host/helper.go`, 131 lines. `getConfig` at `host/helper.go:38` marshals the input,
`runDecodedHelper` decodes the reply, and `runHelper` at `host/helper.go:68` starts the child process
and waits on it.
{{% /notice %}}
## One exec per server
A fresh process per server, so no state carries over between calls.
## What the helper receives
`getConfig` marshals the `Host` itself, so the input shape is exactly the struct's exported fields
(`host/host.go:29-51`). The JSON-tagged fields are the only ones the helper sees; every other field on
`Host` is unexported and stays in the process.
identity
The Choria Server identity, typically the fully qualified domain name.
csr
A provision.CSRReply, non-null only when features.pki is enabled.
ed25519_pubkey
A provision.ED25519Reply, non-null only when features.ed25519 is enabled.
inventory
The rpcutil#inventory result. A JSON string, not a nested object.
jwt
The parsed and already-verified provisioning.jwt claims, non-null only when features.jwt is enabled.
{{% notice style="warning" title="Caveat" %}}
`inventory` is a string containing JSON, because `fetchInventory` assigns
`h.Metadata = string(j)` from the RPC reply. A helper has to decode it a second time to reach the
facts, the agent list, or the version. The `identity` value at the top level and the one inside the
inventory come from different sources, so a helper that needs the identity should use the top-level
field.
{{% /notice %}}
The token, the signing keys, and the helper path itself are not sent. A helper that needs a secret
reads it from its own environment or files.
## What the helper returns
The reply decodes into `host.ConfigResponse` (`host/helper.go:23`). Unknown keys are ignored and every
field is optional, so a minimal helper answers with a `configuration` object alone.
```go
type ConfigResponse struct {
Defer bool `json:"defer"`
Shutdown bool `json:"shutdown"`
Msg string `json:"msg"`
Key string `json:"key"`
Certificate string `json:"certificate"`
CA string `json:"ca"`
SSLDir string `json:"ssldir"`
ServerClaims *tokens.ServerClaims `json:"server_claims"`
Configuration map[string]string `json:"configuration"`
ActionPolicies map[string]string `json:"action_policies"`
OPAPolicies map[string]string `json:"opa_policies"`
UpgradeVersion string `json:"upgrade"`
}
```
`Provision` checks `defer` and `shutdown` first, and either one ends the cycle. `upgrade` diverts to
the upgrade path. `Provision` copies the rest onto the `Host` and sends it to the node in the single
`configure` RPC. [The provisioning cycle]({{% relref "provisioning-cycle" %}}) gives the order those
checks run in, and [Writing a helper]({{% relref "/configuration/helper" %}}) gives worked examples in
Ruby.
## The child process
`runHelper` runs these steps in order.
Timing starts first A prometheus.NewTimer on choria_provisioner_helper_time is deferred before anything else, so a timed-out helper still records its duration.
The pause flag is checked A paused instance refuses to start the helper, and the error includes the helper path.
A 10 second timeout is appliedcontext.WithTimeout(ctx, 10*time.Second) wraps the whole call. No configuration key sets the value.
The command string is split with shellquoteshellquote.Split handles quoting, so helper can carry arguments, for example /opt/prov/helper.rb --site london. An empty result is rejected.
Input is written from a goroutine The write to stdin runs concurrently with the read from stdout and closes the pipe on completion. Doing both in one goroutine would deadlock on any helper whose output exceeds the pipe buffer.
Output is read to completion, then the process is waited on Reading before Wait is required: Wait closes the pipes.
Zero bytes is an error A helper that exits cleanly without writing anything fails with "zero bytes received" rather than producing an empty configuration.
The exit code is checkedProcessState.Success() must be true.
{{% notice style="warning" title="Caveat" %}}
`runHelper` sets a stdin and a stdout pipe but leaves `Stderr` nil, and `os/exec` connects a nil
`Stderr` to the null device. Anything a helper writes to standard error is discarded and never reaches
the Provisioner log. A helper that has a reason to report should return `defer` with a `msg`, which is
logged, or write its own log file.
{{% /notice %}}
`Provision` counts the failures. It increments `choria_provisioner_helper_errors` when `getConfig`
returns an error (`host/host.go:134`), and the successful shutdown path increments
`choria_provisioner_helper_shutdown_requests` from `host/rpc.go:169`.
{{% notice style="tip" title="Next" %}}
[Security and enrollment]({{% relref "security" %}}) covers what happens to the key material that the
helper returns.
{{% /notice %}}