.\"t
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "lacme-accountd" "1" "March 2016" "" ""
.hy
.SH NAME
.PP
lacme-accountd - ACME client written with process isolation and minimal
privileges in mind (account key manager)
.SH SYNOPSIS
.PP
\f[C]lacme-accountd\f[R] [\f[C]--config=FILENAME\f[R]]
[\f[C]--privkey=ARG\f[R]] [\f[C]--socket=PATH\f[R]] [\f[C]--quiet\f[R]]
.SH DESCRIPTION
.PP
\f[C]lacme-accountd\f[R] is the account key manager component of
\f[C]lacme\f[R](8), a small ACME client written with process isolation
and minimal privileges in mind.
No other \f[C]lacme\f[R](8) component needs access to the account key;
in fact the account key could as well be stored on another host or a
smartcard.
.PP
\f[C]lacme-accountd\f[R] binds to a UNIX-domain socket (specified with
\f[C]--socket=\f[R]), which ACME clients can connect to in order to
request data signatures.
As a consequence, \f[C]lacme-accountd\f[R] needs to be up and running
before using \f[C]lacme\f[R](8) to issue ACME commands.
Also, the process does not automatically terminate after the last
signature request: instead, one sends an \f[C]INT\f[R] or \f[C]TERM\f[R]
\f[C]signal\f[R](7) to bring the server down.
.PP
Furthermore, one can use the UNIX-domain socket forwarding facility of
OpenSSH 6.7 and later to run \f[C]lacme-accountd\f[R] and
\f[C]lacme\f[R](8) on different hosts.
For instance one could store the account key on a machine that is not
exposed to the internet.
See the \f[B]examples\f[R] section below.
.SH OPTIONS
.TP
\f[B]\f[CB]--config=\f[B]\f[R]\f[I]filename\f[R]
Use \f[I]filename\f[R] as configuration file instead of
\f[C]%E/lacme/lacme-accountd.conf\f[R].
The value is subject to %-specifier expansion.
\f[C]lacme-accountd\f[R] fails when \f[C]--config=\f[R] is used with a
non-existent file, but a non-existent default location is treated as if
it were an empty file.
.RS
.PP
See the \f[B]configuration file\f[R] section below for the configuration
options.
.RE
.TP
\f[B]\f[CB]--privkey=\f[B]\f[R]\f[I]value\f[R]
Specify the (private) account key to use for signing requests.
Currently supported \f[I]value\f[R]s are:
.RS
.IP \[bu] 2
\f[C]file:\f[R]\f[I]FILE\f[R], for a private key in PEM format
(optionally symmetrically encrypted)
.IP \[bu] 2
\f[C]gpg:\f[R]\f[I]FILE\f[R], for a \f[C]gpg\f[R](1)-encrypted private
key
.PP
\f[I]FILE\f[R] is subject to %-specifier expansion.
.PP
The \f[C]genpkey\f[R](1ssl) command can be used to generate a new
private (account) key:
.IP
.nf
\f[C]
$ install -vm0600 /dev/null /path/to/account.key
$ openssl genpkey -algorithm RSA -out /path/to/account.key
\f[R]
.fi
.PP
Currently \f[C]lacme-accountd\f[R] only supports RSA account keys.
.RE
.TP
\f[B]\f[CB]--socket=\f[B]\f[R]\f[I]path\f[R]
Use \f[I]path\f[R] as the UNIX-domain socket to bind to for signature
requests from the ACME client.
The value is subject to %-specifier expansion.
\f[C]lacme-accountd\f[R] aborts if \f[I]path\f[R] exists or if its
parent directory is writable by other users.
Default: \f[C]%t/S.lacme\f[R] (omitting \f[C]--socket=\f[R] therefore
yields an error when \f[C]lacme-accountd\f[R] doesn\[cq]t run as and the
\f[C]XDG_RUNTIME_DIR\f[R] environment variable is unset or empty).
.TP
\f[B]\f[CB]--stdio\f[B]\f[R]
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 \f[I]internal\f[R] flag should never be used by standalone
\f[C]lacme-accountd\f[R] instances, only for those \f[C]lacme\f[R](8)
spawns.
.TP
\f[B]\f[CB]-h\f[B]\f[R], \f[B]\f[CB]--help\f[B]\f[R]
Display a brief help and exit.
.TP
\f[B]\f[CB]-q\f[B]\f[R], \f[B]\f[CB]--quiet\f[B]\f[R]
Be quiet.
.TP
\f[B]\f[CB]--debug\f[B]\f[R]
Turn on debug mode.
.SH CONFIGURATION FILE
.PP
When given on the command line, the \f[C]--privkey=\f[R],
\f[C]--socket=\f[R] and \f[C]--quiet\f[R] options take precedence over
their counterpart (without leading \f[C]--\f[R]) in the configuration
file.
Valid settings are:
.TP
\f[I]privkey\f[R]
See \f[C]--privkey=\f[R].
This setting is required when \f[C]--privkey=\f[R] is not specified on
the command line.
.TP
\f[I]gpg\f[R]
For a \f[C]gpg\f[R](1)-encrypted private account key, specify the binary
\f[C]gpg\f[R](1) to use, as well as some default options.
Default: \f[C]gpg --quiet\f[R].
.TP
\f[I]socket\f[R]
See \f[C]--socket=\f[R].
.TP
\f[I]logfile\f[R]
An optional file where to log to.
The value is subject to %-specifier expansion.
.TP
\f[I]keyid\f[R]
The \[lq]Key ID\[rq], as shown by \f[C]\[ga]acme account\[ga]\f[R], to
give the ACME client.
With an empty \f[I]keyid\f[R] (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.
.RS
.PP
A non-empty value also causes \f[C]lacme-accountd\f[R] to send an empty
JWK, thereby revoking all account management access (status change,
contact address updates etc.) from the client: any
\f[C]\[ga]acme account\[ga]\f[R] command (or any command from
\f[C]lacme\f[R](8) before version 0.8.0) is bound to be rejected by the
ACME server.
This provides a safeguard against malicious clients.
.RE
.TP
\f[I]quiet\f[R]
Be quiet.
Possible values: \f[C]Yes\f[R]/\f[C]No\f[R].
.SH %-SPECIFIERS
.PP
The value the \f[C]--config=\f[R], \f[C]--privkey=\f[R] and
\f[C]--socket=\f[R] CLI options (and also the \f[I]privkey\f[R],
\f[I]socket\f[R] and \f[I]logfile\f[R] settings from the configuration
file) are subject to %-expansion for the following specifiers.
.PP
.TS
tab(@);
lw(5.8n) lw(64.2n).
T{
\f[C]%C\f[R]
T}@T{
\f[C]/var/cache\f[R] for the root user, and \f[C]$XDG_CACHE_HOME\f[R]
for other users (or \f[C]$HOME/.cache\f[R] if the
\f[C]XDG_CACHE_HOME\f[R] environment variable is unset or empty).
T}
T{
\f[C]%E\f[R]
T}@T{
\f[C]/etc\f[R] for the root user, and \f[C]$XDG_CONFIG_HOME\f[R] for
other users (or \f[C]$HOME/.config\f[R] if the \f[C]XDG_CONFIG_HOME\f[R]
environment variable is unset or empty).
T}
T{
\f[C]%g\f[R]
T}@T{
Current group name.
T}
T{
\f[C]%G\f[R]
T}@T{
Current group ID.
T}
T{
\f[C]%h\f[R]
T}@T{
Home directory of the current user.
T}
T{
\f[C]%t\f[R]
T}@T{
\f[C]/run\f[R] for the root user, and \f[C]$XDG_RUNTIME_DIR\f[R] for
other users.
Non-root users may only use \f[C]%t\f[R] when the
\f[C]XDG_RUNTIME_DIR\f[R] environment variable is set to a non-empty
value.
T}
T{
\f[C]%T\f[R]
T}@T{
\f[C]$TMPDIR\f[R], or \f[C]/tmp\f[R] if the \f[C]TMPDIR\f[R] environment
variable is unset or empty.
T}
T{
\f[C]%u\f[R]
T}@T{
Current user name.
T}
T{
\f[C]%U\f[R]
T}@T{
Current user ID.
T}
T{
\f[C]%%\f[R]
T}@T{
A literal \f[C]%\f[R].
T}
.TE
.SH EXAMPLES
.PP
Run \f[C]lacme-accountd\f[R] in a first terminal:
.IP
.nf
\f[C]
$ lacme-accountd --privkey=file:/path/to/account.key --socket=$XDG_RUNTIME_DIR/S.lacme
\f[R]
.fi
.PP
Then, while \f[C]lacme-accountd\f[R] is running, execute locally
\f[C]lacme\f[R](8) in another terminal:
.IP
.nf
\f[C]
$ sudo lacme --socket=$XDG_RUNTIME_DIR/S.lacme newOrder
\f[R]
.fi
.PP
Alternatively, use OpenSSH 6.7 or later to forward the socket and
execute \f[C]lacme\f[R](8) remotely:
.IP
.nf
\f[C]
$ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:$XDG_RUNTIME_DIR/S.lacme user\[at]example.org \[rs]
    sudo lacme --socket=/path/to/remote.sock newOrder
\f[R]
.fi
.PP
Consult the \f[C]lacme\f[R](8) manual for a solution involving
connecting to \f[C]lacme-accountd\f[R] on a dedicated remote host.
Doing so enables automatic renewal via \f[C]crontab\f[R](5) or
\f[C]systemd.timer\f[R](5).
.SH BUGS AND FEEDBACK
.PP
Bugs or feature requests for \f[C]lacme-accountd\f[R] should be filed
with the Debian project\[cq]s bug tracker at
<https://www.debian.org/Bugs/>.
.SH SEE ALSO
.PP
\f[C]lacme\f[R](8), \f[C]ssh\f[R](1)
.SH AUTHORS
Guilhem Moulin (mailto:guilhem@fripost.org).