diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index 8e0f8f58a9..4428061ccd 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -7,7 +7,7 @@ dist_html_DATA = $(HTMLDOCS) kea-guide.css DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml logging.xml ddns.xml hooks.xml -DOCBOOK += libdhcp.xml lfc.xml stats.xml ctrl-channel.xml +DOCBOOK += libdhcp.xml lfc.xml stats.xml ctrl-channel.xml faq.xml EXTRA_DIST = $(DOCBOOK) DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml diff --git a/doc/guide/faq.xml b/doc/guide/faq.xml new file mode 100644 index 0000000000..f216163472 --- /dev/null +++ b/doc/guide/faq.xml @@ -0,0 +1,134 @@ + + +]> + + + Frequently Asked Questions + + This chapter contains a number of frequently asked questions and + troubleshooting tips. It currently lacks content, but it is expected to grow + over time. + + + +
+ Generic Frequently Asked Questions + +
+ Where did the Kea name came from? + + Kea is a name of high mountain parrot living in New Zealand. + See this + for an extended answer. + +
+ +
+ Feature X is not supported yet. When/if will it be available? + + Kea is developed by a small team of engineers. Our resources are + limited, so we need to prioritize requests. The complexity of a new + feature (how difficult is it to implement a feature and how likely it + would break something that already works), amount of work required and + expected popularity (i.e. how many users would actually benefit from it) + are three leading factors. We sometimes also have contractual obligations. + + + Simply stating that you'd like feature X is useful. We try to + implement features that are actively requested first, but the reality + is that we have more requests than we can handle, so some of them must + be postponed, at least in the near future. So is your request likely to + be reject? Not at all. You can do many things to greatly improve chances + of your request to be fulfilled. First, it helps to explain why you + need a feature. If your explanation is reasonable and there are likely + other users that would benefit from it, the chances for Kea developers + to put this task on a roadmap is better. Saying that you are willing + to participate in tests (e.g. test engineering drops when they become + available) is also helpful. + + Another thing you can do to greatly improve chances of a feature + to appear is to actually develop it on your own and submit a patch. + That's a venue that people often forget about. Kea is an open source + software and we do accept patches. There are certain requirements, like + code quality, comments, unit-tests, documentation, etc., but we have + accepted a significant number of patches in the past, so it's doable. + Accepted contributions range from minor documentation corrections to + significant new features, like support for new database type. Before + considering writing and submitting a patch, make sure you read + Contributor's Guide in Kea Developer's Guide. + + + Kea is developed by ISC, which is non-profit organization. + You may consider signing a development contract with us. In the past + we did implement certain features due to contractual obligations. + With additional funds we are able to put extra engineering efforts + into Kea development. We can reshuffle our schedule or add extra + hands to the team if needed. Please keep in mind that Kea is an + open source software and its principal goal is to provide good DHCP + solution that can be used by everyone. In other words, we may + refuse a contract that would tie the solution to specific proprietary + technology or make it unusable for other users. Also, we strive to + make Kea a reference implementation, so if your proposal significantly + violates RFC, we may have a problem with that. Nevertheless, please + talk to us and we may be able to find a solution. + + Finally, Kea has a public + roadmap, with releases happening several times each year. We tend + to not modify features for current milestone, unless there are very good + reasons to do so. Therefore "I'd like a featury X in 6 months" is much + better received than "I'd like a feature X now". +
+ +
+ +
+ Frequently Asked Questions about DHCPv4 + +
+ I set up a firewall, but Kea server still receives the traffic. Why? + + Any DHCPv4 server must be able to receive from and send traffic to the + hosts that don't have an IPv4 address assigned yet. That is typically not + possible with regular UDP sockets, therefore Kea DHCPv4 server uses raw + sockets by default. Raw sockets mean that the incoming packets are received + as raw Ethernet frames, thus bypassing the whole kernel IP stack, including + any firewalling rules your kernel may provide. + + If you do not want the server to use raw sockets, it is possible to + config Kea DHCPv4 server to use UDP sockets instead. See dhcp-socket-type + described in . However, + using UDP sockets have certain limitations. In particular, it may not allow + to send responses directly to the clients without IPv4 addresses assigned. + That's ok, if all your traffic is coming through relay agents. +
+ +
+ +
+ Frequently Asked Questions about DHCPv6 + +
+ Kea DHCPv6 doesn't seem to get incoming traffic. I checked with tcpdump (or other traffic + capture software) that the incoming traffic is reaching the box. What's wrong? + + Please check whether your OS has any IPv6 filtering rules. Many + operating systems are shipped with firewalls that discard incoming IPv6 + traffic by default. In particular, many Linux distributions do that. Please + check the output of the following command: + +# ip6tables -L -n + One common mistake in this area is to use iptables tool, + which lists IPv4 firewall rules only. + +
+ +
+ + + diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index fd7524c60d..3adb47d68f 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -81,6 +81,8 @@ + + Acknowledgements