/etc/net version 0.7.14
http://etcnet.org/

Copyright (c) 2004-2005 Denis Ovsienko (info#pilot_org_ua)
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.

1. GENERAL INFORMATION

Supported interface types:
+ethernet (eth)
+WiFi
+IP tunnels (iptun)
+IPSec static tunnels (ipsectun)
+VLANs (vlan)
+PLIP (plip)
+bonding (bond)
+bridge
+traffic equalizers (teql)
+/-dummy
+DVB: Pent@NET, Pent@VALUE, SkyStar-2
+usbnet
+PPP (see below for PPtP, PPPoE)

Supported protocols:
IPv4 (static, DHCP, IPv4LL)
IPv6 (static)
IPX

Extra features: QoS, sysctl, firewall.

2. QUICK START
# mkdir /etc/net/ifaces/myinterface1
$ less /etc/net/ifaces/default/options
$ less /etc/net/ifaces/default/options-*
# vi /etc/net/ifaces/myinterface1/options
# vi /etc/net/ifaces/myinterface1/ipv4address
# vi /etc/net/ifaces/myinterface1/ipv4route
...
# mkdir /etc/net/ifaces/myinterface2
...
# vi /etc/hotplug/net.agent (see /etc/net/ifaces/default/options:USE_HOTPLUG)
# vi /etc/pcmcia/network
...
# service network stop
# rm /etc/init.d/network
# ln -s /etc/init.d/network /etc/net/scripts/network.init
# rmmod <all loaded network modules>
# service network start

2A. Example configuration
eth0 with 10.0.0.1/24, default route to 10.0.0.254 and route 10.0.1.0/24 through 10.0.0.253

{
old /etc/sysconfig/network-scripts/ifcfg-eth0:
---8<---8<---
DEVICE=eth0
BOOTPROTO=static
IPADDR=10.0.0.1
NETMASK=255.255.255.0
ONBOOT=yes
---8<---8<---

old /etc/sysconfig/network:
---8<---8<---
GATEWAY=10.0.0.254
---8<---8<---

old /etc/sysconfig/static-routes:
---8<---8<---
eth0 net 10.0.1.0 netmask 255.255.255.0 gw 10.0.0.253
---8<---8<---

old /etc/modules.conf:
---8<---8<---
alias eth0 3c59x
---8<---8<---
}

{
new /etc/net/iface/<any name>/options
---8<---8<---
# only if name is not "eth[0-9]+"
TYPE=eth
MODULE=3c59x
---8<---8<---

new /etc/net/iface/<any name>/ipv4address
---8<---8<---
10.0.0.1/24
---8<---8<---

new /etc/net/iface/<any name>/ipv4route
---8<---8<---
10.0.1.0/24 via 10.0.0.253
default via 10.0.0.254
---8<---8<---
}

2B. REQUIREMENTS
ifrename (part of recent wireless-utils package) is a must for interface
name maps. NOTE: /etc/net 0.4.2 requires ifrename-28!
vlan-utils24 are required to setup VLAN interfaces.
Your kernel must have CryptoAPI patch applied to setup PSK IPSec tunnels.
When LINKDETECT is used, you will need ifplugstatus from ifplugd package.
When BOOTPROTO is other than 'static', you will need a DHCP and (optionally)
IPv4LL client (zcip).
iproute2 is a must

3.1 FILES
/etc/net/iface/default
There is no interface named 'default', this dir only stores default
configuration. Files:
options: default options for all interfaces
options-<TYPE>: default options for interfaces of type TYPE
Those scripts are executed only if [ -x ]:
ifup-pre-local: executed before interface is up, but after it exists
ifup-post-local: executed after the interface is completely up and running
ifdown-pre-local: executed before the interface is going to be shutdown
ifdown-post-local: executed after the interface is completely gone

/etc/net/ifaces/<IFACE>
This is interface-specific configuration. Files:
options: general and type-specific options
ipv4address: 1 IPv4 address per line
ipv4route: 1 IPv4 route per line
ipv6address: 1 IPv6 address per line
ipv6route: 1 IPv6 route per line
iplink: 1 ip link option per line
ipneigh: 1 ip neigh option per line
ipv4rule: 1 ip -4 rule option per line
brctl: 1 'brctl set' arg set per line
ipxinterface: 1 'ipx_interface add' arg set per line

/etc/net/scripts
network.init: chkconfig initscript
functions: helper functions
options: default options

/etc/net/
options: global options and defaults
ipv4rule: ip rules startup table ('ip -4 rule add' args)
sysctl.conf: sysctl startup
vlantab: VLAN mass-configuration table
iftab: interface mappings table, processed each time ifup is run
iftab file format is described in iftab manpage. Please note that we don't
use /etc/iftab, but keep our own /etc/net/iftab. This difference allows to
keep /etc/net-specific filenames with profile and host suffixes under a
single directory without creating additional mess in /etc. Additionally
it prevents the system from accidental interface name change after ifrename
invocation.

3.2 Interface groups:
0/virtual: dummy, lo (tun/tuntap?)
1/realphys (real physical): ethernet, PLIP (SLIP?)
2/hostedphys (hosted physical): VLANs, bonding
3/indeplog (independent/stateless logical): IP tunnels, IPSec tunnels, eql (vtun?)
4/deplog (dependent/statefull logical): PPP (PPtP)
Each interface has its type. Several types form a group. Groups are brought up
in a fixed order to avoid broken dependencies (say, you will not want your VLAN
interface tried to be setup before its host interface ever exists).

3.3 PLIP maps
My notes for multiple PLIP interfaces.

myplip mac fc:fc:fc:fc:fc:fc
Most hosts have 1 or 0 parallel ports.
If you have more and need configured all of them, try
using different 'baseaddress 0xXXX' maps for each iface.
Also note that you will need appropriate modules.conf
entries like:
alias plip0 plip
alias plip1 plip
alias parport0 parport
alias parport1 parport
below plip parport_pc
below parport_pc parport
options parport io=0x3f8,0x3bc
I can't check if this works now.

3.4 QoS hierarchy
/etc/net/ifaces/ether/qos/
1/ --- root qdisc, 1 is handle (1:)
1/qdisc --- root qdisc options
10/   \
20/    | - root qdisc subclasses (handles are 1:10, 1:20 and 1:30 respectively)
30/   /
10/class --- class options
10/100/ --- class child qdisc options (handle 10:100)
10/100/101/   \
10/100/102/    | - subclasses (100:101, 100:102, 100:103)
10/100/103/   /
General rules:
1. Classes and qdiscs can contain each other. Typically a class contains a qdisc
or one or more subclasses. A qdisc typically contains one ore more classes.
2. Containment is represented by directory tree.
3. Directory must contain one of two files: either 'class' or 'qdisc' so that we
know the type of each node. The file contains current node parameters.
4. Qdisc handle is it's directory name with ':'.
5. Class classid is the last qdisc seen in the tree plus ':' plus current class's
directory name.
6. If current directory contains file 'extra', it's contents will be used when
creating children (usually classes). This does not apply to childrens' children.
7. Class dir can contain 'filter' file with filter statements. The filters will
belong to parent qdisc and will point to current dir (class), you don't have to
specify parent and flowid keywords. If 'extra.filter' file exists, it's contents
will be prefixed to each line of 'filter' file.

3.5. INTERFACE RECURSION AND DEPENDENCIES
1. When we bring up an iface, we MUST ensure that parent iface is up.
If it is not so, continue only if we succeeded bringing parent iface up.
2. When we have brought an iface up, we MAY (if configured to do it)
bring up all ifaces that depend on it.
3. When we bring down an iface, we MUST first bring down all dependant
ifaces.
4. We SHOULD keep track of processed ifaces for the original transaction
to avoid loops.
Look for IFUP_CHILDREN, IFDOWN_CHILDREN, IFUP_PARENTS and IFDOWN_PARENTS
in /etc/net/ifaces/default/options.

3.5.1 ifup algorythm
[ifup_parents]
create (type-specific)
[rename]
[ifup-pre]
config (protocols and set UP)
setup (type-specific, may bind to parents or modify them)
[ifup-post]
[ifup_children]

3.5.2 ifdown algorythm
[ifdown_children]
[shutdown] (type-specific, may unbind from parents or modify them)
[ifdown-pre]
unconfig (and set DOWN)
[ifdown-post]
destroy (type-specific)
[ifdown_parents]

3.5.3 VLANs and iface deps
As for now (0.5.2 and earlier) interfaces from vlantab bypass traditional logic,
they can't cause parent/child interface to become up/down. If parent interface
is down at the moment of vlantab processing (ONBOOT=no or misconfiguration), all
child VLAN interfaces will be just skipped.


4. SYSTEM CONFIGURATION
4.1 Edit /etc/sysctl.conf so that it does not intersect with /etc/net/sysctl.conf

4.2 pcmcia_cs configuration (already done in ALTLinux)
Edit /etc/pcmcia/network.opts and replace calls to /sbin/ifup and 
/sbin/ifdown to '/etc/net/scripts/ifup-removable $1 pcmcia_cs' and
'/etc/net/scripts/ifdown-removable $1 pcmcia_cs' respectively.
Apply patch for interface name change support to cardmgr.

4.3 hotplug configuration (already done in ALTLinux)
Edit /etc/hotplug/net.agent and change 
/sbin/ifdown to '/etc/net/scripts/ifdown-removable $1 hotplug' and
/sbin/ifup to '/etc/net/scripts/ifup-removable $1 hotplug'.

4.4 ifplugd configuration (already done in ALTLinux)
As of version 0.7.10 /etc/net have changed ifplugd code. Look at
/etc/net/ifaces/default/options-eth for info.

5. NETWORK PROFILES
5.1 static profiles
A profile is a configuration superset. E.g. when a notebook boots up in
several different networks, it's desirable to select current configuration
by just one parameter. Current profile name can be set via:
 1. environment variable NETPROFILE (not a good idea I guess)
 2. file /etc/net/profile (file should contain just one word, e.g. "office" w/o quotes)
 3. kernel boot parameter "netprof", e.g. "LILO: linux netprof=home"
Specifying a profile does nothing by default. But if etcnet scripts know the
current profile name (e.g. "home") and look for a configuration file (e.g. "options"
and "options#home" exists, then "options#home" will be used instead of "options".
The same for ipv4address, ipv4route, ipv4rule, ipv6address, iplink and so on).

Now if you want to boot the same host in two different networks, you will most
probably have to create additional ipv4address#yourprofilename for another address
and ipv4route#yourprofilename for another default route. Same for resolv.conf,
I guess.

Next example: booting two different hosts from the same HDD (root fs). The same as
previous, but additional options#yourprofilename and iftab#yourprofilename for the
different network card.

To switch between configurations without editing /etc/net/profile one can use:
# service etcnet startwith office
# service etcnet restartwith home

5.2 dynamic profiles
If 'selectprofile' executable script exists in iface directory, it will be run with a
single argument, which defines current stage of (de)configuration sequence. If you
want to override current profile name during runtime, you should perform required
actions in this script and print profile name to stdout. Since this script will be run
several times and runtime detection can take certain time to complete, it is advised
that the script should perform actions only at certain stages. 'selectprofile' will
always get calling script name as the first parameter, so you can skip trying to
detect wireless AP before the kernel module is even loaded, for example. See
/etc/net/ifaces/default/selectprofile for sample implementation.
As for /etc/net-0.5.3 init_netprofile is called only from {ifup,ifdown}.*,
{setup,shutdown}-.* and network.init scripts.

6. PPP interfaces
Directory layout:
[options] --- see ifaces/default/options-ppp
[pppoptions] --- pppd options file
[pppinit] --- pppd init chat script (not shell script)
[pppconnect] --- pppd connect chat script (not shell script)
[pppdisconnect] --- pppd disconnect chat script (not shell script)
ip{v4,v6}{address,route} are a little useless ATM, because pppd assigns addresses
on its own. This will be resolved later.
Note that you will need to place a call to /etc/net/scripts/ifdown-ppp to
/etc/ppp/ip-down or /etc/ppp/ip-down.d/ for scripts to work as designed.
Naming conventions:
PPP links tend to make a considerable mess due to floating indexes. iftab/ifrename
will not work here, so we will have old ppp%u names. create-ppp will try to guess
correct unit index from the interface name and pass it to pppd.

7. smart sysctl support
If there is a sysctl.conf file in interface directory, it will be processed in this
manner: fully specified variables (like in a traditional /etc/sysctl.conf file) will
will be processed as is, but for single word variables like rp_filter auto-prefix
will be tried to find. Auto-prefix works only for interface sysctl.conf and
type-specific sysctl.conf (/etc/net/scripts/sysctl.conf-$TYPE). Order of processing:
/etc/net/sysctl.conf (at startup)
/etc/net/ifaces/default/sysctl.conf (at ifup w/o auto-prefix)
/etc/net/ifaces/default/sysctl.conf-$TYPE (at ifup with auto-prefix)
/etc/net/ifaces/XXXXXX/sysctl.conf (at ifup with auto-prefix)

8. FIXME: Multiple hosts configuration
Priority table:
file#profile@{host,alias}
file@{host,alias}
file#profile
file

9. PPTP interfaces
/etc/net supports Linux pptp-client. PPTP interfaces are in fact PPP interfaces,
main difference is that one has to put
--
pty 'pptp --nolaunchpppd 1.2.3.4'
--
line into pppoptions file. 1.2.3.4 is IP address of PPTP server.

10. Firewall support
10.1. Iptables configs structure

/etc/net/ifaces/default/options: You'd set CONFIG_FW to "yes" for firewall support
/etc/net/ifaces/default/fw/options: Some options for firewall (type, syntax,
default policy for chains)

/etc/net/ifaces/<IFACE>/fw/iptables:
modules: file with list of modules to load when firewall starting
syntax: file with syntax of firewall rules if you've enabled
IPTABLES_HUMAN_SYNTAX

filter: directory with chains for table filter
   |
   --INPUT: File with rules for chain INPUT
   |
   --FORWARD: File with rules for chain FORWARD
   |
   --OUTPUT: File with rules for chain OUTPUT
  
nat: directory with chains for table nat
   |
   --PREROUTING: File with rules for chain PREROUTING
   |
   --POSTROUTING: File with rules for chain POSTROUTING
   |
   --OUTPUT: File with rules for chain OUTPUT
   
mangle: directory with chains for table mangle
   |
   --PREROUTING: File with rules for chain PREROUTING
   |
   --INPUT: File with rules for chain INPUT
   |
   --FORWARD: File with rules for chain FORWARD
   |
   --OUTPUT: File with rules for chain OUTPUT
   |
   --POSTROUTING: File with rules for chain POSTROUTING

You can create your own chain by adding new file to directory. Chain name is
case-sensitive!

Each directory may contains special file "loadorder". In this case tables and
chains processed in order from this file (ony by one)

10.2. Rules syntax
Supported  two type of syntax:
	- raw iptables syntax
	- new "human" syntax a la ipfw
	
If you've enabled IPTABLES_HUMAN_SYNTAX in fw/options, then you can use rules
like ipfw (see examples and syntax file)

In both types of syntax you'd not to include chain or table name to rule.

You can use environment variables and even run one-string commands by using $(cmd).
If there is now output from commnd rule will not be added (this can be used
for including some configs or files with functions).

System environment variable $NAME contains current interface name.

Comments in all files must begins with #

10.3. How it works

When you start service network:
interface "default":
- If CONFIG_FW is yes then go step 2 otherwise go out :)
- Apply chains policy before any interface start and before forwarding is enabled
  sysctl
