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:
 - Support for IPv4 and IPv6
 - 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
         address 2001:db8::100:100/64
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.
This has not been tested in a very long time
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. Applies for IPv4 only.
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 used if the device name is correct. Use udev's
  persistent-net feature to associate MAC and interface name; this
  option is just an additional safetc. If the device is
  already up or the MAC address is not found, an error is forced.
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: force-ipv6-rd
Type: boolean
Default: 0
Example: force-ipv6-rd 1
Explicitly send out an IPv6 router discovery packet on interface
  initialzation and wait for the answer. This makes sure that we have
  learned SLAAC IPv6 addresses before we continue.
Used by: address

Option name: label
Type: boolean
Default: 1
Example: label 0
In the default behavior, the scripts put a label ("$IF_DEVICE:$IFACE")
  on an interface if the logical device name differs from the physical
  one. This is done to make it clear which physical interface a logical
  one depends on.
Unfortunately, this makes numerous DHCP-related packages break in
  various ways (refer to #617258, #617264). To still allow DHCP to work,
  use label 0 to cause the scripts to omit the label.
Used by: address

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 used. Former versions of
  ifupdown-scripts-zg2 used to rename the interface to the wanted name.
  This is no longer done. Use udev's persistent-net feature to establish
  the association between interface name and MAC address.
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
Identify Master interface for VLAN interface. Can be used instead of
  MAC option.
Used by: eth-interfacename vlan

Option name: preflft
Type: numeric
Default: do not set
Example: preflft 0
Set preferred lifetime for IP address to n seconds. 0 means that the
  address is deprecated immediately.
Used by: address

Option name: proxy-arp
Type: boolean
Default: Keep system-wide setting
Example: proxy-arp 1
If set to 1, Proxy-ARP will be enabled for the interface: Address
  Resolution Protocol request packets for non-local addresses will then
  be answered by this interface, provided that received packets to the
  specified address would not be routed through it. See the Linux
  Advanced Routing & Traffic Control HOWTO for possible scenarios where
  this may be useful. 
Used by: proxy-arp

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
	 route_default default fe80::1%eth0
	 route_v6 2001:db8:4350:6101::/64 2a01:db8:4071:321d::1
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 (for IPv6,
				    the gateway string can contain a
				    %iface suffix)
                     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.
    - scrup_1 ':' echo comment   - will execute the echo command unchanged on
                                   iface up and iface down
    - scrup_1 echo comment       - will execute the echo command on iface up only
    - scrup_1 '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
    - scrdn_1 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: wait-tentative
Type: boolean
Default: 1
Example: wait-tentative 1
Wait up to 30 seconds for all IP addresses on an interface to leave
tentative state
Used by: address

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> 2012-06-28
