Documentation/Changes

   1 .. _changes:
   2
   3 Minimal requerements to compile the Kernel
   4 ++++++++++++++++++++++++++++++++++++++++++
   5
   6 Intro
   7 =====
   8
   9 This document is designed to provide a list of the minimum levels of
  10 software necessary to run the 4.x kernels.
  11
  12 This document is originally based on my "Changes" file for 2.0.x kernels
  13 and therefore owes credit to the same people as that file (Jared Mauch,
  14 Axel Boldt, Alessandro Sigala, and countless other users all over the
  15 'net).
  16
  17 Current Minimal Requirements
  18 ****************************
  19
  20 Upgrade to at **least** these software revisions before thinking you've
  21 encountered a bug!  If you're unsure what version you're currently
  22 running, the suggested command should tell you.
  23
  24 Again, keep in mind that this list assumes you are already functionally
  25 running a Linux kernel.  Also, not all tools are necessary on all
  26 systems; obviously, if you don't have any ISDN hardware, for example,
  27 you probably needn't concern yourself with isdn4k-utils.
  28
  29 ====================== ===============  ========================================
  30         Program        Minimal version       Command to check the version
  31 ====================== ===============  ========================================
  32 GNU C                  3.2              gcc --version
  33 GNU make               3.80             make --version
  34 binutils               2.12             ld -v
  35 util-linux             2.10o            fdformat --version
  36 kmod                   13               depmod -V
  37 e2fsprogs              1.41.4           e2fsck -V
  38 jfsutils               1.1.3            fsck.jfs -V
  39 reiserfsprogs          3.6.3            reiserfsck -V
  40 xfsprogs               2.6.0            xfs_db -V
  41 squashfs-tools         4.0              mksquashfs -version
  42 btrfs-progs            0.18             btrfsck
  43 pcmciautils            004              pccardctl -V
  44 quota-tools            3.09             quota -V
  45 PPP                    2.4.0            pppd --version
  46 isdn4k-utils           3.1pre1          isdnctrl 2>&1|grep version
  47 nfs-utils              1.0.5            showmount --version
  48 procps                 3.2.0            ps --version
  49 oprofile               0.9              oprofiled --version
  50 udev                   081              udevd --version
  51 grub                   0.93             grub --version || grub-install --version
  52 mcelog                 0.6              mcelog --version
  53 iptables               1.4.2            iptables -V
  54 openssl & libcrypto    1.0.0            openssl version
  55 bc                     1.06.95          bc --version
  56 Sphinx\ [#f1]_         1.2              sphinx-build --version
  57 ====================== ===============  ========================================
  58
  59 .. [#f1] Sphinx is needed only to build the Kernel documentation
  60
  61 Kernel compilation
  62 ******************
  63
  64 GCC
  65 ---
  66
  67 The gcc version requirements may vary depending on the type of CPU in your
  68 computer.
  69
  70 Make
  71 ----
  72
  73 You will need GNU make 3.80 or later to build the kernel.
  74
  75 Binutils
  76 --------
  77
  78 Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for
  79 assembling the 16-bit boot code, removing the need for ``as86`` to compile
  80 your kernel.  This change does, however, mean that you need a recent
  81 release of binutils.
  82
  83 Perl
  84 ----
  85
  86 You will need perl 5 and the following modules: ``Getopt::Long``,
  87 ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel.
  88
  89 BC
  90 --
  91
  92 You will need bc to build kernels 3.10 and higher
  93
  94
  95 OpenSSL
  96 -------
  97
  98 Module signing and external certificate handling use the OpenSSL program and
  99 crypto library to do key creation and signature generation.
 100
 101 You will need openssl to build kernels 3.7 and higher if module signing is
 102 enabled.  You will also need openssl development packages to build kernels 4.3
 103 and higher.
 104
 105
 106 System utilities
 107 ****************
 108
 109 Architectural changes
 110 ---------------------
 111
 112 DevFS has been obsoleted in favour of udev
 113 (http://www.kernel.org/pub/linux/utils/kernel/hotplug/)
 114
 115 32-bit UID support is now in place.  Have fun!
 116
 117 Linux documentation for functions is transitioning to inline
 118 documentation via specially-formatted comments near their
 119 definitions in the source.  These comments can be combined with the
 120 SGML templates in the Documentation/DocBook directory to make DocBook
 121 files, which can then be converted by DocBook stylesheets to PostScript,
 122 HTML, PDF files, and several other formats.  In order to convert from
 123 DocBook format to a format of your choice, you'll need to install Jade as
 124 well as the desired DocBook stylesheets.
 125
 126 Util-linux
 127 ----------
 128
 129 New versions of util-linux provide ``fdisk`` support for larger disks,
 130 support new options to mount, recognize more supported partition
 131 types, have a fdformat which works with 2.4 kernels, and similar goodies.
 132 You'll probably want to upgrade.
 133
 134 Ksymoops
 135 --------
 136
 137 If the unthinkable happens and your kernel oopses, you may need the
 138 ksymoops tool to decode it, but in most cases you don't.
 139 It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so
 140 that it produces readable dumps that can be used as-is (this also
 141 produces better output than ksymoops).  If for some reason your kernel
 142 is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and
 143 reproduce the Oops with that option, then you can still decode that Oops
 144 with ksymoops.
 145
 146 Mkinitrd
 147 --------
 148
 149 These changes to the ``/lib/modules`` file tree layout also require that
 150 mkinitrd be upgraded.
 151
 152 E2fsprogs
 153 ---------
 154
 155 The latest version of ``e2fsprogs`` fixes several bugs in fsck and
 156 debugfs.  Obviously, it's a good idea to upgrade.
 157
 158 JFSutils
 159 --------
 160
 161 The ``jfsutils`` package contains the utilities for the file system.
 162 The following utilities are available:
 163
 164 - ``fsck.jfs`` - initiate replay of the transaction log, and check
 165   and repair a JFS formatted partition.
 166
 167 - ``mkfs.jfs`` - create a JFS formatted partition.
 168
 169 - other file system utilities are also available in this package.
 170
 171 Reiserfsprogs
 172 -------------
 173
 174 The reiserfsprogs package should be used for reiserfs-3.6.x
 175 (Linux kernels 2.4.x). It is a combined package and contains working
 176 versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and
 177 ``reiserfsck``. These utils work on both i386 and alpha platforms.
 178
 179 Xfsprogs
 180 --------
 181
 182 The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the
 183 ``xfs_repair`` utilities, among others, for the XFS filesystem.  It is
 184 architecture independent and any version from 2.0.0 onward should
 185 work correctly with this version of the XFS kernel code (2.6.0 or
 186 later is recommended, due to some significant improvements).
 187
 188 PCMCIAutils
 189 -----------
 190
 191 PCMCIAutils replaces ``pcmcia-cs``. It properly sets up
 192 PCMCIA sockets at system startup and loads the appropriate modules
 193 for 16-bit PCMCIA devices if the kernel is modularized and the hotplug
 194 subsystem is used.
 195
 196 Quota-tools
 197 -----------
 198
 199 Support for 32 bit uid's and gid's is required if you want to use
 200 the newer version 2 quota format.  Quota-tools version 3.07 and
 201 newer has this support.  Use the recommended version or newer
 202 from the table above.
 203
 204 Intel IA32 microcode
 205 --------------------
 206
 207 A driver has been added to allow updating of Intel IA32 microcode,
 208 accessible as a normal (misc) character device.  If you are not using
 209 udev you may need to::
 210
 211   mkdir /dev/cpu
 212   mknod /dev/cpu/microcode c 10 184
 213   chmod 0644 /dev/cpu/microcode
 214
 215 as root before you can use this.  You'll probably also want to
 216 get the user-space microcode_ctl utility to use with this.
 217
 218 udev
 219 ----
 220
 221 ``udev`` is a userspace application for populating ``/dev`` dynamically with
 222 only entries for devices actually present. ``udev`` replaces the basic
 223 functionality of devfs, while allowing persistent device naming for
 224 devices.
 225
 226 FUSE
 227 ----
 228
 229 Needs libfuse 2.4.0 or later.  Absolute minimum is 2.3.0 but mount
 230 options ``direct_io`` and ``kernel_cache`` won't work.
 231
 232 Networking
 233 **********
 234
 235 General changes
 236 ---------------
 237
 238 If you have advanced network configuration needs, you should probably
 239 consider using the network tools from ip-route2.
 240
 241 Packet Filter / NAT
 242 -------------------
 243 The packet filtering and NAT code uses the same tools like the previous 2.4.x
 244 kernel series (iptables).  It still includes backwards-compatibility modules
 245 for 2.2.x-style ipchains and 2.0.x-style ipfwadm.
 246
 247 PPP
 248 ---
 249
 250 The PPP driver has been restructured to support multilink and to
 251 enable it to operate over diverse media layers.  If you use PPP,
 252 upgrade pppd to at least 2.4.0.
 253
 254 If you are not using udev, you must have the device file /dev/ppp
 255 which can be made by::
 256
 257   mknod /dev/ppp c 108 0
 258
 259 as root.
 260
 261 Isdn4k-utils
 262 ------------
 263
 264 Due to changes in the length of the phone number field, isdn4k-utils
 265 needs to be recompiled or (preferably) upgraded.
 266
 267 NFS-utils
 268 ---------
 269
 270 In ancient (2.4 and earlier) kernels, the nfs server needed to know
 271 about any client that expected to be able to access files via NFS.  This
 272 information would be given to the kernel by ``mountd`` when the client
 273 mounted the filesystem, or by ``exportfs`` at system startup.  exportfs
 274 would take information about active clients from ``/var/lib/nfs/rmtab``.
 275
 276 This approach is quite fragile as it depends on rmtab being correct
 277 which is not always easy, particularly when trying to implement
 278 fail-over.  Even when the system is working well, ``rmtab`` suffers from
 279 getting lots of old entries that never get removed.
 280
 281 With modern kernels we have the option of having the kernel tell mountd
 282 when it gets a request from an unknown host, and mountd can give
 283 appropriate export information to the kernel.  This removes the
 284 dependency on ``rmtab`` and means that the kernel only needs to know about
 285 currently active clients.
 286
 287 To enable this new functionality, you need to::
 288
 289   mount -t nfsd nfsd /proc/fs/nfsd
 290
 291 before running exportfs or mountd.  It is recommended that all NFS
 292 services be protected from the internet-at-large by a firewall where
 293 that is possible.
 294
 295 mcelog
 296 ------
 297
 298 On x86 kernels the mcelog utility is needed to process and log machine check
 299 events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors
 300 reported by the CPU. Processing them is strongly encouraged.
 301
 302 Kernel documentation
 303 ********************
 304
 305 Sphinx
 306 ------
 307
 308 The ReST markups currently used by the Documentation/ files are meant to be
 309 built with ``Sphinx`` version 1.2 or upper. If you're desiring to build
 310 PDF outputs, it is recommended to use version 1.4.6.
 311
 312 .. note::
 313
 314   Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX``
 315   version 3.14159265. Depending on the distribution, you may also need
 316   to install a series of ``texlive`` packages that provide the minimal
 317   set of functionalities required for ``XeLaTex`` to work.
 318
 319 Other tools
 320 -----------
 321
 322 In order to produce documentation from DocBook, you'll also need ``xmlto``.
 323 Please notice, however, that we're currently migrating all documents to use
 324 ``Sphinx``.
 325
 326 Getting updated software
 327 ========================
 328
 329 Kernel compilation
 330 ******************
 331
 332 gcc
 333 ---
 334
 335 - <ftp://ftp.gnu.org/gnu/gcc/>
 336
 337 Make
 338 ----
 339
 340 - <ftp://ftp.gnu.org/gnu/make/>
 341
 342 Binutils
 343 --------
 344
 345 - <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
 346
 347 OpenSSL
 348 -------
 349
 350 - <https://www.openssl.org/>
 351
 352 System utilities
 353 ****************
 354
 355 Util-linux
 356 ----------
 357
 358 - <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
 359
 360 Kmod
 361 ----
 362
 363 - <https://www.kernel.org/pub/linux/utils/kernel/kmod/>
 364 - <https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git>
 365
 366 Ksymoops
 367 --------
 368
 369 - <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
 370
 371 Mkinitrd
 372 --------
 373
 374 - <https://code.launchpad.net/initrd-tools/main>
 375
 376 E2fsprogs
 377 ---------
 378
 379 - <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
 380
 381 JFSutils
 382 --------
 383
 384 - <http://jfs.sourceforge.net/>
 385
 386 Reiserfsprogs
 387 -------------
 388
 389 - <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
 390
 391 Xfsprogs
 392 --------
 393
 394 - <ftp://oss.sgi.com/projects/xfs/>
 395
 396 Pcmciautils
 397 -----------
 398
 399 - <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
 400
 401 Quota-tools
 402 -----------
 403
 404 - <http://sourceforge.net/projects/linuxquota/>
 405
 406 DocBook Stylesheets
 407 -------------------
 408
 409 - <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
 410
 411 XMLTO XSLT Frontend
 412 -------------------
 413
 414 - <http://cyberelk.net/tim/xmlto/>
 415
 416 Intel P6 microcode
 417 ------------------
 418
 419 - <https://downloadcenter.intel.com/>
 420
 421 udev
 422 ----
 423
 424 - <http://www.freedesktop.org/software/systemd/man/udev.html>
 425
 426 FUSE
 427 ----
 428
 429 - <http://sourceforge.net/projects/fuse>
 430
 431 mcelog
 432 ------
 433
 434 - <http://www.mcelog.org/>
 435
 436 Networking
 437 **********
 438
 439 PPP
 440 ---
 441
 442 - <ftp://ftp.samba.org/pub/ppp/>
 443
 444 Isdn4k-utils
 445 ------------
 446
 447 - <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
 448
 449 NFS-utils
 450 ---------
 451
 452 - <http://sourceforge.net/project/showfiles.php?group_id=14>
 453
 454 Iptables
 455 --------
 456
 457 - <http://www.iptables.org/downloads.html>
 458
 459 Ip-route2
 460 ---------
 461
 462 - <https://www.kernel.org/pub/linux/utils/net/iproute2/>
 463
 464 OProfile
 465 --------
 466
 467 - <http://oprofile.sf.net/download/>
 468
 469 NFS-Utils
 470 ---------
 471
 472 - <http://nfs.sourceforge.net/>
 473
 474 Kernel documentation
 475 ********************
 476
 477 Sphinx
 478 ------
 479
 480 - <http://www.sphinx-doc.org/>