aboutsummaryrefslogtreecommitdiffstats
path: root/letsencrypt.1
blob: acbf0d85533feadb30266b9a23e506a17867e0e2 (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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
.TH LETSENCRYPT "1" "MARCH 2016" "Tiny Let's Encrypt ACME client" "User Commands"

.SH NAME
letsencrypt \- Tiny Let's Encrypt ACME client

.SH SYNOPSIS
.B letsencrypt\fR [\fB\-\-config=\fIFILENAME\fR]
[\fB\-\-socket=\fIPATH\fR] [\fIOPTION\fR ...] \fICOMMAND\fR
[\fIARGUMENT\fR ...]


.SH DESCRIPTION
.PP
.B letsencrypt\fR is a tiny ACME client written with process isolation
and minimal privileges in mind.
It is divided into four components, each with its own executable:

.IP \[bu] 4
A \fIletsencrypt\-accountd\fR(1) process to manage the account key and
issue SHA\-256 signatures needed for each ACME command.
(This process binds to a UNIX\-domain socket to reply to signature
requests from the ACME client.)
One can use the UNIX\-domain socket forwarding facility of OpenSSH 6.7
and later to run \fIletsencrypt\-accountd\fR(1) and \fBletsencrypt\fR on
different hosts.

.IP \[bu] 4
A \(lqmaster\(rq \fBletsencrypt\fR process, which runs as root and is
the only component with access to the private key material of the server
keys.
It is used to fork the ACME client (and optionally the ACME webserver)
after dropping root privileges.
For certificate issuances (\fBnew\-cert\fR command), it also generates
Certificate Signing Requests, then verifies the validity of the issued
certificate, and optionally reloads or restarts services when the
\fInotify\fR option is set.

.IP \[bu] 4
An actual ACME client (specified with the \fIcommand\fR option of the
\(lq[client]\(rq section of the configuration file), which builds ACME
commands and dialogues with the remote ACME server.
Since ACME commands need to be signed with the account key, the
\(lqmaster\(rq \fBletsencrypt\fR process passes the
\fIletsencrypt\-accountd\fR(1) UNIX\-domain socket to the ACME client:
data signatures are requested by writing the data to be signed to the
socket.

.IP \[bu] 4
For certificate issuances (\fBnew\-cert\fR command), an optional
webserver (specified with the \fIcommand\fR option of the
\(lq[webserver]\(rq section of the configuration file), which is spawned
by the \(lqmaster\(rq \fBletsencrypt\fR process when no service is
listening on the HTTP port.
(The only challenge type currently supported by \fBletsencrypt\fR is
\(lqhttp\-01\(rq, which requires a webserver to answer challenges.)
That webserver only processes GET and HEAD requests under the
\(lq/.well\-known/acme\-challenge/\(rq URI.
By default some \fIiptables\fR(1) rules are automatically installed to
open the HTTP port, and removed afterwards.

.SH COMMANDS
.TP
.B letsencrypt \fR[\fB\-\-agreement\-uri=\fIURI\fR]\fB \fBnew\-reg \fR[\fICONTACT\fR ...]
Register the account key managed by \fIletsencrypt\-accountd\fR(1).  A
list of \fICONTACT\fR information (such as \(lqmaito:\(rq
URIs) can be specified in order for the server to contact the client for
issues related to this registration (such as notifications about
server\-initiated revocations).

\fB\-\-agreement\-uri=\fR can be used to specify a \fIURI\fR referring
to a subscriber agreement or terms of service provided by the server;
adding this options indicates the client's agreement with the referenced
terms.  Note that the server might require the client to agree to
subscriber agreement before performing any further actions.

If the account key is already registered, \fBletsencrypt\fR prints the
URI of the existing registration and aborts.

.TP
.B letsencrypt \fR[\fB\-\-agreement\-uri=\fIURI\fR]\fB \fBreg=\fIURI\fR \fR[\fICONTACT\fR ...]

Dump or edit the registration \fIURI\fR (relative to the ACME server URI,
which is specified with the \fIserver\fR option of the \(lq[client]\(rq
section of the configuration file).

When specified, the list of \fICONTACT\fR information and the agreement
\fIURI\fR are sent to the server to replace the existing values.

.TP
.B letsencrypt \fR[\fB\-\-config\-certs=\fIFILE\fR]\fB \fBnew\-cert \fR[\fISECTION\fR ...]

Read the certificate configuration \fIFILE\fR (see the \fBCERTIFICATE
CONFIGURATION FILE\fR section below for the configuration options), and
request new Certificate Issuance for each of its sections (or the given
list of \fISECTION\fRs).

.TP
.B letsencrypt \fBrevoke\-cert \fIFILE\fR [\fIFILE\fR ...]

Request that the given certificate(s) \fIFILE\fR(s) be revoked.  For
this command, \fIletsencrypt\-accountd\fR(1) can be pointed to either
the account key or the server's private key.


.SH GENERIC 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 \-\-socket=\fIpath\fR
Use \fIpath\fR as the \fIletsencrypt\-accountd\fR(1) UNIX\-domain socket
to connect to for signature requests from the ACME client.
\fBletsencrypt\fR aborts if \fIpath\fR is readable or writable by
other users, or if its parent directory is writable by other users.
This overrides the \fIsocket\fR option of the \(lq[client]\(rq section
of the configuration file.

.TP
.B \-?\fR, \fB\-\-help\fR
Display a brief help and exit.

.TP
.B \-\-debug
Turn on debug mode.


.SH CONFIGURATION FILE
If \fB\-\-config=\fR is not given, \fBletsencrypt\fR uses the first
existing configuration file among
\fI./letsencrypt.conf\fR,
\fI$XDG_CONFIG_HOME/letsencrypt\-tiny/letsencrypt.conf\fR (or
\fI~/.config/letsencrypt\-tiny/letsencrypt.conf\fR if the
XDG_CONFIG_HOME environment variable is not set), and
\fI/etc/letsencrypt\-tiny/letsencrypt.conf\fR.
Valid options are:

.TP
Default section
.RS
.TP
.I config\-certs
For certificate issuances (\fBnew\-cert\fR command), specify the
certificate configuration file to use (see the \fBCERTIFICATE
CONFIGURATION FILE\fR section below for the configuration options).
.RE

.TP
\(lq[client]\(rq section
This section is used for configuring the ACME client (which takes care
of ACME commands and dialogues with the remote ACME server).

.RS
.TP
.I socket
See \fB\-\-socket=\fR.
Default: \(lq$XDG_RUNTIME_DIR/S.letsencrypt\(rq if the XDG_RUNTIME_DIR
environment variable is set.

.TP
.I user
The username to drop privileges to (setting both effective and real
uid).
Preserve root privileges if the value is empty (not recommended).
Default: \(lqnobody\(rq.

.TP
.I group
The groupname to drop privileges to (setting both effective and real
gid, and also setting the list of supplementary gids to that single
group).  Preserve root privileges if the value is empty (not
recommended).
Default: \(lqnogroup\(rq.

.TP
.I command
Path to the ACME client executable.
Default: \(lq/usr/lib/letsencrypt\-tiny/client\(rq.

.TP
.I server
Root URI of the ACME server.
Default: \(lqhttps://acme\-v01.api.letsencrypt.org/\(rq.

.TP
.I timeout
Timeout in seconds after which the client stops polling the ACME server
and considers the request failed.
Default: \(lq10\(rq.

.TP
.I SSL_verify
Whether to verify the server certificate chain.
Default: \(lqYes\(rq.

.TP
.I SSL_version
Specify the version of the SSL protocol used to transmit data.

.TP
.I SSL_cipher_list
Specify the cipher list for the connection.
.RE

.TP
\(lq[webserver]\(rq section
This section is used for configuring the ACME webserver.

.RS
.TP
.I listen
Specify the local address to listen on, in the form
\fIADDRESS\fR[:\fIPORT\fR].
If \fIADDRESS\fR is enclosed with brackets \(oq[\(cq/\(oq]\(cq then it
denotes an IPv6; an empty \fIADDRESS\fR means \(oq0.0.0.0\(cq.
Default: \(lq:80\(rq.

.TP
.I challenge\-directory
If a webserver is already running, specify a non\-existent directory
under which the webserver is configured to serve GET requests for
challenge files under \(lq/.well\-known/acme\-challenge/\(rq (for each
virtual hosts requiring authorization) as static files.
Default: \(lq/var/www/acme\-challenge\(rq.

.TP
.I user
The username to drop privileges to (setting both effective and real
uid).
Preserve root privileges if the value is empty (not recommended).
Default: \(lqwww\-data\(rq.

.TP
.I group
The groupname to drop privileges to (setting both effective and real
gid, and also setting the list of supplementary gids to that single
group).  Preserve root privileges if the value is empty (not
recommended).
Default: \(lqwww\-data\(rq.

.TP
.I command
Path to the ACME webserver executable.
Default: \(lq/usr/lib/letsencrypt\-tiny/webserver\(rq.

.TP
.I iptables
Whether to automatically install \fIiptables\fR(1) rules to open the
\fIADDRESS\fR[:\fIPORT\fR] specified with \fIlisten\fR.
Theses rules are automatically removed once \fBletsencrypt\fR exits.
Default: \(lqYes\(rq.
.RE


.SH CERTIFICATE CONFIGURATION FILE
For certificate issuances (\fBnew\-cert\fR command), a separate file is
used to configure paths to the certificate and key, as well as the
subject, subjectAltName, etc. to generate Certificate Signing Requests.
If \fB\-\-config\-certs=\fR is not given, and if the
\fIconfig\-certs\fR configuration option is absent,
then \fBletsencrypt\fR uses the first existing configuration file among
\fI./letsencrypt\-certs.conf\fR,
\fI$XDG_CONFIG_HOME/letsencrypt\-tiny/letsencrypt\-certs.conf\fR (or
\fI~/.config/letsencrypt\-tiny/letsencrypt\-certs.conf\fR if the
XDG_CONFIG_HOME environment variable is not set), and
\fI/etc/letsencrypt\-tiny/letsencrypt\-certs.conf\fR.
Each section denotes a separate certificate issuance.
Valid options are:

.TP
.I certificate
Where to store the issued certificate (in PEM format).
At least one of \fIcertificate\fR or \fIcertificate\-chain\fR is
required.

.TP
.I certificate\-chain
Where to store the issued certificate, concatenated with the content of
the file specified specified with the \fICAfile\fR option (in PEM
format).
At least one of \fIcertificate\fR or \fIcertificate\-chain\fR is
required.

.TP
.I certificate\-key
Path the service's private key.  This option is required.  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

.TP
.I min\-days
For an existing certificate, the minimum number of days before its
expiration date the section is considered for re\-issuance.
Default: \(lq10\(rq.


.TP
.I CAfile
Path to the issuer's certificate.  This is used for
\fIcertificate\-chain\fR and to verify the validity of each issued
certificate.
Specifying an empty value skip certificate validation.
Default: \(lq/usr/share/letsencrypt\-tiny/lets\-encrypt\-x1\-cross\-signed.pem\(rq.

.TP
.I hash
Message digest to sign the Certificate Signing Request with.

.TP
.I keyUsage
Comma\-separated list of Key Usages, see \fIx509v3_config\fR(5ssl).

.TP
.I subject
Subject field of the Certificate Signing Request, in the form
\fR/\fItype0\fR=\fIvalue0\fR/\fItype1\fR=\fIvalue1\fR/\fItype2\fR=...
This option is required.

.TP
.I subjectAltName
Comma\-separated list of Subject Alternative Names, in the form
\fItype0\fR:\fIvalue1\fR,\fItype1\fR:\fIvalue1\fR,\fItype2\fR:...
The only \fItype\fR currently supported is \(lqDNS\(rq, to specify an
alternative domain name.

.TP
.I chown
An optional \fIusername\fR[:\fIgroupname\fR] to chown the issued
\fIcertificate\fR and \fIcertificate\-chain\fR with.

.TP
.I chmod
An optional octal mode to chmod the issued \fIcertificate\fR and
\fIcertificate\-chain\fR with.

.TP
.I notify
Command to pass the the system's command shell (\(lq/bin/sh \-c\(rq)
after successful installation of the \fIcertificate\fR and/or
\fIcertificate\-chain\fR.


.SH EXAMPLES

.nf
    ~$ sudo letsencrypt new-reg mailto:noreply@example.com
    ~$ sudo letsencrypt reg=/acme/reg/137760 --agreement-uri=https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf
    ~$ sudo letsencrypt new-cert
    ~$ sudo letsencrypt revoke-cert /path/to/server/certificate.pem
.fi


.SH SEE ALSO
\fBletsencrypt\-accountd\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 .
\}