From 6316bea09b6a43b23ba003eb56a49d5edd6ff77f Mon Sep 17 00:00:00 2001 From: xenolf Date: Tue, 15 Dec 2015 22:27:41 +0100 Subject: [PATCH] Improve documentation. Fixes #46, #47 --- README.md | 36 ++++++++++++++++++++++++++++++------ cli.go | 2 +- 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index a5a89b9e..efc9a72f 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,19 @@ Let's Encrypt client and ACME library written in Go [![GoDoc](https://godoc.org/github.com/xenolf/lego/acme?status.svg)](https://godoc.org/github.com/xenolf/lego/acme) [![Build Status](https://travis-ci.org/xenolf/lego.svg?branch=master)](https://travis-ci.org/xenolf/lego) -This is a work in progress. Please do *NOT* run this on a production server. +#### General +This is a work in progress. Please do *NOT* run this on a production server and please report any bugs you find! -Please report any bugs you find! +#### Installation +lego supports both binary installs and install from source. + +To get the binary just download the latest release for your OS/Arch from [the release page](https://github.com/xenolf/lego/releases) +and put the binary somewhere convenient. lego does not assume anything about the location you run it from. + +To install from source, just run +``` +go get -u github.com/xenolf/lego +``` #### Current Status The code in this repository is under development. @@ -30,10 +40,22 @@ Please keep in mind that CLI switches and APIs are still subject to change. When using the standard --path option, all certificates and account configurations are saved to a folder *.lego* in the current working directory. #### Sudo -I tried to not need sudo apart from challenges where binding to a privileged port is necessary. +The CLI does not require root permissions but needs to bind to port 80 and 443 for certain challenges. To run the CLI without sudo, you have two options: -- Use ```setcap 'cap_net_bind_service=+ep' /path/to/program``` -- Pass the --port option and specify a custom port to bind to. In this case you have to forward port 443 to this custom port. + +- Use setcap 'cap_net_bind_service=+ep' /path/to/program +- Pass the `--port` option and specify a custom port to bind to. In this case you have to forward port 443 to this custom port. + +#### Port Usage +By default lego assumes it is able to bind to ports 80 and 443 to solve challenges. +If this is not possible in your environment, you can use the `--port` option to instruct +lego to listen on that port for any incoming challenges. + +If you are using this option, make sure you proxy all of the following traffic to that port: +- All plaintext HTTP requests to port 80 which begin with a request path of `/.well-known/acme/` for the HTTP-01 challenge. +- All TLS handshakes on port 443 for TLS-SNI-01. + +This traffic redirection is only needed as long as lego solves challenges. As soon as you have received your certificates you can deactivate the forwarding. #### Usage @@ -68,6 +90,7 @@ GLOBAL OPTIONS: ##### CLI Example Assumes the `lego` binary has permission to bind to ports 80 and 443. You can get a pre-built binary from the [releases](https://github.com/xenolf/lego/releases) page. +If your environment does not allow you to bind to these ports, please read [Port Usage](#port-usage). Obtain a certificate: @@ -118,7 +141,8 @@ myUser := MyUser{ // A client facilitates communication with the CA server. This CA URL is // configured for a local dev instance of Boulder running in Docker in a VM. // We specify an optPort of 5001 because we aren't running as root and can't -// bind a listener to port 443 (used later when we attempt to pass challenge). +// bind a listener to port 80 or 443 (used later when we attempt to pass challenges). +// Keep in mind that we still need to proxy challenge traffic to port 5001. client, err := acme.NewClient("http://192.168.99.100:4000", &myUser, rsaKeySize, "5001") if err != nil { log.Fatal(err) diff --git a/cli.go b/cli.go index 7af67ccc..a0bffc73 100644 --- a/cli.go +++ b/cli.go @@ -83,7 +83,7 @@ func main() { }, cli.StringFlag{ Name: "port", - Usage: "Challenges will use this port to listen on. Please make sure to forward port 443 to this port on your machine. Otherwise use setcap on the binary", + Usage: "Challenges will use this port to listen on. Please make sure to forward port 80 and 443 to this port on your machine. Otherwise use setcap on the binary", }, }