aboutsummaryrefslogtreecommitdiffstats
path: root/lacme-accountd.1
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@fripost.org>2016-06-13 23:14:00 +0200
committerGuilhem Moulin <guilhem@fripost.org>2016-06-13 23:14:00 +0200
commit08d9f95505bb11c3d1b6a8c649362ede7dab4138 (patch)
treeacc9aa7f86e28d61a0c3f26e30f8a07848f668a5 /lacme-accountd.1
parentd038f67d1e075010d36272595ea845e2f57e55ac (diff)
Rename ‘letsencrypt-tiny’ to ‘lacme’.
Diffstat (limited to 'lacme-accountd.1')
-rw-r--r--lacme-accountd.1152
1 files changed, 152 insertions, 0 deletions
diff --git a/lacme-accountd.1 b/lacme-accountd.1
new file mode 100644
index 0000000..46a6a0d
--- /dev/null
+++ b/lacme-accountd.1
@@ -0,0 +1,152 @@
+.TH LACME\-ACCOUNTD "1" "MARCH 2016" "ACME client (account key manager)" "User Commands"
+
+.SH NAME
+lacme\-accountd \- ACME client (account key manager)
+
+.SH SYNOPSIS
+.B lacme\-accountd\fR [\fB\-\-config=\fIFILENAME\fR]
+[\fB\-\-privkey=\fIARG\fR] [\fB\-\-socket=\fIPATH\fR] [\fB\-\-quiet\fR]
+
+
+.SH DESCRIPTION
+.PP
+.B lacme\-accountd\fR is the account key manager component of
+\fIlacme\fR(1), a tiny ACME client written with process isolation and
+minimal privileges in mind. No other \fIlacme\fR(1) component need
+access to the account key; in fact the account key could also be stored
+on a smartcard.
+
+.B lacme\-accountd\fR binds to a UNIX\-domain socket (specified with
+\fB\-\-socket=\fR), which ACME clients can connect to in order to
+request data signatures.
+As a consequence, \fBlacme\-accountd\fR needs to be up and running
+before using \fIlacme\fR(1) to issue ACME commands. Also, the process
+does not automatically terminate after the last signature request:
+instead, one sends an \fIINT\fR or \fITERM\fR signal to bring the server
+down.
+
+Furthermore, one can use the UNIX\-domain socket forwarding facility of
+OpenSSH 6.7 and later to run \fBlacme\-accountd\fR and \fIlacme\fR(1) on
+different hosts. For instance one could store the account key on a
+machine that is not exposed to the internet. See the \fBEXAMPLES\fR
+section below.
+
+
+.SH OPTIONS
+.TP
+.B \-\-config=\fIfilename\fR
+Use \fIfilename\fR as configuration file. See the \fBCONFIGURATION
+FILE\fR section below for the configuration options.
+
+.TP
+.B \-\-privkey=\fIarg\fR
+Specify the (private) account key to use for signing requests.
+Currently supported \fIarg\fRuments are:
+
+.RS
+.IP \[bu] 2
+file:\fIFILE\fR, to specify an encrypted private key (in PEM format); and
+.IP \[bu]
+gpg:\fIFILE\fR, to specify a \fIgpg\fR(1)\-encrypted private key (in PEM format).
+
+.PP
+The following command can be used to generate a new 4096\-bits RSA key in
+PEM format with mode 0600:
+
+.nf
+ openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/priv.key
+.fi
+.RE
+
+.TP
+.B \-\-socket=\fIpath\fR
+Use \fIpath\fR as the UNIX\-domain socket to bind against for signature
+requests from the ACME client. \fBlacme\-accountd\fR aborts if
+\fIpath\fR exists or if its parent directory is writable by other users.
+
+.TP
+.B \-?\fR, \fB\-\-help\fR
+Display a brief help and exit.
+
+.TP
+.B \-q\fR, \fB\-\-quiet\fR
+Be quiet.
+
+.TP
+.B \-\-debug
+Turn on debug mode.
+
+
+.SH CONFIGURATION FILE
+If \fB\-\-config=\fR is not given, \fBlacme\-accountd\fR uses the first
+existing configuration file among \fI./lacme\-accountd.conf\fR,
+\fI$XDG_CONFIG_HOME/lacme/lacme\-accountd.conf\fR (or
+\fI~/.config/lacme/lacme\-accountd.conf\fR if the XDG_CONFIG_HOME
+environment variable is not set), and
+\fI/etc/lacme/lacme\-accountd.conf\fR.
+
+When given on the command line, the \fB\-\-privkey=\fR,
+\fB\-\-socket=\fR and \fB\-\-quiet\fR options take precedence over their
+counterpart (without leading \(lq\-\-\(rq) in the configuration file.
+Valid options are:
+
+.TP
+.I privkey
+See \fB\-\-privkey=\fR.
+This option is required when \fB\-\-privkey=\fR is not specified on the
+command line.
+
+.TP
+.I gpg
+For a \fIgpg\fR(1)\-encrypted private account key, specify the binary
+\fIgpg\fR(1) to use, as well as some default options.
+Default: \(lqgpg \-\-quiet\(rq.
+
+.TP
+.I socket
+See \fB\-\-socket=\fR.
+Default: \(lq$XDG_RUNTIME_DIR/S.lacme\(rq if the XDG_RUNTIME_DIR
+environment variable is set.
+
+.TP
+.I quiet
+Be quiet. Possible values: \(lqYes\(rq/\(lqNo\(rq.
+
+
+.SH EXAMPLES
+
+Run \fBlacme\-accountd\fR in a first terminal:
+
+.nf
+ ~$ lacme\-accountd \-\-privkey=file:/path/to/priv.key \-\-socket=/run/user/1000/S.lacme
+.fi
+
+Then, while \fBlacme\-accountd\fR is running, execute locally
+\fIlacme\fR(1) in another terminal:
+
+.nf
+ ~$ sudo lacme \-\-socket=/run/user/1000/S.lacme new\-cert
+.fi
+
+Alternatively, use \fIssh\fR(1) to forward the socket and execute
+\fIlacme\fR(1) remotely:
+
+.nf
+ ~$ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:/run/user/1000/S.lacme user@example.org \\
+ sudo lacme --socket=/path/to/remote.sock new-cert
+.fi
+
+
+.SH SEE ALSO
+\fBlacme\fR(1), \fBssh\fR(1)
+
+.SH AUTHOR
+.ie \n[www-html] \{\
+ Written by
+. MTO guilhem@fripost.org "Guilhem Moulin" .
+\}
+.el \{\
+ Written by Guilhem Moulin
+. MT guilhem@fripost.org
+. ME .
+\}