Quick start

Table of Contents

• Documentation
• System requirements
• Installation
  • From github (for developers)
  • Upgrading
• Troubleshooting
• Compiling this package
  • Build locally
  • Docker build
  • Packages

Documentation

Read the full documentation on Read the docs.

System requirements

This application requires Python 3.3+ and an installed version of PIP for the Python version you are using. It is also convenient to have virtualenv installed so you can make a separate environment for stapled's dependencies.

Installation

Before installation make sure you have met the System requirements. You can install the ocsp daemon from the source code repository on our gitlab instance.

From github (for developers)

# Download the source from the repo
git clone --recursive https://github.com/greenhost/stapled.git
# OR, as a TIP, which downloads all the repos simultaneously in threads:
git clone --recursive -j5 https://github.com/greenhost/stapled.git
# Enter the source directory
cd stapled/
# Setup a virtualenv
virtualenv -p python3 env/
# Load the virtualenv
source env/bin/activate

Every time you want to run stapled you will need to run source env/bin/activate to load the virtualenv first. Then you run stapled as a module:

pythom -m stapled [arguments]

Alternatively you can start the daemon by running stapled without even activating the virtualenv if you install it like this:

Note that this means you have to keep track of the installed dependencies yourself!

Upgrading

If you had previously installed a version of stapled from github, to upgrade run the following:

# Deactivate the virtualenv if active
deactivate
# Delete the virtualenv (we will start clean)
rm -rf ./env
# Make a new virtualenv
virtualenv -p python3 env/
# Update to the latest version
git pull
# Clone submodules too
git submodule upgrade --init --recursive
# Install the current directory with pip. This allows you to edit the code
pip3 install -e . --upgrade

Troubleshooting

In order to get HAPRoxy to serve staples, any valid staple file should exist at the moment it is started. If a staple file does not exist for your certificate stapling will remain disabled until you restart HAProxy. Even if stapled tries to send HAProxy a valid staple through its socket.

In order to get around this bootstrapping problem, add an empty staple file, which is also valid according to HAProxy's documentation by running:

touch [path-to-certificate].pem.ocsp

For each of your domains.

We tested this for HAProxy 1.6, perhaps this behaviour will change in future versions.

Compiling this package

There are 2 ways to compile the package and various target distributions.

Build locally

Assuming you have the following packages installed on a debian based system:

• build-essential
• python3-cffi
• libffi-dev
• python3-all
• python3-dev
• python3-setuptools
• python3-pip
• rpm
• tar, gzip & bzip2
• git
• debhelper
• stdeb (pip3 install --user stdeb)

Or the equivalents of these on another distribution. You can build the packages by running one or more of the following make commands.

# Clear out the cruft from any previous build
make clean
# Source distribution
make sdist
# Binary distribution
make bdist
# RPM package (Fedora, Redhat, CentOS) - untested!
make rpm
# Debian source package (Debian, Ubuntu)
make deb-src
# Debian package (Debian, Ubuntu)
make deb
# All of the above
make all

Everything is tested under Debian Stretch (Python 3.5 and Debian Buster (Python 3.7), on other distros :abbr:`YMMV (Your Mileage May Vary)`.

Docker build

In order to be able to build a package reproducably by anyone, on any platform we have a Dockerfile that will install an instance of Debian Stretch in a docker container and can run the build process for you.

Assuming you have docker installed, you can simply run the below commands to build a package.

make docker-all

Remove any previous docker image and/or container named stapled then build the image with the same dependencies we used. Then compile the packages, then place them in the ./docker-dist dir.

make docker-nuke

Throw away any previous docker image and/or container named stapled. This is part of the make docker-all target.

make docker-build

Build the docker image. This is part of the make docker-all target.

make docker-compile

Assuming you have a built image, this compiles the packages for you and places them in docker-dist. This is part of the make docker-all target.

make docker-install

Assuming you have a built image and compiled the packages, this installs the packages in the docker container. This is part of the make docker-all target.

make docker-run

Assuming you have a built image and compiled the packages, and installed them in the docker container, this runs the installed binary to test if it works.

Packages

You can download packages here: https://github.com/greenhost/stapled/releases