manpage

1 files changed, 189 insertions, 0 deletions

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 .