aboutsummaryrefslogtreecommitdiffstats
path: root/letsencrypt-accountd.1
blob: a06cdcc0071a950c3e94657d4e47955f89b36c81 (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
.TH LETSENCRYPT\-ACCOUNTD "1" "MARCH 2016" "Tiny Let's Encrypt ACME client (account key manager)" "User Commands"

.SH NAME
letsencrypt\-accountd \- Tiny Let's Encrypt ACME client (account key manager)

.SH SYNOPSIS
.B letsencrypt\-accountd\fR [\fB\-\-config=\fIFILENAME\fR]
[\fB\-\-privkey=\fIARG\fR] [\fB\-\-socket=\fIPATH\fR] [\fB\-\-quiet\fR]


.SH DESCRIPTION
.PP
.B letsencrypt\-accountd\fR is the account key manager component of
\fIletsencrypt\fR(1), a tiny ACME client written with process isolation
and minimal privileges in mind.  No other \fIletsencrypt\fR(1) component
need access to the account key; in fact the account key could also be
stored on a smartcard.

.B letsencrypt\-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, \fBletsencrypt\-accountd\fR needs to be up and running
before using \fIletsencrypt\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 \fBletsencrypt\-accountd\fR and
\fIletsencrypt\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.  \fBletsencrypt\-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, \fBletsencrypt\-accountd\fR uses the
first existing configuration file among
\fI./letsencrypt\-accountd.conf\fR,
\fI$XDG_CONFIG_HOME/letsencrypt\-tiny/letsencrypt\-accountd.conf\fR (or
\fI~/.config/letsencrypt\-tiny/letsencrypt\-accountd.conf\fR if the
XDG_CONFIG_HOME environment variable is not set), and
\fI/etc/letsencrypt\-tiny/letsencrypt\-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.letsencrypt\(rq if the XDG_RUNTIME_DIR
environment variable is set.

.TP
.I quiet
Be quiet. Possible values: \(lqYes\(rq/\(lqNo\(rq.


.SH EXAMPLES

Run \fBletsencrypt\-accountd\fR in a first terminal:

.nf
    ~$ letsencrypt\-accountd \-\-privkey=file:/path/to/priv.key \-\-socket=/run/user/1000/S.letsencrypt
.fi

Then, while \fBletsencrypt\-accountd\fR is running, execute locally
\fIletsencrypt\fR(1) in another terminal:

.nf
    ~$ sudo letsencrypt \-\-socket=/run/user/1000/S.letsencrypt new\-cert
.fi

Alternatively, use \fIssh\fR(1) to forward the socket and execute
\fIletsencrypt\fR(1) remotely:

.nf
    ~$ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:/run/user/1000/S.letsencrypt user@example.org \\
       sudo letsencrypt --socket=/path/to/remote.sock new-cert
.fi


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