Zugschlus' interface scripts for ifupdown's manual method
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This package contains a set of scripts that are called by ifupdown.
They use ifupdown's manual method. Compared to ifupdown's static
method, the scripts contained in this package have the following
advantages:
 - CIDR support
 - ATM support
 - support for 802.1q VLAN tagging
 - search-and-rename ethernet interfaces according to their MAC
   address
 - built-in handling of static routes
Additionally, the code needed to bring down an interface is generated
on the fly when the interface is brought up. That way,
/etc/network/interfaces changes made while the interface is up don't
prevent it from being taken down, allowing "ifdown foo; ifup foo" to
activate the changes.

This package is work in progress. Although being in productive use,
it is still missing some features, especially regarding source
routing, metrics etc. Please feel free to provide patches, especially
if they improve the documentation.


Options accepted in an "iface foo inet manual" interface stanza
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Option name: accept-redirects
Type: boolean
Default: Keep system-wide setting
Example: accept-redirects 0
If set to 1, the interface accepts redirects.
Used by: redirects

Option name: address
Type: IP/Prefix
Default: none, option is mandatory
Example: address 127.0.0.1/8
IP address to be given to the interface
Used by: address

Option name: atmarp_$suffix
Type: IP VCI
Default: none
Example: atmarp_otherside 192.168.0.1 0/0/4
Insert the given pair of IP and VCI into the ATM ARP table. VCI is
given in the usual card/VPI/VCI format. Order does not matter, but the
suffixes need to be different on all atmarp lines.
Used by: atmarp

Option name: brd
Type: IP Address or "all0" or "all1" or "none"
Default: all1
Example: brd 192.168.0.255
Broadcast address to be given to the Interface. all0 and all1 do the
obvious, "none" disables broadcasts.
Used by: address

Option name: device
Type: Device Name
Default: none, option is mandatory
Example: device eth0
Gives the physical device name for the interface.
If a "mac" option is present, the interface with the given MAC address
  is looked up and renamed to the string given. If that device is
  already up or the MAC address is not found, an error is forced.
If no MAC address is given, we take the interface of this name.
For a VLAN interface, the newly created interface is named after this
  option as well.
If a route option does not give a gateway IP or a target device, the
  device of the interface is taken as a last resort.
Used by: address atm-interfacename common-functions eth-interfacename
         lo-linkup redirects staticroutes vlan

Option name: encapsulation
Type: dot1q
Default: none
Example: encapsulation dot1q
Give the encapsulation type for VLAN interfaces. Currently, dot1q is
the only value supported.
Used by: vlan

Option name: flags
Type: list of strings
Default: none
Example: flags secondary
Give a flag to an interface. The flag names are written to the state
  file and can be retrieved from there by other programs.
The flag "secondary" is evaluated by address. A secondary IP address
  must be designated as such by this flag. Otherwise, the interface
  won't be initialized. This is a precaution against wrong
  initialization and deinitialization order.
Used by: address flags

Option name: mac
Type: MAC address
Default: none
Example: mac 00:0c:6e:68:f2:2e
If given, the code that is used to identify a physical interface
searches for an interface with the given MAC address.
If found, the interface is appropriately renamed and used
If not found, an error is forced.
If found, but already active with a different name, an error is forced.
Used by: eth-interfacename vlan

Option name: master
Type: Device Name
Default: none
Example: master eth0
Identfy Master interface for VLAN interface. Can be used instead of
MAC option.
Used by: eth-interfacename vlan

Option name: route_$suffix
Type: route_foo prefix gateway/device metric/table
  or: route_foo ip route <cmd line> and
Default: none
Example: route_default default 192.168.0.1
         route_special ip route 127.0.0.1/8 dev lo
If the string after "route_foo" in the config file does not
start with "ip route", the following words are interpreted:
 prefix         - prefix for the route, used as "to" parameter.
 gateway/device - if IP address, gateway for the route,
                                 used as "via" parameter,
                  otherwise,     device for the route,
                                 used as "dev" parameter.
 metric/table   - if numeric,    metric for the route,
                                 used as "metric" parameter.
                  otherwise,     table for the route,
                                 used as "route" parameter.
From these values, appropriate "ip route" command lines are
constructed for interface startup and shutdown. This should cover
almost all non-exotic cases. For the exotic cases, you can start the
string after "route_foo" with "ip route". The remainder of the string
is taken as a full ip route command line which will be appended to
"ip route add" on interface startup and to "ip route del" on interface
shutdown.
Order does not matter, but the suffixes need to be different on all
route lines.
Used by:staticroutes

Option name: scope
Type: IP address scope
Default: none, take default from system
Example: scope host
Set the scope where the IP address will be valid.
Used by:address

Option name: scr{up|dn}_$suffix
Type: command
Default: none
Example: see description
This options allow to write special commands in
/etc/network/interfaces to accomplish things that nobody has thought
of while developing these scripts.
This is similar to ifupdown's built-in up/down command, but allows
the special commands to be issued in the middle of our scripts instead of
before the first or after the last script. Additionally, we do some
magic on the values, and save the "down" commands to the state file. This
way, changes made to /e/n/i while the interface is up are not immediately
valid.
If the first parameter for a IF_SCRUP line begins with a single
quote ', everything until the second single quote ' is treated as a sed
expression to modify the command to be executed on iface down.
 - scrup1 ':' echo comment   - will execute the echo command unchanged on
                               iface up and iface down
 - scrup1 echo comment       - will execute the echo command on iface up only
 - scrup1 's/add /del /' ip addr add dev eth0 127.0.0.1/8
                             - will execute "ip addr add dev..." on iface up
                               and "ip addr del dev..." on iface down
 - scrdn1 ip link set dev eth0 down
                             - will execute the ip command on iface down only
The suffixes need to be different on all scr{up|dn} lines, and
commands are executed in alphabetically sorted order for scrup, and
alphabetically sorted, but reversed order for scrdn.
Used by:specialcommands

Option name: send-redirects
Type: boolean
Default: Keep system-wide setting
Example: send-redirects 0
If set to 1, the interface issues redirects if necessary.
Used by:redirects

Option name: type
Type: atm, eth, loopback
Default: eth
Example: type atm
Sets the type of interface if that cannot be deduced from other
options that might only apply to certain kinds of interface.
Used by:atm-interfacename atmarp eth-interfacename lo-linkup

Option name: verbose
Type: Boolean
Default: 0
Example: verbose 1
Makes the scripts more verbose on execution for debugging.
Used by:common-functions

Option name: vlan-id
Type: Numeric
Default: none
Example: vlan-id 5
Sets the dot1q VLAN ID for a VLAN interface.
Used by:eth-interfacename vlan

-- Marc Haber <mh+debian-packages@zugschlus.de> 2003-09-17

The first version of this text was written while cruising the Canal du Midi