1=================== 2Reproducible builds 3=================== 4 5It is generally desirable that building the same source code with 6the same set of tools is reproducible, i.e. the output is always 7exactly the same. This makes it possible to verify that the build 8infrastructure for a binary distribution or embedded system has not 9been subverted. This can also make it easier to verify that a source 10or tool change does not make any difference to the resulting binaries. 11 12The `Reproducible Builds project`_ has more information about this 13general topic. This document covers the various reasons why building 14the kernel may be unreproducible, and how to avoid them. 15 16Timestamps 17---------- 18 19The kernel embeds timestamps in three 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* If enabled via ``CONFIG_IKHEADERS``, file timestamps of kernel 27 headers embedded in the kernel or respective module, 28 exposed via ``/sys/kernel/kheaders.tar.xz`` 29 30By default the timestamp is the current time and in the case of 31``kheaders`` the various files' modification times. This must 32be overridden using the `KBUILD_BUILD_TIMESTAMP`_ variable. 33If you are building from a git commit, you could use its commit date. 34 35The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, 36and enables warnings if they are used. If you incorporate external 37code that does use these, you must override the timestamp they 38correspond to by setting the `SOURCE_DATE_EPOCH`_ environment 39variable. 40 41User, host 42---------- 43 44The kernel embeds the building user and host names in 45``/proc/version``. These must be overridden using the 46`KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables. If you are 47building from a git commit, you could use its committer address. 48 49Generated files in source packages 50---------------------------------- 51 52The build processes for some programs under the ``tools/`` 53subdirectory do not completely support out-of-tree builds. This may 54cause a later source package build using e.g. ``make rpm-pkg`` to 55include generated files. You should ensure the source tree is 56pristine by running ``make mrproper`` or ``git clean -d -f -x`` before 57building a source package. 58 59Module signing 60-------------- 61 62If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to 63generate a different temporary key for each build, resulting in the 64modules being unreproducible. However, including a signing key with 65your source would presumably defeat the purpose of signing modules. 66 67One approach to this is to divide up the build process so that the 68unreproducible parts can be treated as sources: 69 701. Generate a persistent signing key. Add the certificate for the key 71 to the kernel source. 72 732. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the 74 signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an 75 empty string, and disable ``CONFIG_MODULE_SIG_ALL``. 76 Build the kernel and modules. 77 783. Create detached signatures for the modules, and publish them as 79 sources. 80 814. Perform a second build that attaches the module signatures. It 82 can either rebuild the modules or use the output of step 2. 83 84Structure randomisation 85----------------------- 86 87If you enable ``CONFIG_RANDSTRUCT``, you will need to pre-generate 88the random seed in ``scripts/basic/randstruct.seed`` so the same 89value is used by each build. See ``scripts/gen-randstruct-seed.sh`` 90for details. 91 92Debug info conflicts 93-------------------- 94 95This is not a problem of unreproducibility, but of generated files 96being *too* reproducible. 97 98Once you set all the necessary variables for a reproducible build, a 99vDSO's debug information may be identical even for different kernel 100versions. This can result in file conflicts between debug information 101packages for the different kernel versions. 102 103To avoid this, you can make the vDSO different for different 104kernel versions by including an arbitrary string of "salt" in it. 105This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``. 106 107Git 108--- 109 110Uncommitted changes or different commit ids in git can also lead 111to different compilation results. For example, after executing 112``git reset HEAD^``, even if the code is the same, the 113``include/config/kernel.release`` generated during compilation 114will be different, which will eventually lead to binary differences. 115See ``scripts/setlocalversion`` for details. 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.. _Reproducible Builds project: https://reproducible-builds.org/ 120.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/ 121