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:

* Document the previously undocumented pid_file_name config option
* Add explanation of how cmd and cmd_args is interpreted
* 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
* Document that spiffe-helper restarts 'cmd' when it next rotates
  certificates if it's not running
* Remove reference to the un-released and now-unused -exitWhenReady flag

Signed-off-by: Craig Ringer <[email protected]>
  • Loading branch information
@ringerc
ringerc committed Feb 2, 2025
1 parent 29323c8 commit e1a06d0
Showing 1 changed file with 50 additions and 4 deletions.
54 changes: 50 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +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.

The flag `-exitWhenReady` is also supported.
CLI options:

| Flag name | Description |
|---------------------------------|---------------------------------------------------------------------|
| `-config` | Path to the configuration file |
| `-help` | Print interactive help |
| `-daemon-mode={true|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 @@ -38,6 +46,44 @@ The configuration file is an [HCL](https://github.com/hashicorp/hcl) formatted f
| `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` |


**Notes**:

* `cmd` and `cmd_args` are used in `daemon_mode` to launch the process that
will make use of the certificates.

The `cmd_args` will be split into individual arguments using space separation
unless the argument is enclosed in double quotes, which are consumed. The
command's stdout and stderr will be attached to spiffe-helper's stdout and
stderr but its stdin will be closed.

The process will not be launched for the first time until the certificates
are fetched successfully. If the process still exists 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 makes it possible for
the process to be a short-lived command that calls some non-signal-based
reload mechanism.

* If running in `daemon_mode` with a `renew_signal` and `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.

* `daemon_mode` does *not* cause `spiffe-helper` to run as a daemon in the unix
sense - it does not fork or detach from the terminal. It simply runs in a
loop, fetching and renewing certificates until it is terminated.

* If `daemon_mode` is false no command(s) will be run and no pid file will be
signalled.

* `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`.

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

Expand Down

0 comments on commit e1a06d0

Please sign in to comment.