From 9b4e37696a8ae05650a2aec57ba294fc4785ae0d Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 18 Dec 2015 01:42:27 +0100 Subject: manpage --- letsencrypt.1 | 189 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 letsencrypt.1 diff --git a/letsencrypt.1 b/letsencrypt.1 new file mode 100644 index 0000000..a16e165 --- /dev/null +++ b/letsencrypt.1 @@ -0,0 +1,189 @@ +.TH LETSENCRYPT "1" "DECEMBER 2015" "Tiny Let's Encrypt ACME client" "User Commands" + +.SH NAME +letsencrypt \- Tiny Let's Encrypt ACME client + +.SH SYNOPSIS +.B letsencrypt\fR [\fIOPTION\fR ...] \fICOMMAND\fR \fIACCOUNTKEY\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 three components: + +.nr step 1 1 +.IP \n[step]. 8 +The \(lqmaster\(rq process, which runs as root and is the only component +with access to the private key material (both account and server keys). +It is only used to fork the other components (after dropping +privileges), and to sign ACME requests (JSON Web Signatures); for +certificate issuance (\fBnew-cert\fR command), it is also used to +generate the Certificate Signing Request, then to verify the validity of +the issued certificate, and optionally to reload or restart services +using \fB--notify\fR. + +.IP \n[step]. 8 +The actual ACME client, which runs as the user specified with +\fB--runas\fR (or root if the option is omitted). It builds ACME +requests and dialogues with the remote ACME server. All requests need +to be signed with the account key, but this process doesn't need direct +access to any private key material: instead, it write the data to be +signed to a pipe shared with the master process, which in turns replies +with its SHA-256 signature. + +.IP \n+[step]. +An optional webserver, which is spawned by the master process (when +nothing is listening on localhost:80); \fBsocat\fR(1) is used to listen +on port 80 and to change the user (owner) and group of the process to +\(lqwww-data:www-data\(rq. +(The only challenge type currently supported by \fBletsencrypt\fR is +\(lqhttp-01\(rq, hence a webserver is required.) +Some iptables rules are automatically added to open port 80, and +removed afterwards. +The web server only processes GET requests under the +\(lq/.well-known/acme-challenge\(rq URI. +If a webserver is already listening on port 80, it needs to be +configured to serve these URIs (for each virtual-hosts requiring +authorization) as static files under the \(lq/var/www/acme-challenge\(rq +root directory, which must not exist. + +.SH GENERIC OPTIONS +.TP +.B \-\-runas=\fIusername\fR +Username to run the ACME client as. This user does not need access to +any private key material. The ACME client runs as root when this option +is omited (not recommended). + +.TP +.B \-?\fR, \fB\-\-help\fR +Display a brief help and exit. + +.TP +.B \-q\fR, \fB\-\-quiet\fR +Try to be quiet. + +.TP +.B \-\-debug +Turn on debug mode. + + +.SH ACCOUNT KEY REGISTRATION +.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-reg\fR \fIACCOUNTKEY\fR [\fIEMAIL\fR ...] + +Registers the given \fIACCOUNTKEY\fR. An optional list of \fIEMAIL\fR +addresses can be given as contact information. + +.TP +.B \-\-genkey\fR[\fB=\fIALGO\fR[:\fIBITS\fR]] +Automatically generate the \fIACCOUNTKEY\fR (with mode 0600) if it does +not exist, using a \fIBITS\fR\-long \fIALGO\fR key. +The \fBopenssl\fR(1) default length is used when \fIBITS\fR is omited. +The default \fIALGO\fRrithm is \(lqRSA\(rq, which is also the only one +currently supported. + + +.SH CERTIFICATE ISSUANCE +.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-cert\fR \fIACCOUNTKEY\fR +\fB\-\-output=\fICERT\fR \fB\-\-csr=\fIFILE\fR + +.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-cert\fR \fIACCOUNTKEY\fR +\fB\-\-output=\fICERT\fR \fB\-\-key=\fIFILE\fR [\fB\-\-hash=\fIALGO\fR] +[\fB\-\-subject=\fISTRING\fR] [\fB\-\-san=\fISTRING\fR] +[\fB\-\-keyusage=\fISTRING\fR] + +Request a new Certificate Issuance using the given \fIACCOUNTKEY\fR. +The Certificate Signing Request can be supplied directly using +\fB\-\-csr\fR, or generated from the server key (\fB\-\-key\fR) using +options \fB\-\-hash\fR, \fB\-\-subject\fR, \fB\-\-san\fR and \fB\-\-keyusage\fR. + +The issued X.509 certificate is then validated, and upon success is +placed (in PEM format) into the file specified with \fB\-\-output\fR; the +optional \fB\-\-chain\fR option can be used to append the issuer +certificate as well. + +.TP +.B \-\-min-age=\fISECONDS +Skip the issuance if the certificate specified by \fB\-\-output\fR exists +and its expiration date is more than \fISECONDS\fR ahead. + +.TP +.B \-\-csr=\fIFILE +Certificate Signing Request to send (alternatively, use \fB\-\-key\fR to +generate it from the private server key). + +.TP +.B \-\-key=\fIFILE +Server private key used to generate the Certificate Signing Request when +\fB\-\-csr\fR is omitted. (Use \fB\-\-genkey\fR to generate it +automatically.) + +.TP +.B \-\-genkey\fR[\fB=\fIALGO\fR[:\fIBITS\fR]] +Automatically generate the server private key (with mode 0600) if it +does not exist, using a \fIBITS\fR\-long \fIALGO\fR key. +The \fBopenssl\fR(1) default length is used when \fIBITS\fR is omited. +The default \fIALGO\fRrithm is \(lqRSA\(rq, which is also the only one +currently supported. + +.TP +.B \-\-hash=\fIDGST +Message digest to sign the Certificate Signing Request with. + +.TP +.B \-\-subject=\fR/\fItype0\fR=\fIvalue0\fR/\fItype1\fR=\fIvalue1\fR/\fItype2\fR=... +Subject name to use in the Certificate Signing Request. + +.TP +.B \-\-san=\fItype0\fR:\fIvalue1\fR,\fItype1\fR:\fIvalue1\fR,\fItype2\fR:... +Comma-separated list of Subject Alternative Names. The only \fItype\fR +currently supported is \(lqDNS\(rq, to specify an alternative domain +name. + +.TP +.B \-\-keyusage=\fISTRING +Comma-separated list of Key Usages, see x509v3_config(5ssl). +(Default: \(lqdigitalSignature,keyEncipherment,keyCertSign\(rq.) + +.TP +.B \-\-output=\fIFILE +Where to copy the issued (signed) X.509 certificate. + +.TP +.B \-\-chain=\fR[\fIFILE\fR] +Store the server certificate along with its intermediate CA in +\fIFILE\fR. If \fIFILE\fR is empty or omitted, use the file specified +with \fB\-\-output\fR instead. + +.TP +.B \-\-notify=\fICOMMAND\fR +Command to run upon success. (This option can be repeated to run +multiple commands.) + + +.SH CERTIFICATE REVOKATION +.B letsencrypt\fR [\fIOPTION\fR ...] \fBrevoke\-cert\fR {\fIACCOUNTKEY\fR|\fISVRKEY\fR} \fIFILE\fR [\fIFILE\fR ...] + +Request that the given certificate(s) \fIFILE\fR(s) be revoked. The +first argument after the command name can be either the account key file +or the private part of the certificate(s) to revoke. + + +.SH EXAMPLES + +.TP +letsencrypt \-\-runas=letsencrypt new\-reg \-\-genkey=RSA:4096 /etc/ssl/letsencrypt.key admin@fripost.org +Register a new account key \(lq/etc/ssl/letsencrypt.key\(rq using +\(lqadmin@fripost.org\(rq as contact information. A 4096-bits long RSA +key is generated (with mode 0600) if the key file does not exists. + +.TP +letsencrypt \-\-runas=letsencrypt new\-cert /etc/ssl/letsencrypt.key \-\-output=/etc/nginx/ssl/www.fripost.org.pem \-\-chain \-\-key=/etc/nginx/ssl/www.fripost.org.key \-\-hash=SHA512 \-\-subject=/O=Fripost/CN=fripost.org \-\-san=DNS:fripost.org,DNS:www.fripost.org,DNS:wiki.fripost.org \-\-min-age=432000 \-\-notify='systemctl restart nginx' +Request issuance of a new (chained) certificate, but only if it doesn't exist or expires in less than 5 days; restart nginx upon success. + + +.SH AUTHOR +Written by Guilhem Moulin +.MT guilhem@fripost.org +.ME . -- cgit v1.2.3