From 08d9f95505bb11c3d1b6a8c649362ede7dab4138 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 13 Jun 2016 23:14:00 +0200 Subject: =?UTF-8?q?Rename=20=E2=80=98letsencrypt-tiny=E2=80=99=20to=20?= =?UTF-8?q?=E2=80=98lacme=E2=80=99.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- letsencrypt.1 | 370 ---------------------------------------------------------- 1 file changed, 370 deletions(-) delete mode 100644 letsencrypt.1 (limited to 'letsencrypt.1') diff --git a/letsencrypt.1 b/letsencrypt.1 deleted file mode 100644 index 1c4b0db..0000000 --- a/letsencrypt.1 +++ /dev/null @@ -1,370 +0,0 @@ -.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\-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 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 . -\} -- cgit v1.2.3