BUILDING.md

   1 # Building dhcpcd
   2
   3 This attempts to document various ways of building dhcpcd for your
   4 platform.
   5
   6 ## Size is an issue
   7 To compile small dhcpcd, maybe to be used for installation media where
   8 size is a concern, you can use the `--small` configure option to enable
   9 a reduced feature set within dhcpcd.
  10 Currently this just removes non important options out of
  11 `dhcpcd-definitions.conf`, the logfile option,
  12 DHCPv6 Prefix Delegation and IPv6 address announcement *(to prefer an
  13 address on another interface)*.
  14 Other features maybe dropped as and when required.
  15 dhcpcd can also be made smaller by removing the IPv4 or IPv6 stack:
  16   *  `--disable-inet`
  17   *  `--disable-inet6`
  18
  19 Or by removing the following features:
  20   *  `--disable-auth`
  21   *  `--disable-arp`
  22   *  `--disable-arping`
  23   *  `--disable-ipv4ll`
  24   *  `--disable-dhcp6`
  25   *  `--disable-privsep`
  26
  27 You can also move the embedded extended configuration from the dhcpcd binary
  28 to an external file (LIBEXECDIR/dhcpcd-definitions.conf)
  29   *  `--disable-embedded`
  30 If dhcpcd cannot load this file at runtime, dhcpcd will work but will not be
  31 able to decode any DHCP/DHCPv6 options that are not defined by the user
  32 in /etc/dhcpcd.conf. This does not really change the total on disk size.
  33
  34 ## Cross compiling
  35 If you're cross compiling you may need set the platform if OS is different
  36 from the host.
  37 `--target=sparc-sun-netbsd5.0`
  38
  39 If you're building for an MMU-less system where fork() does not work, you
  40 should `./configure --disable-fork`.
  41 This also puts the `--no-background` flag on and stops the `--background` flag
  42 from working.
  43
  44 ## Default directories
  45 You can change the default dirs with these knobs.
  46 For example, to satisfy FHS compliance you would do this:
  47 `./configure --libexecdir=/lib/dhcpcd dbdir=/var/lib/dhcpcd`
  48
  49 ## Compile Issues
  50 We now default to using `-std=c99`. For 64-bit linux, this always works, but
  51 for 32-bit linux it requires either gnu99 or a patch to `asm/types.h`.
  52 Most distros patch linux headers so this should work fine.
  53 linux-2.6.24 finally ships with a working 32-bit header.
  54 If your linux headers are older, or your distro hasn't patched them you can
  55 set `CSTD=gnu99` to work around this.
  56
  57 ArchLinux presently sanitises all kernel headers to the latest version
  58 regardless of the version for your CPU. As such, Arch presently ships a
  59 3.12 kernel with 3.17 headers which claim that it supports temporary address
  60 management and no automatic prefix route generation, both of which are
  61 obviously false. You will have to patch support either in the kernel or
  62 out of the headers (or dhcpcd itself) to have correct operation.
  63
  64 Linux netlink headers cause a sign conversion error.
  65 I [submitted a patch](https://lkml.org/lkml/2019/12/17/680),
  66 but as yet it's not upstreamed.
  67
  68 GLIBC ships an icmp6.h header which will result in signedness warnings.
  69 Their [bug #22489](https://sourceware.org/bugzilla/show_bug.cgi?id=22489)
  70 will solve this once it's actually applied.
  71
  72 ## OS specific issues
  73 Some BSD systems do not allow the manipulation of automatically added subnet
  74 routes. You can find discussion here:
  75     http://mail-index.netbsd.org/tech-net/2008/12/03/msg000896.html
  76 BSD systems where this has been fixed or is known to work are:
  77     NetBSD-5.0
  78     FreeBSD-10.0
  79
  80 Some BSD systems protect against IPv6 NS/NA messages by ensuring that the
  81 source address matches a prefix on the recieved by a RA message.
  82 This is an error as the correct check is for on-link prefixes as the
  83 kernel may not be handling RA itself.
  84 BSD systems where this has been fixed or is known to work are:
  85     NetBSD-7.0
  86     OpenBSD-5.0
  87     patch submitted against FreeBSD-10.0
  88
  89 Some BSD systems do not announce IPv6 address flag changes, such as
  90 `IN6_IFF_TENTATIVE`, `IN6_IFF_DUPLICATED`, etc. On these systems,
  91 dhcpcd will poll a freshly added address until either `IN6_IFF_TENTATIVE` is
  92 cleared or `IN6_IFF_DUPLICATED` is set and take action accordingly.
  93 BSD systems where this has been fixed or is known to work are:
  94     NetBSD-7.0
  95
  96 OpenBSD will always add it's own link-local address if no link-local address
  97 exists, because it doesn't check if the address we are adding is a link-local
  98 address or not.
  99
 100 Some BSD systems do not announce cached neighbour route changes based
 101 on reachability to userland. For such systems, IPv6 routers will always
 102 be assumed to be reachable until they either stop being a router or expire.
 103 BSD systems where this has been fixed or is known to work are:
 104     NetBSD-7.99.3
 105
 106 Linux prior to 3.17 won't allow userland to manage IPv6 temporary addresses.
 107 Either upgrade or don't allow dhcpcd to manage the RA,
 108 so don't set either `ipv6ra_own` or `slaac private` in `dhcpcd.conf` if you
 109 want to have working IPv6 temporary addresses.
 110 SLAAC private addresses are just as private, just stable.
 111
 112 ## Init systems
 113 We try and detect how dhcpcd should interact with system services at runtime.
 114 If we cannot auto-detect how do to this, or it is wrong then
 115 you can change this by passing shell commands to `--serviceexists`,
 116 `--servicecmd` and optionally `--servicestatus` to `./configure` or overriding
 117 the service variables in a hook.
 118
 119
 120 ## /dev management
 121 Some systems have `/dev` management systems and some of these like to rename
 122 interfaces. As this system would listen in the same way as dhcpcd to new
 123 interface arrivals, dhcpcd needs to listen to the `/dev` management sytem
 124 instead of the kernel. However, if the `/dev` management system breaks, stops
 125 working, or changes to a new one, dhcpcd should still try and continue to work.
 126 To facilitate this, dhcpcd allows a plugin to load to instruct dhcpcd when it
 127 can use an interface. As of the time of writing only udev support is included.
 128 You can disable this with `--without-dev`, or `without-udev`.
 129 NOTE: in Gentoo at least, `sys-fs/udev` as provided by systemd leaks memory
 130 `sys-fs/eudev`, the fork of udev does not and as such is recommended.
 131
 132
 133 ## Importing into another source control system
 134 To import the full sources, use the import target.
 135 To import only the needed sources and documentation, use the import-src
 136 target.
 137 Both targets support DESTDIR to set the installation directory,
 138 if unset it defaults to `/tmp/dhcpcd-$VERSION`
 139 Example: `make DESTDIR=/usr/src/contrib/dhcpcd import-src`
 140
 141
 142 ## Hooks
 143 Not all the hooks in dhcpcd-hooks are installed by default.
 144 By default we install `01-test`, `20-resolv.conf`and `30-hostname`.
 145 The other hooks, `10-wpa_supplicant`, `15-timezone` and `29-lookup-hostname`
 146 are installed to `$(datadir)/dhcpcd/hooks` by default and need to be
 147 copied to `$(libexecdir)/dhcpcd-hooks` for use.
 148 The configure program attempts to find hooks for systems you have installed.
 149 To add more simply
 150 `./configure -with-hook=ntp.conf`