.. image:: https://code.greenhost.net/open/stapled/badges/master/pipeline.svg :target: https://code.greenhost.net/open/stapled/commits/master :alt: Pipeline Status

.. image:: https://code.greenhost.net/open/stapled/raw/master/stapled_128.png :target: https://stapled.readthedocs.io/en/latest/ :alt: Stapled logo :align: left

=========== Quick start

.. contents:: Table of Contents :local:

Documentation

Read the full documentation on Read the docs <https://stapled.readthedocs.org/>_.

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)

.. code-block:: bash

# 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:

.. code-block:: bash

pythom -m stapled [arguments]

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

.. code-block:: bash # Install dependencies.. pip3 install asn1crypto ocspbuilder oscrypto certvalidator # Install the current directory with pip. This install the project dir as # a console script allowing you to run stapled, pip3 install -e .

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:

.. code-block:: bash

# 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:

.. code-block:: bash

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.

.. code-block:: bash

# 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.

.. code-block:: bash

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.

.. code-block:: bash

make docker-nuke

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

.. code-block:: bash

make docker-build

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

.. code-block:: bash

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.

.. code-block:: bash

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.

.. code-block:: bash

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