aboutsummaryrefslogtreecommitdiffstats
path: root/lacme-accountd.1
blob: 46a6a0d3823762d33835dec297e918c35828ea0a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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 .
\}