From 3ec54e7e0fb7a19abf4830efb21a4a9d5292a09a Mon Sep 17 00:00:00 2001 From: Daniel Molkentin Date: Fri, 22 Sep 2017 12:03:57 +0200 Subject: [PATCH] Add man page --- dehydrated.1 | 155 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 dehydrated.1 diff --git a/dehydrated.1 b/dehydrated.1 new file mode 100644 index 0000000..2a2f9e2 --- /dev/null +++ b/dehydrated.1 @@ -0,0 +1,155 @@ +.TH DEHYDRATED 1 2017-09-20 "Dehydrated ACME Client" +.SH NAME +dehydrated \- ACME client implemented as a shell-script +.SH SYNOPSIS +.B dehydrated +[\fBcommand\fR [\fBargument\fR]] +[\fBargument\fR [\fBargument\fR]] +.IR ... +.SH DESCRIPTION +A client for ACME-based Certificate Authorities, such as LetsEncrypt. It +allows to request and obtain TLS certificates from an ACME-based +certificate authority. + +Before any certificates can be requested, Dehydrated needs +to acquire an account with the Certificate Authorities. Optionally, an email +address can be provided. It will be used to e.g. notify about expiring +certificates. You will usually need to accept the Terms of Service of the CA. +Dehydrated will notify if no account is configured. Run with \fB--register +--accept-terms\fR to create a new account. + +Next, all domain names must be provided in domains.txt. The format is line +based: If the file contains two lines "example.com" and "example.net", +Dehydrated will request two certificate, one for "example.com" and the other +for "example.net". A single line while "example.com example.net" will request a +single certificate valid for both "example.net" and "example.com" through the \fISubject +Alternative Name\fR (SAN) field. + +For the next step, one way of verifying domain name ownership needs to be +configured. Dehydrated implements \fIhttp-01\fR and \fIdns-01\fR verification. + +The \fIhttp-01\fR verification provides proof of ownership by providing a +challenge token. In order to do that, the directory referenced in the +\fIWELLKNOWN\fR config variable needs to be exposed at +\fIhttp://{domain}/.well-known/acme-challenge/\fR, where {domain} is every +domain name specified in \fIdomains.txt\fR. Dehydrated does not provide its +own challenge responder, but relies on an existing web server to provide the +challenge response. See \fIwellknown.md\fR for configuration examples of +popular web servers. + +The \fIdns-01\fR verification works by providing a challenge token through DNS. +This is especially interesting for hosts that cannot be exposed to the public +Internet. Because adding records to DNS zones is oftentimes highly specific to +the software or the DNS provider at hand, there are many third party hooks +available for dehydrated. See \fIdns-verification.md\fR for hooks for popular +DNS servers and DNS hosters. + +Finally, the certificates need to be requested and updated on a regular basis. +This can happen through a cron job or a timer. Initially, you may enforce this +by invoking \fIdehydrated -c\fR manually. + +After a successful run, certificates are stored in +\fI/etc/dehydrated/certs/{domain}\fR, where {domain} is the domain name in the +first column of \fIdomains.txt\fR. + +.SH OPTIONS + +.BR Commands +.TP +.BR \-\-version ", " \-v +Print version information +.TP +.BR \-\-register +Register account key +.TP +.BR \-\-account +Update account contact information +.TP +.BR \-\-cron ", " \-c +Sign/renew non\-existent/changed/expiring certificates. +.TP +.BR \-\-signcsr ", " \-s " " \fIpath/to/csr.pem\fR +Sign a given CSR, output CRT on stdout (advanced usage) +.TP +.BR \-\-revoke ", " \-r " " \fIpath/to/cert.pem\fR +Revoke specified certificate +.TP +.BR \-\-cleanup ", " \-gc +Move unused certificate files to archive directory +.TP +.BR \-\-help ", " \-h +Show help text +.TP +.BR \-\-env ", " \-e +Output configuration variables for use in other scripts + +.PP +.BR Parameters +.TP +.BR \-\-accept\-terms +Accept CAs terms of service +.TP +.BR \-\-full\-chain ", " \-fc +Print full chain when using \fB\-\-signcsr\fR +.TP +.BR \-\-ipv4 ", " \-4 +Resolve names to IPv4 addresses only +.TP +.BR \-\-ipv6 ", " \-6 +Resolve names to IPv6 addresses only +.TP +.BR \-\-domain ", " \-d " " \fIdomain.tld\fR +Use specified domain name(s) instead of domains.txt entry (one certificate!) +.TP +.BR \-\-keep\-going ", " \-g +Keep going after encountering an error while creating/renewing multiple +certificates in cron mode +.TP +.BR \-\-force ", " \-x +Force renew of certificate even if it is longer valid than value in RENEW_DAYS +.TP +.BR \-\-no\-lock ", " \-n +Don't use lockfile (potentially dangerous!) +.TP +.BR \-\-lock\-suffix " " \fIexample.com\fR +Suffix lockfile name with a string (useful for use with \-d) +.TP +.BR \-\-ocsp +Sets option in CSR indicating OCSP stapling to be mandatory +.TP +.BR \-\-privkey ", " \-p " " \fIpath/to/key.pem\fR +Use specified private key instead of account key (useful for revocation) +.TP +.BR \-\-config ", " \-f " " \fIpath/to/config\fR +Use specified config file +.TP +.BR \-\-hook ", " \-k " " \fIpath/to/hook.sh\fR +Use specified script for hooks +.TP +.BR \-\-out ", " \-o " " \fIcerts/directory\fR +Output certificates into the specified directory +.TP +.BR \-\-challenge ", " \-t " " \fI[http\-01|dns\-01]\fR +Which challenge should be used? Currently http\-01 and dns\-01 are supported +.TP +.BR \-\-algo ", " \-a " " \fI[rsa|prime256v1|secp384r1]\fR +Which public key algorithm should be used? Supported: rsa, prime256v1 and +secp384r1 +.SH DIAGNOSTICS +The program exits 0 if everything was fine, 1 if an error occurred. +.SH BUGS +Please report any bugs that you may encounter at the project web site +.UR https://github.com/lukas2511/dehydrated/issues +.UE . +.SH AUTHOR +Dehydrated was written by Lukas Schauer. This man page was contributed by +Daniel Molkentin. +.SH COPYRIGHT +Copyright 20015-2017 by Lukas Schauer and the respective contributors. +Provided under the MIT License. See the LICENSE file that accompanies the +distribution for licensing information. +.SH SEE ALSO +Full documentation along with configuration examples are provided in the \fIdocs\fR +directory of the distribution, or at +.UR https://github.com/lukas2511/dehydrated/tree/master/docs +.UE .