diff options
Diffstat (limited to 'lacme.1')
| -rw-r--r-- | lacme.1 | 364 |
1 files changed, 0 insertions, 364 deletions
diff --git a/lacme.1 b/lacme.1 deleted file mode 100644 index bfe4f45..0000000 --- a/lacme.1 +++ /dev/null @@ -1,364 +0,0 @@ -.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 . -\} |