diff options
Diffstat (limited to 'lacme.1')
| -rw-r--r-- | lacme.1 | 364 |
1 files changed, 364 insertions, 0 deletions
@@ -0,0 +1,364 @@ +.TH LACME "1" "MARCH 2016" "ACME client" "User Commands" + +.SH NAME +lacme \- ACME client + +.SH SYNOPSIS +.B lacme\fR [\fB\-\-config=\fIFILENAME\fR] [\fB\-\-socket=\fIPATH\fR] +[\fIOPTION\fR ...] \fICOMMAND\fR [\fIARGUMENT\fR ...] + + +.SH DESCRIPTION +.PP +.B lacme\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 \fIlacme\-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 \fIlacme\-accountd\fR(1) and \fBlacme\fR on different +hosts. + +.IP \[bu] 4 +A \(lqmaster\(rq \fBlacme\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 \fBlacme\fR process passes the \fIlacme\-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 \fBlacme\fR process when no service is listening +on the HTTP port. +(The only challenge type currently supported by \fBlacme\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 lacme \fR[\fB\-\-agreement\-uri=\fIURI\fR]\fB \fBnew\-reg +\fR[\fICONTACT\fR ...] Register the account key managed by +\fIlacme\-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, \fBlacme\fR prints the URI of +the existing registration and aborts. + +.TP +.B lacme \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 lacme \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 lacme \fBrevoke\-cert \fIFILE\fR [\fIFILE\fR ...] + +Request that the given certificate(s) \fIFILE\fR(s) be revoked. For +this command, \fIlacme\-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 \fIlacme\-accountd\fR(1) UNIX\-domain socket to +connect to for signature requests from the ACME client. \fBlacme\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, \fBlacme\fR uses the first existing +configuration file among \fI./lacme.conf\fR, +\fI$XDG_CONFIG_HOME/lacme/lacme.conf\fR (or +\fI~/.config/lacme/lacme.conf\fR if the XDG_CONFIG_HOME environment +variable is not set), and \fI/etc/lacme/lacme.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.lacme\(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/lacme/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/lacme/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 \fBlacme\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 \fBlacme\fR uses the first existing +configuration file among \fI./lacme\-certs.conf\fR, +\fI$XDG_CONFIG_HOME/lacme/lacme\-certs.conf\fR (or +\fI~/.config/lacme/lacme\-certs.conf\fR if the XDG_CONFIG_HOME +environment variable is not set), and +\fI/etc/lacme/lacme\-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/lacme/lets\-encrypt\-x3\-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 lacme new-reg mailto:noreply@example.com + ~$ sudo lacme reg=/acme/reg/137760 --agreement-uri=https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf + ~$ sudo lacme new-cert + ~$ sudo lacme revoke-cert /path/to/server/certificate.pem +.fi + + +.SH SEE ALSO +\fBlacme\-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 . +\} |