Note: This project has been archived. I recommend using the official CertBot or Lego now (https://certbot.eff.org/ or https://github.com/xenolf/lego)
A suite of simple install scripts for the LetsEncrypt official certificate client on most major *nix OS (Debian, AWS, CentOS, RedHat, Ubuntu, and FreeBSD)
This is a minimal, repeatable set of scripts to stand up the official Let's Encrypt certificate management ACME client tool. Let's Encrypt is a really important project, and the team has made amazing progress in the past year.
The letsencrypt ("LE") client is written in Python, and though it attempts to automatically detect your operating system and build environment, it can be fragile and error-prone on some systems, particularly popular distros like Amazon Linux and older versions of CentOS or RedHat.
This started because of so many false starts for me when trying to use the beta client. I was eventually able to reliably request and receive certificates on Debian and CentOS on GCE and AWS, and achieve an A+ rating with SSLLabs' test suite. Woot! These scripts are a cleanup and drastic simplification of that work (many dozens of VMs later). My message is: you too can painlessly generate certs for your systems.
- For people who are not in the Beta program, the scripts by default will target the LE "staging" API endpoint, and on successful generation of certs, the CA will be a test authority ("Happy Hacker CA"). To enable trusted certificates, Beta testers can modify the scripts as indicated in each, but only against white-listed domains (and
example.comdoesn't whitelistblog.example.comby default). - Do not run either these scripts or the client on production systems (yet). LE is still in beta and has some rough edges, including silently invoking sudo and installing quite a few development packages. Please study the script for your platform. These were written quickly to help other people hopefully avoid some of the stumbling blocks I hit, and to expand the pool of testing volunteers.
- The Apache and Nginx plugins to autoupdate are very much still works-in-progress. I encourage anyone to help improve them by testing & documenting your results. Constructive feedback is welcome!
- Because the Nginx LE plugin in particular is still classified as highly experimental, I recommend spinning up a test VM (micro instances on GCE or AWS work great), and using the LE client as a certificate fetcher, pushing certs and keys to target servers via ssh.
- Be patient during the build, because there may be long pauses (multi-minute on micro VMs) that are preceded by unrelated warning messages. If you're running on a platform that ships with Python v 2.6 (wheezy, Cent6, Amazon Linux), be aware that there are some core limits on the underlying library around TLS, but workarounds are in place during the "bootstrap" process of standing up the client, and additional 2.6 support is being added by the LE team.
As indicated in each script, if you get stuck, it's perfectly ok to tear down, rebuild, and try again, just make sure to run the following clean up to remove python and build fragments:
cd ~/ && rm -rf ./letsencrypt && rm -rf ~/.local/share/letsencrypt && rm -rf /etc/letsencrypt && rm -rf ~/.cache/pip
There are three non-official alternative LE clients, and they work pretty well:
https://github.com/unixcharles/acme-client (a Ruby gem)
https://github.com/xenolf/lego (a single cross-platform Go program)
https://github.com/diafygi/letsencrypt-nosudo (as the name suggests, a non-sudo alternative—a single python script)
I tried each, and was able to generate certs quite easily with both Lego and LE-nosudo. Might be worth checking out.
https://community.letsencrypt.org/t/beta-program-announcements/
https://community.letsencrypt.org/t/nginx-configuration-sample/2173
Here is an inventory of files added to a stock Debian Jessie system by the LE client. As mentioned earlier, the official python client installs lots of packages in the background, so depending on your use case and tolerance for eventually adding a heavy tools footprint in production, it may be preferred to run the client as a certificate generator of sorts, and push certs and keys to a receiving web server or public API endpoint.
Alternatively, you may want to look at the Go-based lego client mentioned earlier. It will compile on virtually any platform into a single binary that you can run on other servers, and the installer dependencies are all self-contained packages.
# Generated from a before/after: grep install /var/log/dpkg.log
augeas-lenses
binutils
cpp
cpp-4.9
dh-python
dialog
gcc
gcc-4.9
git-core
libasan1
libatomic1
libaugeas0
libc-dev-bin
libc6-dev
libcilkrts5
libcloog-isl4
libexpat1-dev
libffi-dev
libgcc-4.9-dev
libgomp1
libisl10
libitm1
liblsan0
libmpc3
libmpdec2
libmpfr4
libpython-dev
libpython2.7
libpython2.7-dev
libpython3-stdlib
libpython3.4-minimal
libpython3.4-stdlib
libquadmath0
libssl-dev
libtsan0
libubsan0
linux-libc-dev
python-chardet-whl
python-colorama-whl
python-dev
python-distlib-whl
python-html5lib-whl
python-pip-whl
python-requests-whl
python-setuptools-whl
python-six-whl
python-urllib3-whl
python-virtualenv
python2.7-dev
python3
python3-minimal
python3-pkg-resources
python3-virtualenv
python3.4
python3.4-minimal
virtualenv
zlib1g-dev
You may get this warning if you're running on a platform with python 2.6 (Wheezy, Cent6, Amazon Linux):
InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning.
The bootstrap processes attempt to handle multiple libraries through python virtual environments, but on some OS', the only solution at the moment is to run a parallel library manager that (attempts) to not step over the core system dependencies for yum and apt.
For this suite of scripts I managed to avoid that in all cases but Debian Wheezy, which required pyenv, which offers a lot of benefits, but brings with it additional package and environment variable dependencies.
Big shout out to Kubilay Kocak (@koobs) and Bernard Spil (@Sp1l) on getting LetsEncrypt packaged on FreeBSD, and to Jacob Hoffman-Andrews (@j4cob) from @letsencrypt on his support and suggestions.
Ping me @kennwhite with questions. Have fun!