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-impish.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-impish/.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 - compile NBD and RBD modules
 137          CONFIG_BLK_DEV_NBD=m
 138          CONFIG_BLK_DEV_RBD=m
 139
 140 - enable IBM JFS file system as module
 141
 142   enable it as requested by users (bug #64)
 143
 144 - enable apple HFS and HFSPLUS as module
 145
 146   enable it as requested by users
 147
 148 - enable CONFIG_BCACHE=m (requested by user)
 149
 150 - enable CONFIG_BRIDGE=y
 151
 152   Else we get warnings on boot, that
 153   net.bridge.bridge-nf-call-iptables is an unknown key
 154
 155 - enable CONFIG_DEFAULT_SECURITY_APPARMOR
 156
 157   We need this for lxc
 158
 159 - set CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE=y
 160
 161   because if not set, it can give some dynamic memory or cpu frequencies
 162   change, and vms can crash (mainly windows guest).
 163
 164   see http://forum.proxmox.com/threads/18238-Windows-7-x64-VMs-crashing-randomly-during-process-termination?p=93273#post93273
 165
 166 - use 'deadline' as default scheduler
 167
 168   This is the suggested setting for KVM. We also measure bad fsync
 169   performance with ext4 and cfq.
 170
 171 - disable CONFIG_INPUT_EVBUG
 172
 173   Module evbug is not blacklisted on debian, so we simply disable it
 174   to avoid key-event logs (which is a big security problem)
 175
 176 - enable CONFIG_MODVERSIONS (needed for ABI tracking)
 177
 178 - switch default UNWINDER to FRAME_POINTER
 179
 180   the recently introduced ORC_UNWINDER is not 100% stable yet, especially in combination with ZFS
 181
 182 - enable CONFIG_PAGE_TABLE_ISOLATION (Meltdown mitigation)