ifplugd 0.13 - Ethernet Plugging Daemon
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Copyright 2002,2003
Lennart Poettering <mz6966706c756764@itaparica.org>

---------------------------------------------------------------------

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.

---------------------------------------------------------------------

ifplugd is a Linux daemon which will automatically configure your
ethernet device when a cable is plugged in and automatically
unconfigure it if the cable is pulled. This is useful on laptops with
onboard network adapters, since it will only configure the interface
when a cable is really connected.

ifplugd is a rather simplistic approach to this target since it relies
on your distribution's native interface configuration system.

Features
--------

- Uses your distribution's native ifup/ifdown programs.

- May beep when the cable is unplugged, plugged, the interface
  configuration succeeded or failed.

- Supports the Linux SIOCETHTOOL (newer, aka ethtool API), SIOCGMIIREG
  (older, aka mii-diag/mii-tool API) and SIOCDEVPRIVATE (oldest, aka
  mii-tool API) ioctl()s for getting link status.

- Syslog support

- Works even with PCMCIA devices, where the interface is not available
  when no card is inserted. (-f option)

- Simplistic C source code, just 16k binary

- Multiple ethernet interface support

- May ignore short unplugged whiles (-d option) or plugged whiles (-u
  option).

Requirements
------------

A newer Linux Kernel (I think 2.2 is good enough, alltough I tested it
only with 2.4) with a MII/ethtool compatible device driver and
ethernet card. Most modern cards and drivers are compatible, like mine
which works with the 8139too driver.

You'll need a working GCC configuration for compiling ifplugd.

Installation
------------

Just run "make" in ifplugd's directory. This will compile the
sources. A call to "make install" (as root) will install the binary to
/usr/local/sbin, create the ifplugd configuration directory in
/etc/ifplugd and create a SysV-compatible init script in
/etc/init.d/ifplugd. However, it won't create the necessary links to
/etc/rc?.d/ for you, that make sure ifplugd is getting started on
system bootup. The supplied default configuration works fine with
Debian GNU/Linux 3.0, you might need to tweak it a bit on other
distributions.

You may use "make deinstall" for removing all files created by ifplugd.

Configuration
-------------

Edit /etc/ifplugd/ifplugd.conf for configuration changes. This file is
a bourne shell script sourced by the init script and used to generate
a suiting command line. You may specify more than one ethernet
interface in INTERFACES. For each interface a seperate instance of
ifplugd is spawned. The arguments specified in ARGS are append to
ifplugd's command line. Have a look on ifplug -h for further
information about the available options.

The network interface which is controlled by ifplugd should not be
configured automatically by your distribution's network subsystem,
since ifplugd will do this for you if needed. On Debian remove "auto
eth0" from /etc/network/interfaces.

When you are using the hotplug subsystem (Debian package hotplug) you
may notice that the network device is configured even when when "auto
eth0" is removed from /etc/network/interface. The hotplug subsystem
automatically calls ifup for all network interfaces which come
available. Thus it will try to configure the network interfaces
immediately after you called "modprobe 8139too", as an example. This
interferes somewhat with ifplugd. Thus you need to deactivate this
behaviour by inserting an "exit 0" in /etc/hotplug/net.agent at the
appropriate place.

When ifplugd is started and a cable is already plugged in, the network
interface is configured immediately. When ifplugd is shut down an the
network interface is configured it will be deconfigured immediately.


Development
-----------

Development was done under Debian GNU/Linux 3.0. The used machine was
a Medion 9580-F laptop with a Realtek 8139 network card.

Internet
--------

You may find up to date releases of this utility on
        http://www.stud.uni-hamburg.de/users/lennart/projects/ifplugd/

Have a look on the NEWS file for ifplugd:
        http://www.stud.uni-hamburg.de/users/lennart/projects/ifplugd/NEWS

You may download this release from
        http://www.stud.uni-hamburg.de/users/lennart/projects/ifplugd/ifplugd-0.13.tar.gz

You may find a mostly up to date Debian package of ifplugd on
        http://packages.debian.org/cgi-bin/search_packages.pl?keywords=ifplugd&searchon=names&subword=1&version=all&release=all

Packages for Mandrake Linux may be found in the Cooker distribution

Thanks
------

For the developers of mii-diag, ethtool and laptop-net, since I looked
on their source codes for learning how to use the link beat ioctls.

Oliver Kurth for packaging ifplugd for Debian and ifplugd's
manpage

Asgeir Nilsen, Sean Reifschneider, R. Steve McKown for patches

Frederic Lepied for integrating ifplugd into Mandrake Linux

Lennart Poettering <mz6966706c756764@itaparica.org>, January 2003

$Id: README.in 1.6 Sat, 01 Feb 2003 02:36:25 +0100 lennart $
