README.rst 5.91 KB
Newer Older
Chris Snijder's avatar
Chris Snijder committed
1
2
.. image:: https://code.greenhost.net/open/stapled/badges/master/pipeline.svg
    :target: https://code.greenhost.net/open/stapled/commits/master
Chris Snijder's avatar
Chris Snijder committed
3
    :alt: Pipeline Status
Chris Snijder's avatar
Chris Snijder committed
4

Chris Snijder's avatar
Chris Snijder committed
5
6
7
8
9
.. image:: https://code.greenhost.net/open/stapled/raw/master/stapled_128.png
    :target: https://stapled.readthedocs.io/en/latest/
    :alt: Stapled logo
    :align: left

10
11
12
13
14
15
16
17
18
19
20
21
===========
Quick start
===========

.. contents:: Table of Contents
   :local:


Documentation
=============

Read the full documentation on
22
`Read the docs <https://stapled.readthedocs.org/>`_.
23
24
25
26
27


System requirements
===================

28
This application requires **Python 3.3+** and an installed
29
30
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
31
stapled's dependencies.
32
33
34
35

Installation
============

Chris Snijder's avatar
Chris Snijder committed
36
Before installation make sure you have met the `System requirements`_.
37
38
39
You can install the ocsp daemon from the source code repository on our gitlab
instance.

40
From github (for developers)
41
42
43
44
45
----------------------------

.. code-block:: bash

    # Download the source from the repo
46
    git clone --recursive https://github.com/greenhost/stapled.git
Chris Snijder's avatar
Chris Snijder committed
47
    # OR, as a TIP, which downloads all the repos simultaneously in threads:
48
    git clone --recursive -j5 https://github.com/greenhost/stapled.git
49
    # Enter the source directory
50
    cd stapled/
51
52
53
54
55
    # Setup a virtualenv
    virtualenv -p python3 env/
    # Load the virtualenv
    source env/bin/activate

56
Every time you want to run ``stapled`` you will need to run
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
``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!
76

77
78
79
Upgrading
---------

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

Chris Snijder's avatar
Chris Snijder committed
83
.. code-block:: bash
84
85
86
87
88
89
90
91
92

    # 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
Chris Snijder's avatar
Chris Snijder committed
93
    # Clone submodules too
94
    git submodule upgrade --init --recursive
95
    # Install the current directory with pip. This allows you to edit the code
96
    pip3 install -e . --upgrade
97

Chris Snijder's avatar
Chris Snijder committed
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
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.

Chris Snijder's avatar
Chris Snijder committed
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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
Chris Snijder's avatar
Chris Snijder committed
134
- python3-pip
Chris Snijder's avatar
Chris Snijder committed
135
136
137
138
- rpm
- tar, gzip & bzip2
- git
- debhelper
139
- stdeb (``pip3 install --user stdeb``)
Chris Snijder's avatar
Chris Snijder committed
140
141
142
143

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

144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
.. 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
Chris Snijder's avatar
Chris Snijder committed
160

161
162
Everything is tested under Debian Stretch (Python 3.5 and Debian Buster
(Python 3.7), on other distros :abbr:`YMMV (Your Mileage May Vary)`.
Chris Snijder's avatar
Chris Snijder committed
163
164
165
166
167
168
169
170
171
172
173

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.

174
175
176
177
.. code-block:: bash

    make docker-all

178
Remove any previous docker image and/or container named `stapled` then build the
Chris Snijder's avatar
Chris Snijder committed
179
180
181
image with the same dependencies we used. Then compile the packages, then
place them in the `./docker-dist` dir.

182
183
184
185
.. code-block:: bash

    make docker-nuke

186
Throw away any previous docker image and/or container named `stapled`.
Chris Snijder's avatar
Chris Snijder committed
187
188
This is part of the `make docker-all` target.

189
.. code-block:: bash
Chris Snijder's avatar
Chris Snijder committed
190

191
192
    make docker-build

Chris Snijder's avatar
Chris Snijder committed
193
194
Build the docker image. This is part of the `make docker-all` target.

195
196
197
198
.. code-block:: bash

    make docker-compile

Chris Snijder's avatar
Chris Snijder committed
199
200
201
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.

202
203
204
205
.. code-block:: bash

    make docker-install

Chris Snijder's avatar
Chris Snijder committed
206
207
208
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.

209
210
211
212
.. code-block:: bash

    make docker-run

Chris Snijder's avatar
Chris Snijder committed
213
214
215
216
217
218
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
--------

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