- Load all modules from first to last from "module" file if any
- Create all user-defined chains in all tables if any
- From each chain in each table read rules one by one, parse it (if IPTABLES_HUMAN_SYNTAX)
  and pass it to iptables
each other interface:
- Do same work except chains policy

When you stop service network:
 Do same work in case of start with some diffrences:
- All steps goes in reverse order
- If interface is not "default" then rules deleted one by one from last to first
  otherwise chain just flushed
- Modules unloads from last to first
- Reset chains policy to ACCEPT

You don't need to have all configs for all interfaces. Default rules (in
virtual "default" interface directory) are enough to setup firewall.
But you can have and start some special firewall rules for given interface
or just for clean kernel rules tables (i.e. if you have down some interface
there is no reason to have hundreds of rules for it)

There is special script /sbin/fw which can manage firewall without restarting
interface. Just run: /sbin/fw default stop and your firewall will be stopped :)

 Bugs and limitations
1. Syntax file is not completed. Some rules (especially with prefix "not") will
not work (you can patch syntax file)
2. Many other limitations :)

11. Known bugs
1. some kernels have problems with many VLAN interfaces
2. teql interfaces can't be safely renamed
3. VLAN interfaces sometimes are initialized into wrong state: http://www.kernel.org/git/gitweb.cgi?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=f4637b55ba960d9987a836617271659e9b7b0de8
4. some network drivers have race condition in interface init code
5. ppp interfaces can only be named ppp%d
6. DHCP does not work for bonding
