Skip to content

Commit

Permalink
Document pid_file_name and explain some other flags
Browse files Browse the repository at this point in the history 
Update the README to:

* Explain the different modes spiffe-helper can be used in and how
  they relate to the configuration settings.
* Document the previously undocumented pid_file_name config option
* Document that spiffe-helper restarts 'cmd' when it next rotates
  certificates if it's not running
* Document that spiffe-helper does NOT restart 'cmd' until the next
  cert rotation if it exits.
* Add explanation of how cmd and cmd_args is interpreted
* Warn about surprises in cmd_args parsing with single quotes
* Warn that stdin is not forwarded, and the exit code of the child
  process is not forwarded on exit, so spiffe-helper cannot be used
  as a pass-through wrapper for another command
* Explicitly note that `cmd_args` is not subject to shell metacharacter
  expansion

Signed-off-by: Craig Ringer <[email protected]>
  • Loading branch information
@ringerc
ringerc committed Feb 4, 2025
1 parent 8d77e4a commit 625be07
Showing 1 changed file with 111 additions and 3 deletions.
114 changes: 111 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,26 @@ The SPIFFE Helper is a simple utility for fetching X.509 SVID certificates from

If `-config` is not specified, the default value `helper.conf` is assumed.

CLI options:

| Flag name | Description |
|---------------------------------|---------------------------------------------------------------------|
| `-config` | Path to the configuration file |
| `-help` | Print interactive help |
| `-daemon-mode={true\|false}` | Boolean true or false. Overrides `daemon_mode` in the config file. |

## Configuration

