156 lines
5.5 KiB
Groff
156 lines
5.5 KiB
Groff
|
.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 .
|