docs/wellknown.md

   1 # WELLKNOWN
   2
   3 With `http-01`-type verification (default in this script, there is also support for [dns based verification](dns-verification.md)) Let's Encrypt (or the ACME-protocol in general) is checking if you are in control of a domain by accessing a verification file on an URL similar to `http://example.org/.well-known/acme-challenge/m4g1C-t0k3n`.
   4 It will do that for any (sub-)domain you want to sign a certificate for.
   5
   6 At the moment you'll need to have that location available over normal HTTP on port 80 (redirect to HTTPS will work, but starting point is always HTTP!).
   7
   8 dehydrated has a config variable called `WELLKNOWN`, which corresponds to the directory which should be served under `/.well-known/acme-challenge` on your domain. So in the above example the token would have been saved as `$WELLKNOWN/m4g1C-t0k3n`.
   9
  10 If you only have one docroot on your server you could easily do something like `WELLKNOWN=/var/www/.well-known/acme-challenge`, for anything else look at the example below.
  11
  12 ## Example Usage
  13
  14 If you have more than one docroot (or you are using your server as a reverse proxy / load balancer) the simple configuration mentioned above wouldn't work, but with just a few lines of webserver configuration this can be solved.
  15
  16 An example would be to create a directory `/var/www/dehydrated` and set `WELLKNOWN=/var/www/dehydrated` in the scripts config.
  17
  18 You'll need to configure aliases on your Webserver:
  19
  20 ### Nginx example config
  21
  22 With Nginx you'll need to add this to any of your `server`/VHost config blocks:
  23
  24 ```nginx
  25 server {
  26   [...]
  27   location /.well-known/acme-challenge {
  28     alias /var/www/dehydrated;
  29   }
  30   [...]
  31 }
  32 ```
  33
  34 ### Apache example config
  35
  36 With Apache just add this to your config and it should work in any VHost:
  37
  38 ```apache
  39 Alias /.well-known/acme-challenge /var/www/dehydrated
  40
  41 <Directory /var/www/dehydrated>
  42         Options None
  43         AllowOverride None
  44
  45         # Apache 2.x
  46         <IfModule !mod_authz_core.c>
  47                 Order allow,deny
  48                 Allow from all
  49         </IfModule>
  50
  51         # Apache 2.4
  52         <IfModule mod_authz_core.c>
  53                 Require all granted
  54         </IfModule>
  55 </Directory>
  56 ```
  57
  58 ### Lighttpd example config
  59
  60 With Lighttpd just add this to your config and it should work in any VHost:
  61
  62 ```lighttpd
  63 server.modules += ("alias")
  64 alias.url += (
  65  "/.well-known/acme-challenge/" => "/var/www/dehydrated/",
  66 )
  67 ```