README

   1 KERNEL SOURCE:
   2 ==============
   3
   4 We currently use the Ubuntu kernel sources, available from:
   5
   6  http://kernel.ubuntu.com/git/ubuntu/ubuntu-hirsute.git/
   7
   8 Ubuntu will maintain those kernels till:
   9
  10  https://wiki.ubuntu.com/Kernel/Dev/ExtendedStable
  11
  12
  13 Additional/Updated Modules:
  14 ---------------------------
  15
  16 - include native OpenZFS filesystem kernel modules for Linux
  17
  18   * https://github.com/zfsonlinux/
  19
  20   For licensing questions, see: http://open-zfs.org/wiki/Talk:FAQ
  21
  22
  23 SUBMODULE
  24 =========
  25
  26 We track the current upstream repository as submodule. Besides obvious
  27 advantages over tracking binary tar archives this also has some implications.
  28
  29 For building the submodule directory gets copied into build/ and a few patches
  30 get applied with the `patch` tool. From a git point-of-view, the copied
  31 directory remains clean even with extra patches applied since it does not
  32 contain a .git directory, but a reference to the (still pristine) submodule:
  33
  34 $ cat build/ubuntu-hirsute/.git
  35
  36 If you mistakenly cloned the upstream repo as "normal" clone (not via the
  37 submodule mechanics) this means that you have a real .git directory with its
  38 independent objects and tracking info when copying for building, thus git
  39 operates on the copied directory - and "sees" that it was dirtied by `patch`,
  40 and thus the kernel buildsystem sees this too and will add a '+' to the version
  41 as a result. This changes the output directories for modules and other build
  42 artefacts and let's then the build fail on packaging.
  43
  44 So always ensure that you really checked it out as submodule, not as full
  45 "normal" clone. You can also explicitly set the LOCALVERSION variable to
  46 undefined with: `export LOCALVERSION= but that should only be done for test
  47 builds.
  48
  49 RELATED PACKAGES:
  50 =================
  51
  52 proxmox-ve
  53 ----------
  54
  55 top level meta package, depends on current default kernel series meta package.
  56
  57 git clone git://git.proxmox.com/git/proxmox-ve.git
  58
  59 pve-kernel-meta
  60 ---------------
  61
  62 depends on latest kernel and header package within a certain kernel series,
  63 e.g., pve-kernel-4.15 / pve-headers-4.15
  64
  65 git clone git://git.proxmox.com/git/pve-kernel-meta.git
  66
  67 pve-firmware
  68 ------------
  69
  70 contains the firmware for all released PVE kernels.
  71
  72 git clone git://git.proxmox.com/git/pve-firmware.git
  73
  74
  75 NOTES:
  76 ======
  77
  78 ABI versions, package versions and package name:
  79 ------------------------------------------------
  80
  81 We follow debian's versioning w.r.t ABI changes:
  82
  83 https://kernel-team.pages.debian.net/kernel-handbook/ch-versions.html
  84 https://wiki.debian.org/DebianKernelABIChanges
  85
  86 The debian/rules file has a target comparing the build kernel's ABI against the
  87 version stored in the repository and indicates when an ABI bump is necessary.
  88 An ABI bump within one upstream version consists of incrementing the KREL
  89 variable in the Makefile, rebuilding the packages and running 'make abiupdate'
  90 (the 'abiupdate' target in 'Makefile' contains the steps for consistently
  91 updating the repository).
  92
  93 Watchdog blacklist
  94 ------------------
  95
  96 By default, all watchdog modules are black-listed because it is totally undefined
  97 which device is actually used for /dev/watchdog.
  98 We ship this list in /lib/modprobe.d/blacklist_pve-kernel-<VERSION>.conf
  99 The user typically edit /etc/modules to enable a specific watchdog device.
 100
 101 Debug kernel and modules
 102 ------------------------
 103
 104 In order to build a -dbgsym package containing an unstripped copy of the kernel
 105 image and modules, enable the 'pkg.pve-kernel.debug' build profile (e.g. by
 106 exporting DEB_BUILD_PROFILES='pkg.pve-kernel.debug'). The resulting package can
 107 be used together with 'crash'/'kdump-tools' to debug kernel crashes.
 108
 109 Note: the -dbgsym package is only valid for the pve-kernel packages produced by
 110 the same build. A kernel/module from a different build will likely not match,
 111 even if both builds are of the same kernel and package version.
 112
 113 Additional information
 114 ----------------------
 115
 116 We use the default configuration provided by Ubuntu, and apply
 117 the following modifications:
 118
 119 NOTE: For the exact and current list see debian/rules (PVE_CONFIG_OPTS)
 120
 121 - enable INTEL_MEI_WDT=m (to allow disabling via patch)
 122
 123 - disable CONFIG_SND_PCM_OSS (enabled by default in Ubuntu, not needed)
 124
 125 - switch CONFIG_TRANSPARENT_HUGEPAGE to MADVISE from ALWAYS
 126
 127 - enable CONFIG_CEPH_FS=m (request from user)
 128
 129 - enable common CONFIG_BLK_DEV_XXX to avoid hardware detection
 130   problems (udev, update-initramfs have serious problems without that)
 131
 132          CONFIG_BLK_DEV_SD=y
 133          CONFIG_BLK_DEV_SR=y
 134          CONFIG_BLK_DEV_DM=y
 135
 136 - add workaround for Debian bug #807000 (see
 137   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=807000)
 138
 139          CONFIG_BLK_DEV_NVME=y
 140
 141 - compile NBD and RBD modules
 142          CONFIG_BLK_DEV_NBD=m
 143          CONFIG_BLK_DEV_RBD=m
 144
 145 - enable IBM JFS file system as module
 146
 147   enable it as requested by users (bug #64)
 148
 149 - enable apple HFS and HFSPLUS as module
 150
 151   enable it as requested by users
 152
 153 - enable CONFIG_BCACHE=m (requested by user)
 154
 155 - enable CONFIG_BRIDGE=y
 156
 157   Else we get warnings on boot, that
 158   net.bridge.bridge-nf-call-iptables is an unknown key
 159
 160 - enable CONFIG_DEFAULT_SECURITY_APPARMOR
 161
 162   We need this for lxc
 163
 164 - set CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE=y
 165
 166   because if not set, it can give some dynamic memory or cpu frequencies
 167   change, and vms can crash (mainly windows guest).
 168
 169   see http://forum.proxmox.com/threads/18238-Windows-7-x64-VMs-crashing-randomly-during-process-termination?p=93273#post93273
 170
 171 - use 'deadline' as default scheduler
 172
 173   This is the suggested setting for KVM. We also measure bad fsync
 174   performance with ext4 and cfq.
 175
 176 - disable CONFIG_INPUT_EVBUG
 177
 178   Module evbug is not blacklisted on debian, so we simply disable it
 179   to avoid key-event logs (which is a big security problem)
 180
 181 - enable CONFIG_MODVERSIONS (needed for ABI tracking)
 182
 183 - switch default UNWINDER to FRAME_POINTER
 184
 185   the recently introduced ORC_UNWINDER is not 100% stable yet, especially in combination with ZFS
 186
 187 - enable CONFIG_PAGE_TABLE_ISOLATION (Meltdown mitigation)