'\" t
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.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[V]lacme-accountd\f[R] [\f[V]--config=FILENAME\f[R]]
[\f[V]--privkey=ARG\f[R]] [\f[V]--socket=PATH\f[R]] [\f[V]--quiet\f[R]]
.SH DESCRIPTION
.PP
\f[V]lacme-accountd\f[R] is the account key manager component of
\f[V]lacme\f[R](8), a small ACME client written with process isolation
and minimal privileges in mind.
No other \f[V]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[V]lacme-accountd\f[R] binds to a UNIX-domain socket (specified with
\f[V]--socket=\f[R]), which ACME clients can connect to in order to
request data signatures.
As a consequence, \f[V]lacme-accountd\f[R] needs to be up and running
before using \f[V]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[V]INT\f[R] or \f[V]TERM\f[R]
\f[V]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[V]lacme-accountd\f[R] and
\f[V]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[V]--config=\f[R]\f[I]filename\f[R]
Use \f[I]filename\f[R] as configuration file instead of
\f[V]%E/lacme/lacme-accountd.conf\f[R].
The value is subject to %-specifier expansion.
\f[V]lacme-accountd\f[R] fails when \f[V]--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[V]--privkey=\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[V]file:\f[R]\f[I]FILE\f[R], for a private key in PEM format
(optionally symmetrically encrypted)
.IP \[bu] 2
\f[V]gpg:\f[R]\f[I]FILE\f[R], for a \f[V]gpg\f[R](1)-encrypted private
key
.PP
\f[I]FILE\f[R] is subject to %-specifier expansion.
.PP
The \f[V]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[V]lacme-accountd\f[R] only supports RSA account keys.
.RE
.TP
\f[V]--socket=\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[V]lacme-accountd\f[R] aborts if \f[I]path\f[R] exists or if its
parent directory is writable by other users.
Default: \f[V]%t/S.lacme\f[R] (omitting \f[V]--socket=\f[R] therefore
yields an error when \f[V]lacme-accountd\f[R] doesn\[cq]t run as and the
\f[V]XDG_RUNTIME_DIR\f[R] environment variable is unset or empty).
.TP
\f[V]--stdio\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[V]lacme-accountd\f[R] instances, only for those \f[V]lacme\f[R](8)
spawns.
.TP
\f[V]-h\f[R], \f[V]--help\f[R]
Display a brief help and exit.
.TP
\f[V]-q\f[R], \f[V]--quiet\f[R]
Be quiet.
.TP
\f[V]--debug\f[R]
Turn on debug mode.
.SH CONFIGURATION FILE
.PP
When given on the command line, the \f[V]--privkey=\f[R],
\f[V]--socket=\f[R] and \f[V]--quiet\f[R] options take precedence over
their counterpart (without leading \f[V]--\f[R]) in the configuration
file.
Valid settings are:
.TP
\f[I]privkey\f[R]
See \f[V]--privkey=\f[R].
This setting is required when \f[V]--privkey=\f[R] is not specified on
the command line.
.TP
\f[I]gpg\f[R]
For a \f[V]gpg\f[R](1)-encrypted private account key, specify the binary
\f[V]gpg\f[R](1) to use, as well as some default options.
Default: \f[V]gpg --quiet\f[R].
.TP
\f[I]socket\f[R]
See \f[V]--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[V]\[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[V]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[V]\[ga]acme account\[ga]\f[R] command (or any
command from \f[V]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[V]Yes\f[R]/\f[V]No\f[R].
.SH %-SPECIFIERS
.PP
The value the \f[V]--config=\f[R], \f[V]--privkey=\f[R] and
\f[V]--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[V]%C\f[R]
T}@T{
\f[V]/var/cache\f[R] for the root user, and \f[V]$XDG_CACHE_HOME\f[R]
for other users (or \f[V]$HOME/.cache\f[R] if the
\f[V]XDG_CACHE_HOME\f[R] environment variable is unset or empty).
T}
T{
\f[V]%E\f[R]
T}@T{
\f[V]/etc\f[R] for the root user, and \f[V]$XDG_CONFIG_HOME\f[R] for
other users (or \f[V]$HOME/.config\f[R] if the \f[V]XDG_CONFIG_HOME\f[R]
environment variable is unset or empty).
T}
T{
\f[V]%g\f[R]
T}@T{
Current group name.
T}
T{
\f[V]%G\f[R]
T}@T{
Current group ID.
T}
T{
\f[V]%h\f[R]
T}@T{
Home directory of the current user.
T}
T{
\f[V]%t\f[R]
T}@T{
\f[V]/run\f[R] for the root user, and \f[V]$XDG_RUNTIME_DIR\f[R] for
other users.
Non-root users may only use \f[V]%t\f[R] when the
\f[V]XDG_RUNTIME_DIR\f[R] environment variable is set to a non-empty
value.
T}
T{
\f[V]%T\f[R]
T}@T{
\f[V]$TMPDIR\f[R], or \f[V]/tmp\f[R] if the \f[V]TMPDIR\f[R] environment
variable is unset or empty.
T}
T{
\f[V]%u\f[R]
T}@T{
Current user name.
T}
T{
\f[V]%U\f[R]
T}@T{
Current user ID.
T}
T{
\f[V]%%\f[R]
T}@T{
A literal \f[V]%\f[R].
T}
.TE
.SH EXAMPLES
.PP
Run \f[V]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[V]lacme-accountd\f[R] is running, execute locally
\f[V]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[V]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[V]lacme\f[R](8) manual for a solution involving
connecting to \f[V]lacme-accountd\f[R] on a dedicated remote host.
Doing so enables automatic renewal via \f[V]crontab\f[R](5) or
\f[V]systemd.timer\f[R](5).
.SH BUGS AND FEEDBACK
.PP
Bugs or feature requests for \f[V]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[V]lacme\f[R](8), \f[V]ssh\f[R](1)
.SH AUTHORS
Guilhem Moulin (mailto:guilhem@fripost.org).