nginx_le_cli 0.1.0

Command line tools for Nginx-LE

Nginx-LE

Nginx-LE provides a docker container and tools to create an Nginx web server with Lets Encrypt built in.

Nginx-LE supports both public facing web servers and private (internal) web servers such as those used by individual developers.

The key advantages of Nginx-LE are:

• automatical certificate acquisition and renewal
• no down time when renewing certificates
• for Public facing servers, works with any DNS server

The key disadvantage

• for Private servers we only support NameCheap.
• currently support a max of 10 Private servers

Automatic renewal

Both Public facing and internal Private Web Servers can have their certificates automatically renewed.

No down time.

Nginx-LE is able to renew certificate WITHOUT taking your web server offline.

Once Nginx-LE has acquired a certificate it will move it into the Nginx certificate directory and perform an Nginx reload command which is close to instantaneous.

Public Web Server

Public Web Servers is where the Web Server exposes port 80 on a public IP address.

For Public Web Servers Nginx-LE uses the standard Certbot HTTP auth mechanism.

Lets Encrypt certificates are automatically renewed.

A public web server may be behind a NAT however it MUST have port 80 open to the world to allow certbot to validate the server.

Private Web Server

For a private web server (one with no public internet access) a simple script is provided to renew certificates using the certbot DNS auth method.

Note: At this point the private mode only works with a NameCheap dns server as that is the only api we currently support.

Nginx-LE cli tooling

Nginx-LE provides cli tooling to manage your Nginx-LE instance.

The cli tooling is based on dart and the DShell library.

To install the cli tooling follow this (install guide)[https://github.com/bsutton/dshell/wiki/Installing-DShell]

On linux this amounts to:

sudo apt-get update
sudo apt-get install --no-install-recommends -y wget ca-certificates gnupg2
wget https://raw.githubusercontent.com/bsutton/dshell/master/bin/linux/dshell_install
chmod +x dshell_install
export PATH="$PATH":"$HOME/.pub-cache/bin":"$HOME/.dshell/bin"
./dshell_install

The DShell installer also installs dart (if its not already installed).

Once DShell is installed, install the Nginx-LE cli tools via:

pub global activate nginx-le

cli commands

The Nginx-LE cli exposes the following commands:

Command	Description
build	Builds the docker image
start	Starts nginx-le
restart	Restarts nginx-le
stop	Stops nginx-le
acquire	Acquires or renews a Lets Encrypt certificate
revoke	Revokes the current Lets Encrypt certificate
cli	Attaches you to the Docker container in a bash shell.

Building Nginx-LE

To build Nginx-LE install the Nginx-LE cli tools as noted above.

You can use the Nginx-LE image in a numbe of ways.

Method	Usage
Serve static content	Mount a volume with your static content into /etc/nginx/wwwroot
Configure your own Location(s)	Add nginx compatible Location files under /etc/nginx/locations
Configure as Proxy	Add nginx compatible Location files under /etc/nginx/locations and Upstream files under /etc/nginx/upstream
Extend the Image	Create your own Dockerfile based on Nginx-LE.

Before you build your container you need to create your Dockerfile. See the section below on Create a Dockerfile

To build the Nginx-LE image run:

nginx-le build --tag=<repo/image:version>

Switches

image

The requried --image switch sets the docker image/tag name (repo/image:version) for the image.

e.g. --image=examplerepo/examplenginx:1.0.0

The switch can be abbreviated to -i.

update-dshell

The optonal flag --update-dshell causes the build to pull the latest version of dart/dshell rather than using the docker cache instance.

You only need to add this switch if you have an existing build and you need to update the dshell/dart version.

debug

The optional flag --debug outputs additional build information.

The flag can be abbreviated to -d.

Starting Nginx-LE

To start the Nginx-LE container run:

nginx-le start --fqdn=example.com --tld=com --mode=public --emailaddress=[e-mail] --name=mycontainer

When you first start your Nginx-LE container it won't have a certificate.

When Nginx-LE detects that it doesn't have a vaid certificate it will enter certificate acquistion mode.

In this mode it will display a default 'Certificate Acquistion Required' home page with instructions on obtaining a certificate.

public mode

If you are running a --mode=public build, the container will automatically acquire a certificate and then switch into standard operating mode (e.g. it will start serving your website).

private mode

if you are running a --mode=private build, the container is unable to automatically acquire a certificate.

When running in private mode you also need to run the acquire command described below.

Switches

fqnd

The required --fqdn switch specifies the fully qualified domain name (FQDN) of the host that the certificate will be issued for.

The FQDN must much a valid DNS entry on a public facing DNS server.

tld

The required --tld switch specifies top level domain name (TLD) of the host e.g. use com.au if your fqdn is example.com.au.

mode

The required --mode switch tells Nginx-LE whether your web server is access from the internet and therefore controls how certificate renewal is performed.

There are two values supported by --mode

private - the server is not access from the internet and cerbot will use DNS validation.

public - the server is accessible from the internet and certbot will use HTTPS validation.

e.g. --mode=public

The switch can be abbreviated to -m.

image

The required --image switch specifics which docker image to use. This should be the same name you passed to the --image switch when you ran the build.

emailaddress

The required --emailaddress switch is used to send email notifications when errors occur.

e.g. --emailaddress=[e-mail]

The switch can be abbreviated to -e.

name

The optional --name switch allows you to name your container which will allow you to start it by name.

e.g. --name=examplengix

The switch can be abbreviated to -n.

Acquiring/Renewing certificates

Public Mode

For Nginx-LE containers that were built with the --mode=public switch certificate aquisition and renewal is automatic.

Simply start your Nginx-LE container and it will acquire a certificate and renew it as required.

Unlike private mode Nginx-LE public mode works with ANY dns provider.

Nginx-LE will check if a renew is required every 13 hours. Certbot will renew a certificate if its within 30 days of expiring.

Private Mode

Note: Nginx-LE currently only supports the NameCheap DNS api for acquiring certificates in private mode.

WARNING: We would not recommend NameCheap for production DNS servers as their api requires us to replace EVERY DNS entry to create a single DSN entry. A failure of Nginx-LE could result in your DNS becoming corrupted. Additionally this method only supports DNS servers with no more than 10 Host entries. This is a limit of Nginx-LE as we haven't worked out how to use the NameCheap POST option for updating the DNS entries (as it doesn't appear to be documented).

