source: trunk/third/ifplugd/doc/README.html @ 20388

Revision 20388, 16.2 KB checked in by amb, 20 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r20387, which included commits to RCS files with non-trunk default branches.
Line 
1<?xml version="1.0" encoding="iso-8859-1"?> <!-- -*-html-helper-*- -->
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml">
4
5<head>
6<title>ifplugd 0.23</title>
7<link rel="stylesheet" type="text/css" href="style.css" />
8</head>
9
10<body>
11<h1><a name="top">ifplugd 0.23</a></h1>
12
13<p><i>Copyright 2002-2004 Lennart Poettering &lt;mzvscyhtq (at) 0pointer (dot) de&gt;</i></p>
14
15<ul class="toc">
16    <li><a href="#license">License</a></li>
17    <li><a href="#news">News</a></li>
18    <li><a href="#overview">Overview</a></li>
19    <li><a href="#status">Status</a></li>
20    <li><a href="#documentation">Documentation</a></li>
21    <li><a href="#requirements">Requirements</a></li>
22    <li><a href="#installation">Installation</a></li>
23    <li><a href="#acks">Acknowledgements</a></li>
24    <li><a href="#download">Download</a></li>
25</ul>
26
27<h2><a name="license">License</a></h2>
28
29<p>This program is free software; you can redistribute it and/or
30modify it under the terms of the GNU General Public License as
31published by the Free Software Foundation; either version 2 of the
32License, or (at your option) any later version.</p>
33
34<p>This program is distributed in the hope that it will be useful, but
35WITHOUT ANY WARRANTY; without even the implied warranty of
36MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
37General Public License for more details.</p>
38
39<p>You should have received a copy of the GNU General Public License
40along with this program; if not, write to the Free Software
41Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</p>
42
43<h2><a name="news">News</a></h2>
44
45<div class="news-date">Wed Apr 7 2004: </div> <p class="news-text"><a
46href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.23.tar.gz">Version
470.23</a> released, changes include: don't make <tt>/dev/tty1</tt> the controlling TTY when beeping</p>
48
49<div class="news-date">Tue Feb 10 2004: </div> <p class="news-text"><a
50href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.22.tar.gz">Version
510.22</a> released, changes include: rename <tt>ifstatus</tt> to <tt>ifplugstatus</tt> due to namespace collision, minor fixes</p>
52
53<div class="news-date">Mon Jan 26 2004: </div> <p class="news-text"><a
54href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.21b.tar.gz">Version
550.21b</a> released, added missing file.</p>
56
57<div class="news-date">Mon Jan 26 2004: </div> <p class="news-text"><a
58href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.21.tar.gz">Version
590.21</a> released, changes include: better compatibility with wireless devices, compatibility with newer kernels</p>
60
61<div class="news-date">Sun Nov 9 2003: </div> <p class="news-text"><a
62href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.20.tar.gz">Version
630.20</a> released, changes include: fix wrong message, build fix</p>
64
65<div class="news-date">Mon Oct 20 2003: </div> <p class="news-text"><a
66href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.19.tar.gz">Version
670.19</a> released, changes include: New option <tt>--wait-for-kill</tt>, this requires <a href="http://0pointer.de/lennart/projects/libdaemon/"><tt>libdaemon 0.3</tt></a></p>
68
69<div class="news-date">Fri Oct 17 2003: </div> <p class="news-text"><a
70href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.18.tar.gz">Version
710.18</a> released, changes include: Some bugs fixed</p>
72
73<div class="news-date">Fri Sep 13 2003: </div> <p class="news-text"><a
74href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.17b.tar.gz">Version
750.17b</a> released, changes include: typo and date fix</p>
76
77<div class="news-date">Fri Sep 13 2003: </div> <p class="news-text"><a
78href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.17.tar.gz">Version
790.17</a> released, changes include: documentation update, better support for multiple interfaces, gcc 2.95 build fix</p>
80
81<div class="news-date">Thu Aug 13 2003: </div> <p class="news-text"><a
82href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.16.tar.gz">Version
830.16</a> released, changes include: RPM spec file added, build fixes, WLAN improvements (including compatibility with the upcoming <tt>waproamd</tt>, a WLAN roaming daemon), monitor mode for use in conjunction with PCMCIA devices, better support for multiple interface setups, <tt>SUPPORTED_DRIVERS</tt> returns</p>
84
85<div class="news-date">Thu July 10 2003: </div> <p class="news-text"><a
86href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.15.tar.gz">Version
870.15</a> released, changes include: bad umask fix, documentation update</p>
88
89<div class="news-date">Mon July 7 2003: </div> <p class="news-text"><a
90href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.14.tar.gz">Version
910.14</a> released, changes include: autoconf usage, new dependency <a
92href="http://0pointer.de/lennart/projects/libdaemon/"><tt>libdaemon</tt></a>, wireless LAN support, support for
93suspending/resuming, many fixes</p>
94
95<h2><a name="overview">Overview</a></h2>
96
97<p><tt>ifplugd</tt> is a Linux daemon which will automatically
98configure your ethernet device when a cable is plugged in and
99automatically unconfigure it if the cable is pulled. This is useful on
100laptops with onboard network adapters, since it will only configure
101the interface when a cable is really connected.</p>
102
103<p><tt>ifplugd</tt> ifplugd interfaces with your distribution's native network
104  configuration utilities.</p>
105
106<p>Some features:</p>
107
108<ul>
109  <li>Uses your distribution's native <tt>ifup</tt>/<tt>ifdown</tt> programs.</li>
110
111  <li>May beep when the cable is unplugged, plugged, the interface
112  configuration succeeded or failed.</li>
113
114  <li>Supports the Linux <tt>SIOCETHTOOL</tt> (newer, aka <tt>ethtool</tt> API), <tt>SIOCGMIIREG</tt>
115  (older, aka <tt>mii-diag</tt>/<tt>mii-tool</tt> API) and SIOCDEVPRIVATE (oldest, aka
116  <tt>mii-tool</tt> API) <tt>ioctl()</tt>s for getting link status.</li>
117
118  <li>Syslog support</li>
119
120  <li>Small program - the binary is just 19 KB (plus 11 KB for <tt>libdaemon</tt>).</li>
121 
122  <li>Multiple ethernet interface support</li>
123
124  <li>Can be configured to ignore short "unplugged" periods
125  (-d option) or short "plugged" periods(<tt>-u</tt>
126  option)</li>
127
128  <li>Support for wireless networking. Whenever an association to an
129AP is detected the network is configured. Have a look on <a
130href="http://0pointer.de/lennart/projects/waproamd/"><tt>waproamd</tt></a>
131if you need a facility to configure WEP keys before AP associations succeed.</li>
132
133  <li>Compatibility mode for network devices which do not support cable detection (<tt>-F</tt> option)</li>
134</ul>
135 
136<h2><a name="status">Status</a></h2>
137
138<p>Version 0.23 is stable and has all the sensible features its users could think of.</p>
139 
140<h2><a name="documentation">Documentation</a></h2>
141
142<p>Have a look on the man pages <a href="http://0pointer.de/lennart/projects/ifplugd/ifplugd.8.xml"><tt>ifplugd(8)</tt></a>, <a href="http://0pointer.de/lennart/projects/ifplugd/ifplugstatus.8.xml"><tt>ifplugstatus(8)</tt></a>, <a href="http://0pointer.de/lennart/projects/ifplugd/ifplugd.conf.5.xml"><tt>ifplugd.conf(5)</tt></a>. (An XSLT capable browser is required)</p>
143
144<h3>Configuration</h3>
145
146<p>Edit <tt>/etc/ifplugd/ifplugd.conf</tt> for configuration
147changes. This file is a bourne shell script sourced by the init script
148and used to start <tt>ifplugd</tt> with appropriate arguments. You may specify more than
149one ethernet interface in <tt>INTERFACES</tt>. For each interface a
150seperate instance of <tt>ifplugd</tt> is spawned. The arguments specified in
151<tt>ARGS</tt> are append to <tt>ifplugd</tt>'s command line. Have a look on
152<tt>ifplugd -h</tt> or <tt>man ifplugd</tt> for further information
153about the available options.</p>
154
155<p>The network interface which is controlled by <tt>ifplugd</tt>
156should not be configured automatically by your distribution's network
157subsystem, since <tt>ifplugd</tt> will do this for you if needed.</p>
158
159<p>On Debian systems, any interfaces named in ifplugd's
160<tt>INTERFACES</tt> environment variable should not also be listed in
161an "auto" stanza in <tt>/etc/network/interfaces</tt>.</p>
162
163<h3>Troubleshooting</h3>
164
165<p>When you are using the hotplug subsystem (Debian package
166<tt>hotplug</tt>) you may notice that the network device is configured
167even when it is not listed on an <tt>auto</tt> line in
168<tt>/etc/network/interface</tt>. This may be due to <tt>hotplug</tt>
169being configured to <tt>ifup</tt> the network interface when it
170becomes available.  This was the default behavior in the Debian
171<tt>hotplug</tt> package prior to release <tt>0.0.20030117-1</tt>, for
172example.  To prevent this you should either upgrade your
173<tt>hotplug</tt> package or comment out the <tt>ifup</tt> call in
174<tt>/etc/hotplug/net.agent</tt>.</p>
175
176<p>When using <tt>ifplugd</tt> together with APM (and probably ACPI)
177suspends, strange things may happen: some network devices fail to
178detect the network cable for a short period of time before and after
179the suspend. When using the <tt>-f</tt> switch, this will be treated
180as "no link beat", thus the network is shutdown after a
181timeout. During this timeout the machine changes to suspended
182state. When it is resumed again, the timeout period will have expired
183and so the network is deconfigured, however, as the next cable
184detection succeeds, the network is configured again immediately. To
185fix this problem, <tt>ifplugd</tt> should be disabled before the APM
186suspend and enabled back after the suspend. This may be done by using
187<tt>apmd</tt> and adding a script to
188<tt>/etc/apm/{suspend,resume}.d</tt> which simply calls
189<tt>/etc/init.d/ifplugd suspend</tt>, resp. <tt>/etc/init.d/ifplugd
190resume</tt>. It might even be a good idea to shut down the network
191completely during suspend, this may be achieved by calling
192<tt>/etc/init.d/ifplugd stop</tt> and <tt>/etc/init.d/ifplugd
193start</tt> in the appropriate places. I strongly urge the packagers of
194this software for the Linux distributions to add such scripts to their
195packages.</p>
196
197<h3>FAQ</h3>
198
199<ol>
200  <li><p><b>Q:</b> I want to use <tt>ifplugd</tt> with my PCMCIA device, but <tt>ifplugd</tt> quits
201  when it doesn't find <tt>eth0</tt>, when I have not inserted the
202  card. What can I do?</p>
203 
204  <p><b>A:</b> Use the <tt>-f</tt> switch. This is not very clean however,
205  since modprobe is called on each cable detection query of <tt>ifplugd</tt> to
206  load a module for the network device. This is suboptimal. You should
207  probably run <tt>ifplugd</tt> only when the card is really inserted.</p>
208  </li>
209 
210  <li><p><b>Q:</b> I am using the <tt>-f</tt> switch, but the kernel logs are getting filled
211  with messages like "<tt>modprobe: modprobe: Can't locate module
212  eth0</tt>". What can I do?</p>
213 
214  <p><b>A:</b> Make sure you have a line like <tt>alias eth0 off</tt> in your <tt>/etc/modules.conf</tt></p>
215  </li>
216 
217  <li><p><b>Q:</b> When the cable is unplugged and the interface shut down it is
218  still available with <tt>ifconfig</tt> and markes as UP. Why this?</p>
219
220  <p><b>A:</b> <tt>ifplugd</tt> cannot detect the link beat with a shut down interface on
221  certain (most as of kernel 2.4.19) network drivers. Thus <tt>ifplugd</tt>
222  enables the interface before querying the link status. This may
223  be switched off with -a flag. You might want to use it if you
224  have a sane network driver (e.g. <tt>eepro100</tt>). The subdirectory
225  <tt>patches/</tt> in the <tt>ifplugd</tt> distribution includes a patch for the
226  8139too 0.9.26 driver, which makes the driver compatible with
227  -a. Don't ask me how to apply this patch. If you don't know, you
228  won't need it.</p></li>
229
230  <li><p><b>Q:</b> Does it work with anything else than plain ethernet or wireless LAN?</p>
231
232  <p><b>A:</b> Certainly not, since the <tt>MII</tt> and
233<tt>ETHTOOL</tt> <tt>ioctl()</tt>s and the wireless extension don't
234exist on
235  other network device types.</p></li>
236 
237  <li><p><b>Q:</b> I have a Realtek 8139 based network card. Everytime <tt>ifplugd</tt>
238  starts on bootup my machine freezes. What can I do?</p>
239 
240  <p><b>A:</b> This is a bug in the <tt>8139too</tt> driver 0.9.25 (at least) shipped
241  with Linux 2.4.19, please upgrade to <tt>8139too</tt> 0.9.26 (Linux 2.4.20
242  or seperately at <a href="http://www.sourceforge.net/projects/gkernel/">http://www.sourceforge.net/projects/gkernel/</a>).</p></li>
243 
244 
245  <li><p><b>Q:</b> There are already <tt>laptop-net</tt>'s <tt>ifd</tt> and <tt>miid</tt>, why did you write
246  your own daemon?</p>
247
248  <p><b>A:</b> <tt>laptop-net</tt> was too integrated with its profile
249system and didn't work on my hardware when I had a look on it. It
250seemed easier to me to write a simple but feature complete replacement
251than using laptop-net without most of the special features disabled. I
252didn't know about <tt>miid</tt> when I wrote
253  <tt>ifplugd</tt>, but in any case <tt>ifplugd</tt> is much better
254than <tt>miid</tt>. For a
255     comparison of <tt>miid</tt> and <tt>ifplugd</tt>, have a look on
256
257  <a href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=162763&amp;repeatmerged=yes">http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=162763&amp;repeatmerged=yes</a></p></li>
258</ol>
259
260
261<h2><a name="requirements">Requirements</a></h2>
262
263<p>A newer Linux Kernel (I think 2.2 is good enough, alltough I tested it
264only with 2.4) with a compatible device driver and
265ethernet card. Most modern cards and drivers are compatible, like mine
266which works with the <tt>8139too</tt> driver.</p>
267
268<p><tt>ifplugd</tt> was developed and tested on Debian GNU/Linux
269"testing" from July 2003, it should work on most other Linux
270distributions (and maybe Unix versions) since it uses GNU autoconf and
271GNU libtool for source code configuration and shared library
272management.</p>
273
274<p>The machine used was a Medion 9580-F laptop with a Realtek 8139
275network card and a PRISM1 PCMCIA wireless LAN card.</p>
276
277<p><tt>ifplugd</tt> needs <a
278href="http://0pointer.de/lennart/projects/libdaemon/"><tt>libdaemon</tt></a>.</p>
279 
280<h2><a name="installation">Installation</a></h2>
281
282<p>As this package is made with the GNU autotools you should run
283<tt>./configure</tt> inside the distribution directory for configuring
284the source tree. After that you should run <tt>make</tt> for
285compilation and <tt>make install</tt> (as root) for installation of
286<tt>ifplugd</tt>.</p>
287
288<p>The installation scripts create an init script in
289<tt>${sysconfdir}/init.d/ifplugd</tt>, however no <tt>/etc/rc?.d/</tt> links are created
290for it.</p>
291
292<p>Extensive installation instructions for <tt>ifplugd</tt> are available at <a href="http://www.acmc.uq.edu.au/~gbe/linux/installation_of_ifplugd.html">Geoff Ericksson's web site</a>.</p>
293
294<h2><a name="acks">Acknowledgements</a></h2>
295
296<p>For the developers of <tt>mii-diag</tt>, <tt>ethtool</tt> and <tt>laptop-net</tt>, since I looked
297on their source codes for learning how to use the link beat ioctls.</p>
298
299<p>Oliver Kurth for packaging <tt>ifplugd</tt> for Debian and <tt>ifplugd</tt>'s
300manpage</p>
301
302<p>Thomas Hood, Asgeir Nilsen, Sean Reifschneider, R. Steve McKown, David Mitchell, Norbert Preining, Herbert Graeber for patches</p>
303
304<p>Frederic Lepied for integrating <tt>ifplugd</tt> into Mandrake Linux</p>
305
306<h2><a name="download">Download</a></h2>
307
308<p>The newest release is always available from <a href="http://0pointer.de/lennart/projects/ifplugd/">http://0pointer.de/lennart/projects/ifplugd/</a></p>
309
310<p>The current release is <a href="http://0pointer.de/lennart/projects/ifplugd/ifplugd-0.23.tar.gz">0.23</a></p>
311
312<p>Get <tt>ifplugd</tt>'s development sources from the <a href="http://subversion.tigris.org/">Subversion</a> <a href="https://seth.intheinter.net:8081/svn/ifplugd/">repository</a>.</p>
313
314<p>You may find an up to date Debian package of <tt>ifplugd</tt> on the <a href="http://packages.debian.org/ifplugd">Debian package repository</a>.</p>
315
316<p>Packages for Mandrake Linux may be found in the Cooker distribution; Gentoo packages are available as well; <a href="http://packman.links2linux.de/">SuSE packages</a> are available courtesy of Herbert Graeber.</p>
317
318<p>If you want to be notified whenever I release a new version of this software use the subscription feature of <a href="http://freshmeat.net/projects/ifplugd/">Freshmeat</a>.</p>
319
320<p><b>New!</b> There is a joint <tt>ifplugd</tt> and <tt>waproamd</tt> <a href="https://seth.intheinter.net/mailman/listinfo/ifplugd-discuss">mailing list</a> available.</p>
321
322<hr/>
323<address class="grey">Lennart Poettering &lt;mzvscyhtq (at) 0pointer (dot) de&gt;, April 2004</address>
324<div class="grey"><i>$Id: README.html,v 1.1.1.1 2004-04-09 20:09:21 amb Exp $</i></div>
325
326</body>
327</html>
Note: See TracBrowser for help on using the repository browser.