aboutsummaryrefslogtreecommitdiffstats
path: root/lacme-accountd.1.md
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@debian.org>2021-02-22 03:30:32 +0100
committerGuilhem Moulin <guilhem@debian.org>2021-02-22 03:30:32 +0100
commitd1be19ea9484f4c48af2de54266465d49bb1281d (patch)
tree768da9388a9ea6ed42d8d818a6433a4871a1172e /lacme-accountd.1.md
parent847ae99fb1ed73fd77c6ffd30f2c554ab5892fde (diff)
parent3eba02ef820a393bd5781be9f8fcda1611ae7c3d (diff)
Merge tag 'v0.8.0' into debian/latest
Release version 0.8.0
Diffstat (limited to 'lacme-accountd.1.md')
-rw-r--r--lacme-accountd.1.md135
1 files changed, 107 insertions, 28 deletions
diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md
index a967b67..4933a78 100644
--- a/lacme-accountd.1.md
+++ b/lacme-accountd.1.md
@@ -41,30 +41,53 @@ Options
`--config=`*filename*
-: Use *filename* as configuration file. See the **[configuration
- file](#configuration-file)** section below for the configuration
- options.
+: Use *filename* as configuration file instead of
+ `%E/lacme/lacme-accountd.conf`. The value is subject to
+ [%-specifier expansion](#percent-specifiers). `lacme-accountd`
+ fails when `--config=` is used with a non-existent file, but a
+ non-existent default location is treated as if it were an empty
+ file.
-`--privkey=`*arg*
+ See the **[configuration file](#configuration-file)** section below
+ for the configuration options.
+
+`--privkey=`*value*
: Specify the (private) account key to use for signing requests.
- Currently supported *arg*uments are:
+ Currently supported *value*s are:
+
+ * `file:`*FILE*, for a private key in PEM format (optionally
+ symmetrically encrypted)
+ * `gpg:`*FILE*, for a [`gpg`(1)]-encrypted private key
+
+ *FILE* is subject to [%-specifier expansion](#percent-specifiers).
- * `file:`*FILE*, to specify an encrypted private key (in PEM
- format); and
- * `gpg:`*FILE*, to specify a [`gpg`(1)]-encrypted private key (in
- PEM format).
+ The [`genpkey`(1ssl)] command can be used to generate a new private
+ (account) key:
- The following command can be used to generate a new 4096-bits RSA
- key in PEM format with mode 0600:
+ $ install -vm0600 /dev/null /path/to/account.key
+ $ openssl genpkey -algorithm RSA -out /path/to/account.key
- openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/account.key
+ Currently `lacme-accountd` only supports RSA account keys.
`--socket=`*path*
-: Use *path* as the UNIX-domain socket to bind against for signature
- requests from the [ACME] client. `lacme-accountd` aborts if *path*
- exists or if its parent directory is writable by other users.
+: Use *path* as the UNIX-domain socket to bind to for signature
+ requests from the [ACME] client. The value is subject to
+ [%-specifier expansion](#percent-specifiers). `lacme-accountd`
+ aborts if *path* exists or if its parent directory is writable by
+ other users.
+ Default: `%t/S.lacme` (omitting `--socket=` therefore yields an
+ error when `lacme-accountd` doesn't run as and the `XDG_RUNTIME_DIR`
+ environment variable is unset or empty).
+
+`--stdio`
+
+: Read signature requests from the standard input and write signatures
+ to the standard output, instead of using a UNIX-domain socket for
+ communication with the [ACME] client.
+ This _internal_ flag should never be used by standalone
+ `lacme-accountd` instances, only for those [`lacme`(8)] spawns.
`-h`, `--help`
@@ -81,19 +104,13 @@ Options
Configuration file
==================
-If `--config=` is not given, `lacme-accountd` uses the first existing
-configuration file among *./lacme-accountd.conf*,
-*$XDG_CONFIG_HOME/lacme/lacme-accountd.conf* (or
-*~/.config/lacme/lacme-accountd.conf* if the `XDG_CONFIG_HOME`
-environment variable is not set), and *@@sysconfdir@@/lacme/lacme-accountd.conf*.
-
When given on the command line, the `--privkey=`, `--socket=` and
`--quiet` options take precedence over their counterpart (without
-leading `--`) in the configuration file. Valid options are:
+leading `--`) in the configuration file. Valid settings are:
*privkey*
-: See `--privkey=`. This option is required when `--privkey=` is not
+: See `--privkey=`. This setting is required when `--privkey=` is not
specified on the command line.
*gpg*
@@ -105,31 +122,90 @@ leading `--`) in the configuration file. Valid options are:
*socket*
: See `--socket=`.
- Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR`
- environment variable is set.
+
+*logfile*
+
+: An optional file where to log to. The value is subject to
+ [%-specifier expansion](#percent-specifiers).
+
+*keyid*
+
+: The "Key ID", as shown by `` `acme account` ``, to give the [ACME]
+ client. With an empty *keyid* (the default) the client forwards the
+ JSON Web Key (JWK) to the [ACME] server to retrieve the correct
+ value. A non-empty value therefore saves a round-trip.
+
+ A non-empty value also causes `lacme-accountd` to send an empty JWK,
+ thereby revoking all account management access (status change,
+ contact address updates etc.) from the client: any `` `acme account` ``
+ command (or any command from [`lacme`(8)] before version 0.8.0) is
+ bound to be rejected by the [ACME] server. This provides a
+ safeguard against malicious clients.
*quiet*
: Be quiet. Possible values: `Yes`/`No`.
+%-specifiers {#percent-specifiers}
+============
+
+The value the `--config=`, `--privkey=` and `--socket=` CLI options (and
+also the *privkey*, *socket* and *logfile* settings from the
+configuration file) are subject to %-expansion for the following
+specifiers.
+
+---- ------------------------------------------------------------------
+`%C` `@@localstatedir@@/cache` for the root user, and `$XDG_CACHE_HOME`
+ for other users (or `$HOME/.cache` if the `XDG_CACHE_HOME`
+ environment variable is unset or empty).
+
+`%E` `@@sysconfdir@@` for the root user, and `$XDG_CONFIG_HOME` for
+ other users (or `$HOME/.config` if the `XDG_CONFIG_HOME`
+ environment variable is unset or empty).
+
+`%g` Current group name.
+
+`%G` Current group ID.
+
+`%h` Home directory of the current user.
+
+`%t` `@@runstatedir@@` for the root user, and `$XDG_RUNTIME_DIR` for
+ other users. Non-root users may only use `%t` when the
+ `XDG_RUNTIME_DIR` environment variable is set to a non-empty
+ value.
+
+`%T` `$TMPDIR`, or `/tmp` if the `TMPDIR` environment variable is unset
+ or empty.
+
+`%u` Current user name.
+
+`%U` Current user ID.
+
+`%%` A literal `%`.
+---- ------------------------------------------------------------------
+
Examples
========
Run `lacme-accountd` in a first terminal:
- ~$ lacme-accountd --privkey=file:/path/to/account.key --socket=$XDG_RUNTIME_DIR/S.lacme
+ $ lacme-accountd --privkey=file:/path/to/account.key --socket=$XDG_RUNTIME_DIR/S.lacme
Then, while `lacme-accountd` is running, execute locally [`lacme`(8)] in
another terminal:
- ~$ sudo lacme --socket=$XDG_RUNTIME_DIR/S.lacme newOrder
+ $ sudo lacme --socket=$XDG_RUNTIME_DIR/S.lacme newOrder
Alternatively, use [OpenSSH] 6.7 or later to forward the socket and
execute [`lacme`(8)] remotely:
- ~$ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:$XDG_RUNTIME_DIR/S.lacme user@example.org \
+ $ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:$XDG_RUNTIME_DIR/S.lacme user@example.org \
sudo lacme --socket=/path/to/remote.sock newOrder
+Consult the [`lacme`(8) manual][`lacme`(8)] for a solution involving
+connecting to `lacme-accountd` on a dedicated remote host. Doing so
+enables automatic renewal via [`crontab`(5)] or [`systemd.timer`(5)].
+
See also
========
@@ -141,3 +217,6 @@ See also
[`gpg`(1)]: https://www.gnupg.org/documentation/manpage.en.html
[OpenSSH]: https://www.openssh.com/
[`ssh`(1)]: https://man.openbsd.org/ssh
+[`genpkey`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-genpkey.html
+[`crontab`(5)]: https://linux.die.net/man/5/crontab
+[`systemd.timer`(5)]: https://www.freedesktop.org/software/systemd/man/systemd.timer.html