History

Documentation: kbuild: Add document about reproducible builds

In the Distribution Kernels track at Linux Plumbers Conference there was some discussion around the difficulty of making kernel builds reproducible. This is a solved problem, but the solutions don't appear to be documented in one place. This document lists the issues I know about and the settings needed to ensure reproducibility.

Ben Hutchings committed 7 years ago

Commit fe013f81 parent cbacb5a2 files · +123 −0Browse files

Unified · Split

2 files
  1. Documentation/kbuild/index.rst +1 −0
  2. Documentation/kbuild/reproducible-builds.rst +122 −0
Documentation/kbuild/index.rst+1−0
@@ -18,6 +18,7 @@ Kernel Build System · 17 unmodified lines
1818 headers_install
1919
2020 issues
21+ reproducible-builds
2122
2223 .. only:: subproject and html
2324
Documentation/kbuild/reproducible-builds.rst+122−0
@@ -0,0 +1,122 @@
1+===================
2+Reproducible builds
3+===================
4+
5+It is generally desirable that building the same source code with
6+the same set of tools is reproducible, i.e. the output is always
7+exactly the same. This makes it possible to verify that the build
8+infrastructure for a binary distribution or embedded system has not
9+been subverted. This can also make it easier to verify that a source
10+or tool change does not make any difference to the resulting binaries.
11+
12+The `Reproducible Builds project`_ has more information about this
13+general topic. This document covers the various reasons why building
14+the kernel may be unreproducible, and how to avoid them.
15+
16+Timestamps
17+----------
18+
19+The kernel embeds a timestamp in two places:
20+
21+* The version string exposed by ``uname()`` and included in
22+ ``/proc/version``
23+
24+* File timestamps in the embedded initramfs
25+
26+By default the timestamp is the current time. This must be overridden
27+using the `KBUILD_BUILD_TIMESTAMP`_ variable. If you are building
28+from a git commit, you could use its commit date.
29+
30+The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
31+and enables warnings if they are used. If you incorporate external
32+code that does use these, you must override the timestamp they
33+correspond to by setting the `SOURCE_DATE_EPOCH`_ environment
34+variable.
35+
36+User, host
37+----------
38+
39+The kernel embeds the building user and host names in
40+``/proc/version``. These must be overridden using the
41+`KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables. If you are
42+building from a git commit, you could use its committer address.
43+
44+Absolute filenames
45+------------------
46+
47+When the kernel is built out-of-tree, debug information may include
48+absolute filenames for the source files. This must be overridden by
49+including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable.
50+
51+Depending on the compiler used, the ``__FILE__`` macro may also expand
52+to an absolute filename in an out-of-tree build. Kbuild automatically
53+uses the ``-fmacro-prefix-map`` option to prevent this, if it is
54+supported.
55+
56+The Reproducible Builds web site has more information about these
57+`prefix-map options`_.
58+
59+Generated files in source packages
60+----------------------------------
61+
62+The build processes for some programs under the ``tools/``
63+subdirectory do not completely support out-of-tree builds. This may
64+cause a later source package build using e.g. ``make rpm-pkg`` to
65+include generated files. You should ensure the source tree is
66+pristine by running ``make mrproper`` or ``git clean -d -f -x`` before
67+building a source package.
68+
69+Module signing
70+--------------
71+
72+If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to
73+generate a different temporary key for each build, resulting in the
74+modules being unreproducible. However, including a signing key with
75+your source would presumably defeat the purpose of signing modules.
76+
77+One approach to this is to divide up the build process so that the
78+unreproducible parts can be treated as sources:
79+
80+1. Generate a persistent signing key. Add the certificate for the key
81+ to the kernel source.
82+
83+2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the
84+ signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an
85+ empty string, and disable ``CONFIG_MODULE_SIG_ALL``.
86+ Build the kernel and modules.
87+
88+3. Create detached signatures for the modules, and publish them as
89+ sources.
90+
91+4. Perform a second build that attaches the module signatures. It
92+ can either rebuild the modules or use the output of step 2.
93+
94+Structure randomisation
95+-----------------------
96+
97+If you enable ``CONFIG_GCC_PLUGIN_RANDSTRUCT``, you will need to
98+pre-generate the random seed in
99+``scripts/gcc-plgins/randomize_layout_seed.h`` so the same value
100+is used in rebuilds.
101+
102+Debug info conflicts
103+--------------------
104+
105+This is not a problem of unreproducibility, but of generated files
106+being *too* reproducible.
107+
108+Once you set all the necessary variables for a reproducible build, a
109+vDSO's debug information may be identical even for different kernel
110+versions. This can result in file conflicts between debug information
111+packages for the different kernel versions.
112+
113+To avoid this, you can make the vDSO different for different
114+kernel versions by including an arbitrary string of "salt" in it.
115+This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``.
116+
117+.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
118+.. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host
119+.. _KCFLAGS: kbuild.html#kcflags
120+.. _prefix-map options: https://reproducible-builds.org/docs/build-path/
121+.. _Reproducible Builds project: https://reproducible-builds.org/
122+.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t