As such we only recommend private mode for developer machines using a non-production domain.

Just acquire a cheap random domain name for use by your development team and host it with NameCheap

Acquire a certificate

When running in private mode you must run the acquire command to acquire a certificate.

To acquire a certificate using a NameCheap DNS server using the acquire command:

e.g.

nginx-le acquire --containerid=XXXXX namecheap --ask

Note: The acquire command can take 5 minutes+ to acquire a certificate due to delays in DNS propergation.

The NameCheap Api requires an apiKey and apiUsername. This need to be held securely and as such can't be saved to disk.

containerid switch

The docker containerid to attach to.

Either this switch or the --name switch must be passed.

e.g. --containerid=XXXXX

staging switch

Lets Encrypt puts fairly tight constraints on the number of times you can request a certificate for a given domain (5 per day).

During testing we recommend that you use there staging certificates as the limts are much higher

The optional --staging flag allows you to select the Lets Encrypt staging server.

ask switch

The --ask will prompt you to enter the apikey and the apiusername.

env switch

The --env switch requires you to place the apikey and apiusername into to environment variables:

export NAMECHEAP_API_KEY=xxxxxx
export NAMECHEAP_API_USERNAME=yyyy

Note: the namecheap api username is the same username you use to log in to the NameCheap admin console.

Nginx-LE will then acquire the certificate and then transition into standard operating mode (e.g. it will start serving your website).

Once you have run the acquire command Nginx-LE will be able to automatically renew certificates until you shutdown the server.

Automating certificate renewal in Private Mode

You can run the acquire command after running the start command even if Nginx-LE already has a certificate.

If you run the acquire command after ever start then Nginx-LE server can automaically renew certificates as required.

This command sequence starts the container and passes it the NameCheap credentials to allow it to renew as required.

export NAMECHEAP_API_KEY=xxxxxx
export NAMECHEAP_API_USERNAME=yyyy
nginx-le start --fqdn=example.com --tld=com --name=mycontainer
nginx-le acquire namecheap --env

During development you should probaly just use the start command as you don't want to be storing you creditials in a script.

On a daily bases use the start command and only use the acquire namecheap --ask option every few months when a renewal is required.

Create a dockerfile

By default the Nginx-LE ships with the following configuration files:

The base nginx configuration is defined by:

• /etc/nginx/nginx.conf
• /etc/nginx/custom/defaults.conf

If you are happy with the standard configuration you can simply add location files under /etc/nginx/locations.

Otherwise you can replace the /etc/nginx/custom/default.conf with your own customised defaults.

NOTE: if you replace default.conf you MUST include a ./well-known location for lets encrypt to work:

  # lets encrypt renewal path
    location ^~ /.well-known {
      allow all;
      root  /opt/letsencrypt/wwwroot;
    }

The nginx-le container REQUIRES that you have a default.conf file in:

• /etc/nginx/custom/default.conf

You can also modify the nginx.conf if you have specialised requirements.

If you modify nginx.conf there are several options that MUST not change.

• daemon off;
• user nginx;
• include /etc/nginx/live/default.conf

Changing any of the above settings will cause nginx-le to fail.

Whats with this 'live' directory

The nginx.conf loads its configuration from the /etc/nginx/live/defaults.conf file.

However the above instructions dictate that you put your default.conf in /etc/nginx/custom/defaults.conf

Note: the difference custom vs live.

On startup the live directory is symlinked to your /etc/nginx/custom directory.

This allows nginx-le to change the live folder to point to the acquire path when in certificate acquistion mode.

When nginx starts and your configuration requires https but you don't have any certificates then nginx will fail.

To get around this problem nginx-le on startup checks if you have active certificates. If you don't it placess the container into acquire mode.

nginx-le does this by changing the live symlink to point to the /etc/nginx/acquire directory.

The acquire path contains a single index.html page informing you that a certificate needs to be acquired. In this mode no other content will be served and only requests from certbot will be processed.

This allows nginx to start and then nginx-le can acquire the necessary certifiacates (or if in private mode you can via the acquire command).

Once a valid certificate has been acquired nginx-le switches the live symlink back to /etc/nginx/custom and does a nginx reload and your site is back online.