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.
Unified · Split
| @@ -18,6 +18,7 @@ Kernel Build System · 17 unmodified lines | ||
| 18 | 18 | headers_install |
| 19 | 19 | |
| 20 | 20 | issues |
| 21 | + reproducible-builds | |
| 21 | 22 | |
| 22 | 23 | .. only:: subproject and html |
| 23 | 24 | |
| @@ -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/ | |