root / docs / index.rst @ c27d829e
History | View | Annotate | Download (7.3 kB)
1 | c27d829e | Dimitris Aragiorgis | .. nfdhcpd documentation master file, created by |
---|---|---|---|
2 | c27d829e | Dimitris Aragiorgis | sphinx-quickstart on Mon Jan 20 18:25:17 2014. |
3 | c27d829e | Dimitris Aragiorgis | You can adapt this file completely to your liking, but it should at least |
4 | c27d829e | Dimitris Aragiorgis | contain the root `toctree` directive. |
5 | c27d829e | Dimitris Aragiorgis | |
6 | c27d829e | Dimitris Aragiorgis | Welcome to nfdhcpd's documentation! |
7 | c27d829e | Dimitris Aragiorgis | =================================== |
8 | c27d829e | Dimitris Aragiorgis | |
9 | c27d829e | Dimitris Aragiorgis | nfdhcpd is a userspace server written in python and based on NFQUEUE [1]. The |
10 | c27d829e | Dimitris Aragiorgis | administrator can enable processing of DHCP, NS, RS, DHCPv6 requests on |
11 | c27d829e | Dimitris Aragiorgis | individual TAP interfaces by injecting nfdhcpd in the processing pipeline for |
12 | c27d829e | Dimitris Aragiorgis | IP packets dynamically (by mangling the corresponding packet types and redirect |
13 | c27d829e | Dimitris Aragiorgis | them to the appropriate nfqueue). |
14 | c27d829e | Dimitris Aragiorgis | |
15 | c27d829e | Dimitris Aragiorgis | The daemon runs on the host and is controlled by manipulating files under its |
16 | c27d829e | Dimitris Aragiorgis | state directory. Creation of a new file under this directory ("binding file") |
17 | c27d829e | Dimitris Aragiorgis | instructs the daemon to reply on the requests arriving on the specified TAP |
18 | c27d829e | Dimitris Aragiorgis | interface. |
19 | c27d829e | Dimitris Aragiorgis | |
20 | c27d829e | Dimitris Aragiorgis | nfdhcpd vs. dnsmasq |
21 | c27d829e | Dimitris Aragiorgis | ------------------- |
22 | c27d829e | Dimitris Aragiorgis | |
23 | c27d829e | Dimitris Aragiorgis | a) The service can be activated dynamically, per-interface, by manipulating |
24 | c27d829e | Dimitris Aragiorgis | iptables accordingly. There is no need to restart the daemon, or edit |
25 | c27d829e | Dimitris Aragiorgis | (potentially read-only) configuration files, you only need to drop a file |
26 | c27d829e | Dimitris Aragiorgis | containing the required info under /var/lib/nfdhcpd. |
27 | c27d829e | Dimitris Aragiorgis | |
28 | c27d829e | Dimitris Aragiorgis | b) There is no interference to existing DHCP servers listening to port |
29 | c27d829e | Dimitris Aragiorgis | 67. Everything happens directly via NFQUEUE. |
30 | c27d829e | Dimitris Aragiorgis | |
31 | c27d829e | Dimitris Aragiorgis | c) The host doesn't even need to have an IP address on the interfaces |
32 | c27d829e | Dimitris Aragiorgis | where DHCP replies are served, making it invisible to the VMs. This |
33 | c27d829e | Dimitris Aragiorgis | may be beneficial from a security perspective. Similarly, it doesn't |
34 | c27d829e | Dimitris Aragiorgis | matter if the TAP interface is bridged or routed. |
35 | c27d829e | Dimitris Aragiorgis | |
36 | c27d829e | Dimitris Aragiorgis | d) Binding files provide a TAP-MAC mapping. In other words, requests coming |
37 | c27d829e | Dimitris Aragiorgis | from unregistered TAP interfaces (without a binding file) are ignored, and |
38 | c27d829e | Dimitris Aragiorgis | packet processing happens as if nfdhcpd didn't exist in the first place. |
39 | c27d829e | Dimitris Aragiorgis | Requests coming from a registered device with but with different are considered |
40 | c27d829e | Dimitris Aragiorgis | as snooping attempts and are dropped. |
41 | c27d829e | Dimitris Aragiorgis | |
42 | c27d829e | Dimitris Aragiorgis | e) nfdhcpd is written in pure Python and uses scapy for packet |
43 | c27d829e | Dimitris Aragiorgis | processing. This has proved super-useful when trying to troubleshooting |
44 | c27d829e | Dimitris Aragiorgis | networking problems in production. |
45 | c27d829e | Dimitris Aragiorgis | |
46 | c27d829e | Dimitris Aragiorgis | A simple scenario |
47 | c27d829e | Dimitris Aragiorgis | ----------------- |
48 | c27d829e | Dimitris Aragiorgis | |
49 | c27d829e | Dimitris Aragiorgis | a) nfdhcpd starts. Upon initialization, it creates an NFQUEUE (e.g., 42, |
50 | c27d829e | Dimitris Aragiorgis | configurable), and listens on it for incoming DHCP requests. It also begins to |
51 | c27d829e | Dimitris Aragiorgis | watch its state directory, `/var/lib/nfdhcpd` via inotify(). |
52 | c27d829e | Dimitris Aragiorgis | |
53 | c27d829e | Dimitris Aragiorgis | b) A new VM gets created, let's assume its NIC has address mac0, lives on TAP |
54 | c27d829e | Dimitris Aragiorgis | interface tap0, and is to receive IP address ip0 via DHCP. |
55 | c27d829e | Dimitris Aragiorgis | |
56 | c27d829e | Dimitris Aragiorgis | c) Someone (e.g., a Ganeti KVM ifup script, or in our case snf-network [2] |
57 | c27d829e | Dimitris Aragiorgis | creates a new binding file informing nfdhcpd that it is to reply to DHCP |
58 | c27d829e | Dimitris Aragiorgis | requests from MAC mac0 on TAP interface tap0, and include IP ip0 in the DHCP |
59 | c27d829e | Dimitris Aragiorgis | reply. |
60 | c27d829e | Dimitris Aragiorgis | |
61 | c27d829e | Dimitris Aragiorgis | d) The ifup script or the administrator injects nfdhcpd in the processing |
62 | c27d829e | Dimitris Aragiorgis | pipeline for packets coming from tap0, using iptables: |
63 | c27d829e | Dimitris Aragiorgis | |
64 | c27d829e | Dimitris Aragiorgis | .. code-block:: console |
65 | c27d829e | Dimitris Aragiorgis | |
66 | c27d829e | Dimitris Aragiorgis | # iptables -t mangle -A PREROUTING -i tap0 -m udp -p udp --dport 67 -j NFQUEUE --queue-num 42 |
67 | c27d829e | Dimitris Aragiorgis | |
68 | c27d829e | Dimitris Aragiorgis | e) From now on, whenever a DHCP request is sent out by the VM, the |
69 | c27d829e | Dimitris Aragiorgis | iptables rule will forward the packet to nfdhcpd, which will consult |
70 | c27d829e | Dimitris Aragiorgis | its bindings database, find the entry for tap0, verify the source MAC, |
71 | c27d829e | Dimitris Aragiorgis | and inject a DHCP reply for the corresponding IP address into tap0. |
72 | c27d829e | Dimitris Aragiorgis | |
73 | c27d829e | Dimitris Aragiorgis | Binding file |
74 | c27d829e | Dimitris Aragiorgis | ------------ |
75 | c27d829e | Dimitris Aragiorgis | |
76 | c27d829e | Dimitris Aragiorgis | A binding file in nfdhcpd's state directory is named after the |
77 | c27d829e | Dimitris Aragiorgis | physical interface where the daemon is to receive incoming DHCP requests |
78 | c27d829e | Dimitris Aragiorgis | from, and defines at least the following variables: |
79 | c27d829e | Dimitris Aragiorgis | |
80 | c27d829e | Dimitris Aragiorgis | * ``INSTANCE``: The instance name related to this inteface |
81 | c27d829e | Dimitris Aragiorgis | |
82 | c27d829e | Dimitris Aragiorgis | * ``INDEV``: The logical interface where the packet is received on. For |
83 | c27d829e | Dimitris Aragiorgis | bridged setups, the bridge interface, e.g., br0. Otherwise, same as |
84 | c27d829e | Dimitris Aragiorgis | the file name. |
85 | c27d829e | Dimitris Aragiorgis | |
86 | c27d829e | Dimitris Aragiorgis | * ``MAC``: The MAC address where the DHCP request must be originating from |
87 | c27d829e | Dimitris Aragiorgis | |
88 | c27d829e | Dimitris Aragiorgis | * ``IP``: The IPv4 address to be returned in DHCP replies |
89 | c27d829e | Dimitris Aragiorgis | |
90 | c27d829e | Dimitris Aragiorgis | * ``SUBNET``: The IPv4 subnet to be returned in DHCP replies in CIDR form |
91 | c27d829e | Dimitris Aragiorgis | |
92 | c27d829e | Dimitris Aragiorgis | * ``GATEWAY``: The IPv4 gateway to be returned in DHCP replies |
93 | c27d829e | Dimitris Aragiorgis | |
94 | c27d829e | Dimitris Aragiorgis | * ``SUBNET6``: The IPv6 network prefix |
95 | c27d829e | Dimitris Aragiorgis | |
96 | c27d829e | Dimitris Aragiorgis | * ``GATEWAY6``: The IPv6 network gateway |
97 | c27d829e | Dimitris Aragiorgis | |
98 | c27d829e | Dimitris Aragiorgis | * ``EUI64``: The IPv6 address of the instance |
99 | c27d829e | Dimitris Aragiorgis | |
100 | c27d829e | Dimitris Aragiorgis | |
101 | c27d829e | Dimitris Aragiorgis | nfdhcpd.conf |
102 | c27d829e | Dimitris Aragiorgis | ------------ |
103 | c27d829e | Dimitris Aragiorgis | |
104 | c27d829e | Dimitris Aragiorgis | The configuration file for nfdhcp is `/etc/nfdhpcd/nfdhcpd.conf`. Three |
105 | c27d829e | Dimitris Aragiorgis | sections are defined: general, dhcp, ipv6. |
106 | c27d829e | Dimitris Aragiorgis | |
107 | c27d829e | Dimitris Aragiorgis | Note that nfdhcpd can run as nobody. This and other options related to |
108 | c27d829e | Dimitris Aragiorgis | its execution environment are defined in general section. |
109 | c27d829e | Dimitris Aragiorgis | |
110 | c27d829e | Dimitris Aragiorgis | In the dhcp section we define the options related to DHCP responses. |
111 | c27d829e | Dimitris Aragiorgis | Specifically: |
112 | c27d829e | Dimitris Aragiorgis | |
113 | c27d829e | Dimitris Aragiorgis | * ``enable_dhcp`` to globally enable/disable DHCP |
114 | c27d829e | Dimitris Aragiorgis | |
115 | c27d829e | Dimitris Aragiorgis | * ``server_ip`` a dummy IP that the VMs will as src IP of the response |
116 | c27d829e | Dimitris Aragiorgis | |
117 | c27d829e | Dimitris Aragiorgis | * ``dhcp_queue`` the a NFQUEUE number to listen on for DHCP requests |
118 | c27d829e | Dimitris Aragiorgis | |
119 | c27d829e | Dimitris Aragiorgis | | Please not that this queue *must* be used in iptables mangle rule. |
120 | c27d829e | Dimitris Aragiorgis | |
121 | c27d829e | Dimitris Aragiorgis | * ``nameservers`` IPv4 nameservers to include in DHCP responses |
122 | c27d829e | Dimitris Aragiorgis | |
123 | c27d829e | Dimitris Aragiorgis | * ``domain`` the domain to serve with the replies (optional) |
124 | c27d829e | Dimitris Aragiorgis | |
125 | c27d829e | Dimitris Aragiorgis | | If not given the instance's name (hostname) will be used instead. |
126 | c27d829e | Dimitris Aragiorgis | |
127 | c27d829e | Dimitris Aragiorgis | In the ipv6 section we define the options related to IPv6 responses. Currently |
128 | c27d829e | Dimitris Aragiorgis | nfdhcpd supports IPv6 stateless configuration [3]. The instance will get an |
129 | c27d829e | Dimitris Aragiorgis | auto-generated IPv6 (MAC to eui64) based on the IPv6 prefix exported by Router |
130 | c27d829e | Dimitris Aragiorgis | Advertisements (O flag set, M flag unset). This kind of RA will make instance |
131 | c27d829e | Dimitris Aragiorgis | query for nameservers and domain search list via DHCPv6 request. |
132 | c27d829e | Dimitris Aragiorgis | nfdhcpd, currently and in case of IPv6, is supposed to work on a routed setup |
133 | c27d829e | Dimitris Aragiorgis | where the instances are not on the same collision domain with the external |
134 | c27d829e | Dimitris Aragiorgis | router and thus any RA/NA should be served locally. Specifically: |
135 | c27d829e | Dimitris Aragiorgis | |
136 | c27d829e | Dimitris Aragiorgis | * ``enable_ipv6`` to globally enable/disable IPv6 responses |
137 | c27d829e | Dimitris Aragiorgis | |
138 | c27d829e | Dimitris Aragiorgis | * ``ra_period`` to define how often nfdhcpd will send RAs to TAPs with IPv6 |
139 | c27d829e | Dimitris Aragiorgis | |
140 | c27d829e | Dimitris Aragiorgis | * ``rs_queue`` the NFQUEUE number to listen on for router solicitations |
141 | c27d829e | Dimitris Aragiorgis | |
142 | c27d829e | Dimitris Aragiorgis | * ``ns_queue`` the NFQUEUE number to listen on for neighbor solicitations |
143 | c27d829e | Dimitris Aragiorgis | |
144 | c27d829e | Dimitris Aragiorgis | * ``dhcp_queue`` the NFQUEUE number to listen on for DHCPv6 request |
145 | c27d829e | Dimitris Aragiorgis | |
146 | c27d829e | Dimitris Aragiorgis | * ``nmeservers`` the IPv6 nameservers |
147 | c27d829e | Dimitris Aragiorgis | |
148 | c27d829e | Dimitris Aragiorgis | | They can be send using the RDNSS option of the RA [4]. |
149 | c27d829e | Dimitris Aragiorgis | | Since it is not supported by Windows we serve them via DHCPv6 responses |
150 | c27d829e | Dimitris Aragiorgis | |
151 | c27d829e | Dimitris Aragiorgis | * ``domains`` the domain search list |
152 | c27d829e | Dimitris Aragiorgis | |
153 | c27d829e | Dimitris Aragiorgis | | If not given the instance's name (hostname) will be used instead. |
154 | c27d829e | Dimitris Aragiorgis | |
155 | c27d829e | Dimitris Aragiorgis | iptables |
156 | c27d829e | Dimitris Aragiorgis | -------- |
157 | c27d829e | Dimitris Aragiorgis | |
158 | c27d829e | Dimitris Aragiorgis | In order nfdhcpd to be able to process incoming requests you have to mangle |
159 | c27d829e | Dimitris Aragiorgis | the corresponding packages. Please note that in case of bridged setup the |
160 | c27d829e | Dimitris Aragiorgis | kernel understands that the packets are coming from the bridge (logical indev) |
161 | c27d829e | Dimitris Aragiorgis | and not from the tap (physical indev). Specifically: |
162 | c27d829e | Dimitris Aragiorgis | |
163 | c27d829e | Dimitris Aragiorgis | * **DHCP**: ``iptables -t mangle -A PREROUTING -i tap+ -p udp --dport 67 -j NFQUEUE --queue-num 42`` |
164 | c27d829e | Dimitris Aragiorgis | |
165 | c27d829e | Dimitris Aragiorgis | * **RS**: ``ip6tables -t mangle -A PREROUTING -i tap+ -p icmpv6 --icmpv6-type router-solicitation -j NFQUEUE --queue-num 43`` |
166 | c27d829e | Dimitris Aragiorgis | |
167 | c27d829e | Dimitris Aragiorgis | * **NS**: ``ip6tables -t mangle -A PREROUTING -i tap+ -p icmpv6 --icmpv6-type neighbour-solicitation -j NFQUEUE --queue-num 44`` |
168 | c27d829e | Dimitris Aragiorgis | |
169 | c27d829e | Dimitris Aragiorgis | * **DHCPv6**: ``ip6tables -t mangle -A PREROUTING -i tap+ -p udp --dport 547 -j NFQUEUE --queue-num 45`` |
170 | c27d829e | Dimitris Aragiorgis | |
171 | c27d829e | Dimitris Aragiorgis | For a bridged setup replace tap+ with br+ in case of DHCP. Using nfdhcpd |
172 | c27d829e | Dimitris Aragiorgis | for IPv6 in a bridged setup does not make any sense. The above rules are |
173 | c27d829e | Dimitris Aragiorgis | included in `/etc/ferm/nfdhcpd.ferm` . |
174 | c27d829e | Dimitris Aragiorgis | In case you use ferm, this file should be included in `/etc/ferm/ferm.conf`. |
175 | c27d829e | Dimitris Aragiorgis | Otherwise an `rc.local` script can be used to issue those rules upon boot. |
176 | c27d829e | Dimitris Aragiorgis | |
177 | c27d829e | Dimitris Aragiorgis | |
178 | c27d829e | Dimitris Aragiorgis | |
179 | c27d829e | Dimitris Aragiorgis | | [1] https://www.wzdftpd.net/redmine/projects/nfqueue-bindings/wiki/ |
180 | c27d829e | Dimitris Aragiorgis | | [2] https://code.grnet.gr/projects/snf-network/ |
181 | c27d829e | Dimitris Aragiorgis | | [3] https://tools.ietf.org/html/rfc4862 |
182 | c27d829e | Dimitris Aragiorgis | | [4] https://tools.ietf.org/html/rfc5006 |