From 24db573005a1a960056949154d3713f3931676c5 Mon Sep 17 00:00:00 2001 From: "Nicholas J. Kain" Date: Wed, 13 Jul 2011 02:30:10 -0400 Subject: [PATCH] Write man pages and do some misc cleanup on old files. Add more documentation to the README. --- ifchd/LICENSE => LICENSE | 0 README | 85 ++++++++-- ifchd/ChangeLog | 64 -------- ifchd/ifchd.8 | 91 +++++++++++ ndhc/COPYING | 339 --------------------------------------- ndhc/README | 64 -------- ndhc/ndhc.8 | 113 +++++++++---- ndhc/ndhc.c | 9 +- 8 files changed, 260 insertions(+), 505 deletions(-) rename ifchd/LICENSE => LICENSE (100%) delete mode 100644 ifchd/ChangeLog create mode 100644 ifchd/ifchd.8 delete mode 100644 ndhc/COPYING delete mode 100644 ndhc/README diff --git a/ifchd/LICENSE b/LICENSE similarity index 100% rename from ifchd/LICENSE rename to LICENSE diff --git a/README b/README index 8ba882e..a62ee87 100644 --- a/README +++ b/README @@ -1,14 +1,12 @@ -ndhc + ifchd, copyright (c) 2004-2011 Nicholas Kain. Licensed under GNU GPL2. +ndhc + ifchd, Copyright (C) 2004-2011 Nicholas J. Kain. +Licensed under GNU GPL v2. Requirements: -Linux kernel (tested: 2.4, 2.6) - * libcap is required (available via ftp.kernel.org) - -C99-compliant C compiler (for C99 struct subobject init) - * any modern GCC should be sufficient - -CMake (tested: 2.8) +Linux kernel (2.4 used to work long ago, but I only test 2.6 now) +C99-compliant C compiler (any recent GCC will work) +GNU Make (tested: 3.82) or CMake (tested: 2.8) +libcap (available via ftp.kernel.org) Tested with glibc. dietlibc is not compatible. I have not tested uclibc. @@ -51,6 +49,42 @@ explicitly deconfigured. This functionality can be useful on wired networks when transient carrier downtimes occur (or cables are changed), but it is particularly useful on wireless networks. +FEATURES +-------- + +Privilege-seperated. Neither ifchd or ndhc runs as full root, and capabilities +are divided between the programs. Both programs run in a chroot. + +Robust. ndhc performs no runtime heap allocations -- malloc() is never called +(and neither is brk(), mmap(), etc), and ndhc never performs recursive calls +and only stack-allocates fixed-length types, so stack depth is bounded, too. +ifchd lightly uses malloc(), but no heap allocations have long lifetimes, and +are bounded from being large. + +Active defense of IP address and IP collision avoidance. ndhc fully implements +RFC5227. It is capable of both a normal level of tenacity in defense, where +it will eventually back off and request a new lease if a peer won't relent +in the case of a conflict, and of relentlessly defending a lease forever. In +either mode, it rate-limits defense messages, so it can't be tricked into +flooding by a hostile peer or DHCP server, either. + +Small. Both ndhc and ifchd avoid outside dependencies and are written in +plain C. + +Fast. ndhc filters input using the BPF/LPF mechanism so that uninteresting +packets are dropped by the operating system before ndhc even sees the data. +ndhc also only listens to DHCP traffic when it's necessary. + +Flexible. ndhc can request particular IPs, send user-specified client IDs, +write a file that contains the current lease IP, write PID files, etc. One +ifchd session can service multiple ndhc sessions. + +Aware of the hardware link status. If you disconnect an interface on which +ndhc is providing dhcp service, it will be aware. When the link status +returns, ndhc will fingerprint the reconnected network and make sure that it +corresponds to the one on which it has a lease. If the new network is +different, it will forget about the old lease and request a new one. + USAGE ----- @@ -153,8 +187,10 @@ be used multiple times to allow multiple interfaces. PORTING NOTES ------------- -ndhc is rather platform-dependent, and it extensively uses Linux-specific -features. Some of these features are also available on the BSDs. +DHCP clients aren't naturally very portable. It's necessary to perform a lot +of tasks that are platform-specific. ndhc is rather platform-dependent, and it +extensively uses Linux-specific features. Some of these features are also +available on the BSDs. 1) Both ndhc and ifchd use the SO_PEERCRED flag of getsockopt() to discriminate authorized connections by uid, gid, and pid. Similar functionality exists in @@ -265,5 +301,34 @@ Make sure that CONFIG_GRKERNSEC_CHROOT_CAPS is disabled. Otherwise, ifchd will lose its capabilities (in particular, the ability to reconfigure interfaces) when it chroots. +DHCP PROTOCOL QUIRKS +-------------------- +Send a packet that has an options field set to: +'DHCP-OPTION-OVERLOAD:3' +Then in the file and sname fields: +'DHCP-OPTION-OVERLOAD:3' +I suspect some bad dhcp programs will hang given this input. + +Options concatenation is a minefield of poor specification. There's a +follow-up RFC to make proper behavior somewhat more defined, but it's still +overly complex. + +DHCP explicitly specifies that there is no minimum lease time and also +specifies that the minimum default rebinding time is leasetime*0.875 and +the minimum default renewing time is leasetime*0.500. All times are relative +to the instant when the lease is bound and are specified in seconds. Taken +together, this means that a client strictly implementing the RFC should +accept a lease that either is perpetually rebinding (lease == 1s) or instantly +expires (lease == 0s). ndhc ignores the RFC and specifies a minimum lease +time of one minute. + +Renew and rebind times are optionally specified and may take on any value. +This means that a malicious server could demand a rebind time before a renew +time, or make these times ridiculously short, or specify both times past +that of the lease duration. ndhc avoids all of this nonsense by simply +ignoring these options and using the default values specified by the RFC. + +There are other quirks, but these are just several interesting ones that +immediately occur to me while I'm writing this document. diff --git a/ifchd/ChangeLog b/ifchd/ChangeLog deleted file mode 100644 index f4eecfb..0000000 --- a/ifchd/ChangeLog +++ /dev/null @@ -1,64 +0,0 @@ -20040906 - accept_conns() trivial correctness fix: EINTR return from accept should - force continue rather than break in handling loop. - - fail_on_fdne() is now file_exists() with a slightly different API. - -20040818 - Use inet_aton rather than custom function; daemon.[ch] removed. - -20040817 - ifchd no longer logs a "FATAL - select returned an error!" when it - is -KILL'ed. - -20040626 - pending_exit is now static volatile sig_atomic_t rather than - static volatile int for pedantic correctness issues. - -20040614 - Added --interface (-i) option that allows one to restrict the - interfaces that ifchd clients are allowed to modify. I - reccomend that this flag be used to further mitigate the possible - effects of a compromised client. By default, all interfaces - may be modified by clients. - Minor cleanups. - Clear corresponding namesvrs and domains on socket disconnection. - -20040613 - Factor out Linux-specific code into linux.c. - Nameservers and search domains now tracked per-connection to - prevent races where a client could force a writeout of data - provided by another client. - Interface name now cleared on connection close. - Make all headers idempotent. - Minor improvements to error messages. - -20040612 - Removed iffd[] array; this change makes the state machine action - functions (perform_*) depend on less external state. - - HOSTNAME command now supported; it is not enabled by default. - If you wish for remote daemons to be able to change the hostname - of the local machine, use the --hostname (-o) option. - -20040610 - Added MTU support. - -20040609 - Robustify so that suicide() isn't called at every possible failure. - Harmless failures will now simply print an error to the log. Risky - or severe errors still suicide(). - -20040608 - - Added support for resolv.conf, namely "nameserver" and "search" entries. - Make strlist more robust and paranoid. - -20040607 - - Improved accept() code to be much more robust; it can now properly error - recover. I hope this will fix the elusive random-exit problem that - plagues machines running the 2.6 kernel. - - Refactored dispatch_work() to be cleaner. - diff --git a/ifchd/ifchd.8 b/ifchd/ifchd.8 new file mode 100644 index 0000000..1653f9b --- /dev/null +++ b/ifchd/ifchd.8 @@ -0,0 +1,91 @@ +.TH IFCHD 8 2011-07-12 Linux "Linux Administrator's Manual" +.SH NAME +ifchd \- interface change daemon +.SH SYNOPSIS +.B ifchd +.RI [ OPTION ]... +.SH DESCRIPTION +The ifchd daemon changes network interface configuration information +(such as the IP address, broadcast address, subnet, etc) as well as +resolv.conf, the machine hostname, and other similar system configuration +bits on the request of authorized clients such as ndhc instances. +.SH OPTIONS +.TP +.BR \-d ,\ \-\-detach +Immediately fork into the background. This is the default behavior. +.TP +.BR \-n ,\ \-\-nodetach +Do not fork into the background. Useful for debugging or initial setup. +.TP +.BR \-q ,\ \-\-quiet +Don't print to standard out, standard error, or syslog. +.TP +.BI \-c\ CHROOTDIR ,\ \-\-chroot= CHROOTDIR +This option specifies the directory to which ifchd should confine itself via +chroot() after startup. This directory should be shared with associated ndhc +daemons, and should have access to dev/urandom and dev/null. For logging to +work, a dev/log socket or device should also exist. +.TP +.BI \-r\ RESOLVCONF ,\ \-\-resolve= RESOLVCONF +Specifies the path to the system resolv.conf. This file will typically be in +/etc/resolv.conf. If this option is specified, ndhc will update the contents +of this file to match the DNS servers specified by the remote DHCP server. If +this option is not specified, ifchd will never change the system DNS resolution +configuration. +.TP +.BR \-o ,\ \-\-hostname +If specified, ifchd will update the system host name in response to any +hostname option field provided by a remote DHCP server on the request of +a ndhc client. If this option is not specified, ifchd will never change +the system hostname. +.TP +.BI \-p\ PIDFILE ,\ \-\-pidfile= PIDFILE +Write the process id number of the ifchd instance into the specified file name. +The default is to not write the process id number into any file at all. +.TP +.BI \-u\ USER ,\ \-\-user= USER +This option specifies the user name or user id that ifchd will change to after +startup. This user should be unique to the ifchd daemon. +.TP +.BI \-g\ GROUP ,\ \-\-group= GROUP +This option specifies the group name or group id that ifchd will change to +after startup. +.TP +.BI \-U\ CLIENTUSER ,\ \-\-cuser= CLIENTUSER +This option specifies the user name or user id that will be required of +processes that wish to make interface change requests of ifchd. Any other +users will be denied a connection to the ifchange socket. +.TP +.BI \-G\ CLIENTGROUP ,\ \-\-cgroup= CLIENTGROUP +This option specifies the group name or group id that will be required of +processes that wish to make interface change requests of ifchd. Any other +groups will be denied a connection to the ifchange socket. +.TP +.BI \-P\ CLIENTPID ,\ \-\-cpid= CLIENTPID +This option specifies the process id that will be required to make interface +change requests of ifchd. Any process that has a process id that does not +equal this value will be denied a connection to the ifchange socket. +.TP +.BI \-i\ INTERFACE ,\ \-\-interface= INTERFACE +Specifies an interface by name (such as 'eth0') on which ifchd is allowed to +make configuration changes (such as IP address, subnet mask, etc). Multiple +interfaces may be whitelisted by using this switch multiple times. +.TP +.BR \-V ,\ \-\-verbose +Print detailed messages. Useful for debugging or setup. +.TP +.BR \-h ,\ \-\-help +Print basic help information and exit. +.TP +.BR \-v ,\ \-\-version +Display the ifchd version number and copyright information. +.SH SIGNALS +It is not necessary to sleep between sending signals, as signals received are +processed sequentially in the order they are received. ifchd does not +perform any unusual behavior on receipt of signals. +.SH NOTES +ifchd is rather minimal and doesn't do exotic things like change NTP server +configuration. This is intentional, since it needs to run as CAP_NET_ADMIN, +which although far less powerful than root, still gives it a fair amount +of privileged behavior. + diff --git a/ndhc/COPYING b/ndhc/COPYING deleted file mode 100644 index a43ea21..0000000 --- a/ndhc/COPYING +++ /dev/null @@ -1,339 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 675 Mass Ave, Cambridge, MA 02139, USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - Appendix: How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) 19yy - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) 19yy name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. diff --git a/ndhc/README b/ndhc/README deleted file mode 100644 index 8682251..0000000 --- a/ndhc/README +++ /dev/null @@ -1,64 +0,0 @@ -ndhc client --------------------- - -The ndhc client negotiates a lease with the DHCP server and notifies -ifchd when a leases is obtained or lost. - - -command line options -------------------- - -The command line options for the ndhc client are: - --c, --clientid=CLIENTID Client identifier --H, --hostname=HOSTNAME Client hostname --h, Alias for -H --f, --foreground Do not fork after getting lease --b, --background Fork to background if lease cannot be - immediately negotiated. --i, --interface=INTERFACE Interface to use (default: eth0) --n, --now Exit with failure if lease cannot be - immediately negotiated. --q, --quit Quit after obtaining lease --r, --request=IP IP address to request (default: none) --v, --version Display version - - -If the requested IP address cannot be obtained, the client accepts the -address that the server offers. - - -note on ndhc's random seed ---------------------------- - -ndhc will seed its random number generator (used for generating xids) -by reading /dev/urandom. If you have a lot of embedded systems on the same -network, with no entropy, you can either seed /dev/urandom by a method of -your own, or doing the following on startup: - -ifconfig eth0 > /dev/urandom - -in order to seed /dev/urandom with some data (mac address) unique to your -system. If reading /dev/urandom fails, ndhc will fall back to its old -behavior of seeding with time(0). - - -signals accepted by ndhc -------------------------- - -ndhc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state, -and SIGUSR2 will force a release of the current lease, and cause ndhc to -go into an inactive state (until it is killed, or receives a SIGUSR1). You do -not need to sleep between sending signals, as signals received are processed -sequentially in the order they are received. - -DHCP pitfalls -------------- - -Send a packet that has an options field set to: -DHCP-OPTION-OVERLOAD:3 - -Then in the file and sname fields: -DHCP-OPTION-OVERLOAD:3 - -I suspect some bad dhcp programs will hang given this input. diff --git a/ndhc/ndhc.8 b/ndhc/ndhc.8 index 18dceaf..ce2f894 100644 --- a/ndhc/ndhc.8 +++ b/ndhc/ndhc.8 @@ -1,46 +1,93 @@ -.TH NDHC 8 2004-02-25 Linux "Linux Administrator's Manual" +.TH NDHC 8 2011-07-12 Linux "Linux Administrator's Manual" .SH NAME ndhc \- secure DHCP client .SH SYNOPSIS .B ndhc .RI [ OPTION ]... .SH DESCRIPTION -The ndhc client negotiates a lease with the DHCP server and -informs ifchd of the change when it is obtained or lost. +The ndhc client negotiates a lease with the DHCP server and informs ifchd of +the change when it is obtained or lost. It also defends the assigned IP +address against hostile imposters and requests a new lease if it detects that +the interface has been connected to a new network. It requires a cooperating +ifchd server to properly perform its duties. .SH OPTIONS .TP .BI \-c\ CLIENTID ,\ \-\-clientid= CLIENTID -Send the client identifier -.IR CLIENTID . +Specifies the client identifier that will be sent to the remote server. This +can be any (reasonably sized, <64byte or so) text string, or an ethernet +MAC address in a form similar to 'aa:bb:cc:dd:ee:ff'. ndhc is smart enough +to recognize MAC addresses. ISP DHCP servers commonly check the value of this +field before providing a lease. The default value is the MAC address of +the network interface to which ndhc is bound. .TP -.BR -f ,\ \-\-foreground -Do not fork after obtaining a lease. +.BI \-h\ HOSTNAME ,\ \-\-hostname= HOSTNAME +Send the specified client hostname to the remote DHCP server. This option +should not be necessary in most instances, but may perhaps be useful for odd +DHCP servers that perform some kind of authentication against the hostname +option field. The default is to send no hostname option at all. .TP -.BI \-H\ HOSTNAME ,\ \-\-hostname= HOSTNAME -Send the client hostname -.IR HOSTNAME . +.BI \-v\ VENDORID ,\ \-\-vendorid= VENDORID +Send the specified vendor identification string to the remote DHCP server. +This option should not be necessary in most instances, but may perhaps be +useful for odd DHCP servers that perform some kind of authentication against +the vendor id option field. The default is to send the string 'ndhc'. .TP -.BI \-h\ HOSTNAME -Alias for -H -.IR HOSTNAME . +.BR \-f ,\ \-\-foreground +Do not fork into the background after obtaining a lease. +.TP +.BR \-b ,\ \-\-background +Immediately fork into the background, even before obtaining a lease. +.TP +.BI \-p\ PIDFILE ,\ \-\-pidfile= PIDFILE +Write the process id number of the ndhc instance into the specified file name. +The default is to not write the process id number into any file at all. +.TP +.BI \-l\ LEASEFILE ,\ \-\-leasefile= LEASEFILE +Write the IP address of the currently held DHCP lease into the specified file +name. The default is to not write the lease IP address into any file at all. +This file can be quite useful for reacting to changes in IP address -- one +can listen for changes to it using fanotify() or inotify() on Linux. .TP .BI \-i\ INTERFACE ,\ \-\-interface= INTERFACE -Configure -.IR INTERFACE . +Act as a DHCP client for the specified interface. A single ndhc daemon can +only act as a DHCP client for a single interface. Specify the interface it +should use by name. The default is to listen on 'eth0'. .TP -.BR -n ,\ \-\-now -Exit with failure if a lease cannot be obtained. +.BR \-n ,\ \-\-now +Exit with failure if a lease cannot be obtained. Useful for some init scripts. .TP -.BR -q ,\ \-\-quit -Exit after obtaining a lease. +.BR \-q ,\ \-\-quit +Exit after obtaining a lease. Useful for some init scripts. .TP -.BI \-r\ ADDRESS ,\ \-\-request= ADDRESS -Request IP address -.IR ADDRESS . +.BI \-r\ IP ,\ \-\-request= IP +Request the specified IP address from the remote DHCP server. The DHCP server +has no obligation to provide us with this IP, but it may acquiesce to the +request if it would not conflict with another host. .TP -.BR -v ,\ \-\-version -Display version. -.SH NOTES +.BI \-u\ USER ,\ \-\-user= USER +This option specifies the user name or user id that ndhc will change to after +startup. ndhc will also change its group to match the default group of this +user. This user should have the ability to write to the ifchd socket of the +associated ifchd daemon. In practice, this requirement means that this user +should belong to the same group as the ifchd user. +.TP +.BI \-C\ CHROOTDIR ,\ \-\-chroot= CHROOTDIR +This option specifies the directory to which ndhc should confine itself via +chroot() after startup. This directory should be shared with the associated +ifchd daemon, and should have access to dev/urandom and dev/null. For +logging to work, a dev/log socket or device should also exist. +.TP +.BR \-d ,\ \-\-relentless-defense +If specified, ndhc will never back down in defending the IP address that it +has been assigned by the remote DHCP server. This behavior should not be +specified for average machines, but is useful for servers or routers where +the IP address of the machine must remain fixed for proper operation. +.TP +.BR \-v ,\ \-\-version +Display the ndhc version number. +.SH SIGNALS +It is not necessary to sleep between sending signals, as signals received are +processed sequentially in the order they are received. .B ndhc responds to the following signals: .TP @@ -51,6 +98,18 @@ to renew the current lease or, if it does not have one, obtain a new lease. .TP .B SIGUSR2 -This signal caused +This signal causes .B ndhc -to release the current lease. +to release the current lease and go to sleep until it receives a SIGUSR1. +.SH NOTES +ndhc will seed its random number generator (used for generating xids) +by reading /dev/urandom. If you have a lot of embedded systems on the same +network, with no entropy, you can either seed /dev/urandom by a method of +your own, or doing the following on startup: + +ifconfig eth0 > /dev/urandom + +in order to seed /dev/urandom with some data (mac address) unique to your +system. If reading /dev/urandom fails, ndhc will fall back to seeding with +time(0). + diff --git a/ndhc/ndhc.c b/ndhc/ndhc.c index 7e1b0c0..7f7d6f7 100644 --- a/ndhc/ndhc.c +++ b/ndhc/ndhc.c @@ -79,6 +79,8 @@ struct client_config_t client_config = { static void show_usage(void) { printf( +"ndhc " VERSION ", dhcp client. Licensed under GNU GPL.\n" +"Copyright (C) 2004-2011 Nicholas J. Kain\n" "Usage: ndhc [OPTIONS]\n\n" " -c, --clientid=CLIENTID Client identifier\n" " -h, --hostname=HOSTNAME Client hostname\n" @@ -312,7 +314,12 @@ int main(int argc, char **argv) arp_relentless_def = 1; break; case 'v': - printf("ndhc, version " VERSION "\n\n"); + printf( +"ndhc %s, dhcp client. Licensed under GNU GPL.\n", VERSION); + printf( +"Copyright (C) 2004-2011 Nicholas J. Kain\n" +"This is free software; see the source for copying conditions. There is NO\n" +"WARRANTY; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n"); exit(EXIT_SUCCESS); break; case 'V':