The configuration file is an [HCL](https://github.com/hashicorp/hcl) formatted file that defines the following configurations:

| Configuration | Description | Example Value |
|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `agent_address` | Socket address of SPIRE Agent. | `"/tmp/agent.sock"` |
| `cmd` | The path to the process to launch. | `"ghostunnel"` |
| `cmd_args` | The arguments of the process to launch. | `"server --listen localhost:8002 --target localhost:8001--keystore certs/svid_key.pem --cacert certs/svid_bundle.pem --allow-uri-san spiffe://example.org/Database"` |
| `cmd` | The path to the process to launch and monitor and signal for certificate renewals. Ignored if `daemon_mode=false` | `"ghostunnel"` |
| `cmd_args` | The arguments of the process to launch. Split by spaces into an argument vector. | `"server --listen localhost:8002 --target localhost:8001--keystore certs/svid_key.pem --cacert certs/svid_bundle.pem --allow-uri-san spiffe://example.org/Database"` |
| `pid_file_name` | Path to a file containing a process ID to signal when certificates are renewed. Not required when using 'cmd'. | `"/var/run/ghostunnel.pid"` |
| `cert_dir` | Directory name to store the fetched certificates. This directory must be created previously. | `"certs"` |
| `daemon_mode` | Toggle running as a daemon, keeping X.509 and JWT up to date; or just fetch X.509 and JWT and exit 0 | `true` |
| `daemon_mode` | Toggle running as a daemon, keeping X.509 and JWT up to date; or just fetch X.509 and JWT and exit 0. Does not background itself. | `true` |
| `add_intermediates_to_bundle` | Add intermediate certificates into Bundle file instead of SVID file. | `true` |
| `renew_signal` | The signal that the process to be launched expects to reload the certificates. It is not supported on Windows. | `"SIGUSR1"` |
| `svid_file_name` | File name to be used to store the X.509 SVID public certificate in PEM format. | `"svid.pem"` |
Expand All @@ -35,6 +45,104 @@ The configuration file is an [HCL](https://github.com/hashicorp/hcl) formatted f
| `key_file_mode` | The octal file mode to use when saving the X.509 private key file. | `0600` |
| `jwt_bundle_file_mode` | The octal file mode to use when saving a JWT Bundle file. | `0600` |
| `jwt_svid_file_mode` | The octal file mode to use when saving a JWT SVID file. | `0600` |
### Operating modes and configuration details

spiffe-helper has two primary operating modes - "daemon mode" (the default),
where it runs continuously and manages the certificates, and "non-daemon mode",
where it fetches the certificates once and exits.

The helper can be used in several ways, as detailed below:

* Run a command that uses the certificates, and signal it when they are renewed.
* Run a command that reloads an external process when the certificates are renewed.
* Signal an external process when the certificates are renewed.
* Fetch the certificates once and exit.

Note that "daemon mode" does not actually detach itself from the controlling
process and background itself like a unix "daemon". It just keeps running until
terminated by a signal or a fatal error.

#### Use in daemon-mode with file watcher

If the process using the certificates can watch the on-disk files for changes,
spiffe-helper can be run in `daemon_mode` with no `cmd` or `pid_file_name`. It
will fetch and renew the certificates, overwrite them on disk, and the process
will pick up the changes.

This approach is recommended where possible.

#### Use in daemon-mode with `cmd` to run a process or a reload command

`cmd` and `cmd_args` are used in `daemon_mode` to run a command whenever the
certificates are renewed. This can be a long-lived process that uses the
certificates, or a short-lived command that signals a reload mechanism
for an externally-managed process.

The `cmd_args` will be split into individual arguments using space separation
unless the argument is enclosed in double quotes, which are consumed. Single quotes
are NOT respected for argument quoting, so `cmd` = `touch` and `cmd_args` =
`'some file'` will create two files named `'some` and `file'` (including the quotes
in the file name), not a single file named `some file`.

`cmd_args` is *not* subject to shell expansion or interpretation. If you need
to use shell features, you must invoke a shell explicitly, e.g. `cmd =
"/bin/sh"` and `cmd_args = "-c \"echo hello\""`. Be careful with shell
invocations, as they can introduce security vulnerabilities and should be
avoided where possible.

The command's stdout and stderr will be attached to spiffe-helper's stdout
and stderr. Its stdin will be closed.

The process will not be launched for the first time until the certificates
are fetched successfully.

`spiffe-helper` continues running if the process created by `cmd` exits. The
process is not re-launched immediately if it exits.

If the process is still running next time the certs are renewed,
`spiffe-helper` will signal it with `renew_signal`. If it has exited,
`spiffe-helper` will re-launch it instead. This can be used to manage
certificate reloading in externally-managed processes that do not support
reloading certificates with a signal.

#### Use in daemon-mode with `pid_file_name` to signal an externally-managed process

If running in `daemon_mode` with `pid_file_name` set, the pid in
`pid_file_name` is sent the signal `renew_signal` to reload the certificates
when they are renewed.

`pid_file_name` is re-read every time the process is to be signaled, so it can
be updated with a new pid if the process changes.

An error will be logged if the pid file cannot be opened, read, or the value
parsed, and the attempt to signal the process will be skipped. The process will
still be signalled next time the certificates are renewed.

#### Combining `cmd` and `pid_file_name`

Both `cmd` and `pid_file_name` can be used at the same time. `spiffe-helper` will
both run the specified command and signal the process in the pid file. This can be
useful to use `cmd` to start the process to be managed, and `pid_file_name` to signal
a reload mechanism that is not signal-based.

#### Use in one-shot non-daemon mode

If `daemon_mode` is false, `spiffe-helper` will fetch the certificates once and
exit. This can be useful for one-shot scripts or for use in a process supervisor
that does not require a long-lived process.

`cmd` and `pid_file_name` are ignored in non-daemon mode. No command will be
run and no signals will be sent.

`spiffe-helper` cannot be used as a transparent wrapper around another
command because it does not forward stdin, signals, file descriptors, exit
when the child process exits, or return the managed process's exit code as
its own exit code. Instead, consider running the other process separately,
under the control of a proper process supervisor like systemd, and signaling
it via `pid_file_name`.

:warning: A future release may support running a command in non-daemon mode, so
it is recommended to leave `cmd` blank if `daemon_mode` is false.

### Health Checks Configuration
SPIFFE Helper can expose and endpoint that can be used for health checking
Expand Down

0 comments on commit 625be07

Please sign in to comment.