contrib/dhcpcd/BUILDING.md

   1 # Building dhcpcd
   2
   3 This attempts to document various ways of building dhcpcd for your
   4 platform.
   5
   6 Building for distribution (ie making a dhcpcd source tarball) now requires
   7 gmake-4 or any BSD make.
   8
   9 ## Size is an issue
  10 To compile small dhcpcd, maybe to be used for installation media where
  11 size is a concern, you can use the `--small` configure option to enable
  12 a reduced feature set within dhcpcd.
  13 Currently this just removes non important options out of
  14 `dhcpcd-definitions.conf`, the logfile option and
  15 support for DHCPv6 Prefix Delegation.
  16 Other features maybe dropped as and when required.
  17 dhcpcd can also be made smaller by removing the IPv4 or IPv6 stack:
  18   *  `--disable-inet`
  19   *  `--disable-inet6`
  20
  21 Or by removing the following features:
  22   *  `--disable-auth`
  23   *  `--disable-arp`
  24   *  `--disable-arping`
  25   *  `--disable-ipv4ll`
  26   *  `--disable-dhcp6`
  27
  28 You can also move the embedded extended configuration from the dhcpcd binary
  29 to an external file (LIBEXECDIR/dhcpcd-definitions.conf)
  30   *  `--disable-embedded`
  31 If dhcpcd cannot load this file at runtime, dhcpcd will work but will not be
  32 able to decode any DHCP/DHCPv6 options that are not defined by the user
  33 in /etc/dhcpcd.conf. This does not really change the total on disk size.
  34
  35 ## Cross compiling
  36 If you're cross compiling you may need set the platform if OS is different
  37 from the host.
  38 `--target=sparc-sun-netbsd5.0`
  39
  40 If you're building for an MMU-less system where fork() does not work, you
  41 should `./configure --disable-fork`.
  42 This also puts the `--no-background` flag on and stops the `--background` flag
  43 from working.
  44
  45 ## Default directories
  46 You can change the default dirs with these knobs.
  47 For example, to satisfy FHS compliance you would do this:
  48 `./configure --libexecdir=/lib/dhcpcd dbdir=/var/lib/dhcpcd`
  49
  50 ## Compile Issues
  51 We now default to using `-std=c99`. For 64-bit linux, this always works, but
  52 for 32-bit linux it requires either gnu99 or a patch to `asm/types.h`.
  53 Most distros patch linux headers so this should work fine.
  54 linux-2.6.24 finally ships with a working 32-bit header.
  55 If your linux headers are older, or your distro hasn't patched them you can
  56 set `CSTD=gnu99` to work around this.
  57
  58 ArchLinux presently sanitises all kernel headers to the latest version
  59 regardless of the version for your CPU. As such, Arch presently ships a
  60 3.12 kernel with 3.17 headers which claim that it supports temporary address
  61 management and no automatic prefix route generation, both of which are
  62 obviously false. You will have to patch support either in the kernel or
  63 out of the headers (or dhcpcd itself) to have correct operation.
  64
  65 ## OS specific issues
  66 Some BSD systems do not allow the manipulation of automatically added subnet
  67 routes. You can find discussion here:
  68     http://mail-index.netbsd.org/tech-net/2008/12/03/msg000896.html
  69 BSD systems where this has been fixed or is known to work are:
  70     NetBSD-5.0
  71     FreeBSD-10.0
  72
  73 Some BSD systems protect against IPv6 NS/NA messages by ensuring that the
  74 source address matches a prefix on the recieved by a RA message.
  75 This is an error as the correct check is for on-link prefixes as the
  76 kernel may not be handling RA itself.
  77 BSD systems where this has been fixed or is known to work are:
  78     NetBSD-7.0
  79     OpenBSD-5.0
  80     patch submitted against FreeBSD-10.0
  81
  82 Some BSD systems do not announce IPv6 address flag changes, such as
  83 `IN6_IFF_TENTATIVE`, `IN6_IFF_DUPLICATED`, etc. On these systems,
  84 dhcpcd will poll a freshly added address until either `IN6_IFF_TENTATIVE` is
  85 cleared or `IN6_IFF_DUPLICATED` is set and take action accordingly.
  86 BSD systems where this has been fixed or is known to work are:
  87     NetBSD-7.0
  88
  89 OpenBSD will always add it's own link-local address if no link-local address
  90 exists, because it doesn't check if the address we are adding is a link-local
  91 address or not.
  92
  93 Some BSD systems do not announce cached neighbour route changes based
  94 on reachability to userland. For such systems, IPv6 routers will always
  95 be assumed to be reachable until they either stop being a router or expire.
  96 BSD systems where this has been fixed or is known to work are:
  97     NetBSD-7.99.3
  98
  99 Linux prior to 3.17 won't allow userland to manage IPv6 temporary addresses.
 100 Either upgrade or don't allow dhcpcd to manage the RA,
 101 so don't set either `ipv6ra_own` or `slaac private` in `dhcpcd.conf` if you
 102 want to have working IPv6 temporary addresses.
 103 SLAAC private addresses are just as private, just stable.
 104
 105 ## Init systems
 106 We try and detect how dhcpcd should interact with system services at runtime.
 107 If we cannot auto-detect how do to this, or it is wrong then
 108 you can change this by passing shell commands to `--serviceexists`,
 109 `--servicecmd` and optionally `--servicestatus` to `./configure` or overriding
 110 the service variables in a hook.
 111
 112
 113 ## /dev management
 114 Some systems have `/dev` management systems and some of these like to rename
 115 interfaces. As this system would listen in the same way as dhcpcd to new
 116 interface arrivals, dhcpcd needs to listen to the `/dev` management sytem
 117 instead of the kernel. However, if the `/dev` management system breaks, stops
 118 working, or changes to a new one, dhcpcd should still try and continue to work.
 119 To facilitate this, dhcpcd allows a plugin to load to instruct dhcpcd when it
 120 can use an interface. As of the time of writing only udev support is included.
 121 You can disable this with `--without-dev`, or `without-udev`.
 122 NOTE: in Gentoo at least, `sys-fs/udev` as provided by systemd leaks memory
 123 `sys-fs/eudev`, the fork of udev does not and as such is recommended.
 124
 125 ## select
 126 dhcpcd uses eloop.c, which is a portable main event loop with timeouts and
 127 signal handling. Unlike libevent and similar, it can be transplanted directly
 128 within the application - the only caveat outside of POSIX calls is that
 129 you provide queue.h based on a recent BSD (glibc sys/queue.h is not enough).
 130 eloop supports the following polling mechanisms, listed in order of preference:
 131         kqueue, epoll, pollts, ppoll and pselect.
 132 If signal handling is disabled (ie in RTEMS or other single process
 133 OS's) then eloop can use poll.
 134 You can decide which polling mechanism dhcpcd will select in eloop like so
 135 `./configure --with-poll=[kqueue|epoll|pselect|pollts|ppoll]`
 136
 137
 138 ## Importing into another source control system
 139 To prepare dhcpcd for import into a platform source tree (like NetBSD)
 140 you can use the make import target to create /tmp/dhcpcd-$version and
 141 populate it with all the source files and hooks needed.
 142 In this instance, you may wish to disable some configured tests when
 143 the binary has to run on older versions which lack support, such as getline.
 144 `./configure --without-getline`
 145
 146
 147 ## Hooks
 148 Not all the hooks in dhcpcd-hooks are installed by default.
 149 By default we install `01-test`, `02-dump`, `10-mtu`, `20-resolv.conf`
 150 and `30-hostname`.
 151 The other hooks, `10-wpa_supplicant`, `15-timezone` and `29-lookup-hostname`
 152 are installed to `$(datadir)/dhcpcd/hooks` by default and need to be
 153 copied to `$(libexecdir)/dhcpcd-hooks` for use.
 154 The configure program attempts to find hooks for systems you have installed.
 155 To add more simply
 156 `./configure -with-hook=ntp.conf`
 157
 158 Some system services expose the name of the service we are in,
 159 by default dhcpcd will pick `RC_SVCNAME` from the environment.
 160 You can override this in `CPPFLAGS+= -DRC_SVCNAME="YOUR_SVCNAME"`.
 161 This is important because dhcpcd will scrub the environment aside from `$PATH`
 162 before running hooks.
 163 This variable could be used to facilitate service re-entry so this chain could
 164 happen in a custom OS hook:
 165   dhcpcd service marked inactive && dhcpcd service starts
 166   dependant services are not started because dhcpcd is inactive (not stopped)
 167   dhcpcd hook tests if `$if_up = true` and `$af_waiting` is empty or unset.
 168   if true, mark the dhcpcd service as started and then start dependencies
 169   if false and the dhcpcd service was previously started, mark as inactive and
 170      stop any dependant services.
 171