README.md 2.25 KB
Newer Older
Stephan Uhlmann's avatar
Stephan Uhlmann committed
1
2
bacme
=====
Stephan Uhlmann's avatar
Stephan Uhlmann committed
3
4
5
6
7
8
9
10

Documentation
-------------

This is a "keep it simple" shell script for requesting a certificate from the
Let's Encrypt CA using the ACME protocol.

Simplifications for example are:
Stephan Uhlmann's avatar
Stephan Uhlmann committed
11

12
- supports ACMEv2 (RFC 8555) only, not the deprecated ACMEv1
Stephan Uhlmann's avatar
Stephan Uhlmann committed
13
- supports http validation only
14
15
16
17
18
19
- keys are not reused but regenerated every time
  - both the account key and the domain key
  - in part this is also because of privacy considerations

The script is intentionally made so by default it will not do anything on your
server by itself. There is no need that you have to run it directly on your
20
server (as root or otherwise). You keep control over the validation and
21
22
23
24
25
installation process.
A typical automated renewal process would be to let the script generate new
private keys, automate the http validation by using a SSH key authenticated
rsync with the --webroot option and installing the generated keys and
certificates via e.g. an Ansible playbook.
Stephan Uhlmann's avatar
Stephan Uhlmann committed
26
27

The script is intended to be easy to understand but still allow the complete
28
automatic generation of a certificate.
29
It is also a working small example to learn the ACME protocol.
Stephan Uhlmann's avatar
Stephan Uhlmann committed
30

Stephan Uhlmann's avatar
Stephan Uhlmann committed
31

Stephan Uhlmann's avatar
Stephan Uhlmann committed
32
33
34
35
36
37
Let's Encrypt Subscriber Agreement
----------------------------------

By using this script you accept the Let's Encrypt Subscriber Agreement.
The latest version can be found at https://letsencrypt.org/repository/

Stephan Uhlmann's avatar
Stephan Uhlmann committed
38

39
40
41
42
Usage
-----

```
Stephan Uhlmann's avatar
Stephan Uhlmann committed
43
Usage: bacme [options...] <domain> [ <domain> ... ]
44
45
46
47
48
49
50
51
52
53
Options:
  -e, --email EMAIL         Your email if you want that Let's Encrypt can contact you
  -h, --help                This help
  -t, --test                Use staging API of Let's Encrypt for testing the script
  -v, --verbose             Verbose mode, print additional debug output
  -w, --webroot DIRECTORY   Path to the DocumentRoot of your webserver. Can be a rsync
                            compatible remote location like www@myserver:/srv/www/htdocs/.

The first domain parameter should be your main domain name with the subdomains following after it.

Stephan Uhlmann's avatar
Stephan Uhlmann committed
54
Example: ./bacme -e me@example.com -w www@server:/var/www/example/ example.com www.example.com
55
56
57
58
59
60

```

See EXAMPLES.md for sample executions and their output.


Stephan Uhlmann's avatar
Stephan Uhlmann committed
61
62
Useful links
------------
Stephan Uhlmann's avatar
Stephan Uhlmann committed
63

64
- ACME protocol: https://tools.ietf.org/html/rfc8555
65
- Other ACME clients: https://letsencrypt.org/docs/client-options/
Stephan Uhlmann's avatar
Stephan Uhlmann committed
66