root/trunk/etcnet/docs/etcnet.8

.TH "etcnet" "8" "0.9" "Denis Ovsienko <info@etcnet.org>" "Linux network configuration"
.SH "NAME"
/etc/net \- basic and advanced network configuration in Linux
.SH "SYNOPSIS"
.TP 
ifup <interface>
.TP 
ifdown <interface>
.TP 
service network <start|stop|restart|reload...>
.SH "DESCRIPTION"
/etc/net is a network configuration system. It should be both simple
to use for a beginner and powerful for expert. First of all you have
to describe your network options and interfaces in a set of
configuration files. Once you are done, you should be able to control
state of your host with 3 scripts: ifup, ifdown, network.init.
.SH "SYSTEM CONFIGURATION"
/etc/net ships in default configuration, which is suitable for many cases. Linux distributions can customize default installation even further, but there are things that only you can configure. /etc/net keeps its configuration in files, most of which reside in /etc/net (literally) directory.
.IP "/etc/net/options.d"
This directory by default keeps 00\-default file. There can be other files here, they will be read in alphabet order.
.IP /etc/net/sysctl.conf
sysctl startup file
.IP "/etc/net/ipv4rule ???"
ip rules startup table ('ip \-4 rule add' args)
.IP /etc/net/vlantab
VLAN mass\-configuration table. If you need to configure lots of simple VLAN interfaces, this is the right place. See VLANTAB SYNTAX for details.
.IP /etc/net/iftab
Interface mappings table, optional, but strictly advised to have. This file is used by ifrename. 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.
.IP /etc/net/hosttab
This optional file can be used during MULTIHOST CONFIGURATION.
.IP /etc/net/ifup\-pre
If exists and is executable, is run before ANY interface is up, but after it is created.
.IP /etc/net/ifup\-post
If exists and is executable, is run after ANY interface is completely up and running.
.IP /etc/net/ifdown\-pre
If exists and is executable, is run before ANY interface is going to be shutdown.
.IP /etc/net/ifdown\-post
If exists and is executable, is run after ANY interface is completely gone.
.IP /etc/net/netup\-pre
If exists and is executable, is run before starting network.
.IP /etc/net/netup\-post
If exists and is executable, is run after starting network.
.IP /etc/net/netdown\-pre
If exists and is executable, is run before stopping network.
.IP /etc/net/netdown\-post
If exists and is executable, is run after stopping network.
.SH "INTERFACE CONFIGURATION"
To complete interface configuration one should perform the following steps for each
network interface found at Linux host:
.TP 
Invent a descriptive name for the interface and place appropriate line
into /etc/net/iftab. Note that some restrictions apply:
PPP interfaces can only be named pppXXX, TEQL interfaces shouldn't be renamed due
to a bug in kernel code. Skystar DVB kernel code isn't stable at all.
.TP 
Create interface configuration directory /etc/net/ifaces/<NAME>
.TP 
Fill it with configuration files accordingly to INTERFACE DIRECTORY LAYOUT.
.SH "INTERFACE GROUPS"
There are 5 interface groups in /etc/net model:
.IP "virtual"
Self\-consistent interfaces, currently loopback and dummy. They very seldom require other interfaces and require no hardware, therefore chances are high to bring them up.
.IP "real physical"
Interfaces, corresponding to real hardware: pure Ethernet, PLIP, USB Ethernet adapters and DVB. You cannot bring them up, if there is no hardware present.
.IP "hosted physical"
Something between physical and logical type. This group includes: VLAN, bonding, bridges and traffic equalizers. These interfaces don't directly use hardware, but are built from one ore more 'host' real physical interfaces. If host interface is missing, hosted interfaces can't be brought up.
.IP "independent logical"
This group includes IP and IPSec tunnels. Tunnels are stateless, they are much like virtual group, but sometimes they depend on lower\-level interfaces indirectly.
.IP "dependent logical"
This group currently consists of PPP interfaces, including PPPoE/PPtP ones. Their well known property is to disconnect on timeouts, so this group has the most chances to fail.
.LP 
When network is being started, /etc/net puts interfaces in appropriate group and processes groups from virtual to dependent logical. When network is being stopped, groups are processed in reverse order. This order results in less failures, than simple processing from A to Z. You don't have to specify interface group anywhere, it is computed from interface type.
.SH "INTERFACE DIRECTORY LAYOUT"
Unless explicitly stated, each configuration file contains 1 item per line (options, addresses, routes etc.). You have to create files for each feature you want to use. If file is missing, the feature will not be configured.
.IP options
Main options file. This file is required. See etcnet\-options manpage for list of options available.
.IP iplink
List of 'ip link' commands. If you need to change interface MTU or PROMISC flag, this is the right place to do it. If you want to to have a specific MAC address on the board, you can place "address xx:xx:xx:xx:xx:xx" into this file. This file is not required.
.IP ipneigh
List of 'ip ne' commands, can be used to control ARP table, e.g. add static ARP entries. This file is not required.
.IP ipv4address
List of IPv4 addresses for current interface. This file is not required, but often used.
.IP ipv4route
List of IPv4 routes for current interface. This file is not required, but often used.
.IP ipv4rule
List of IPv4 routing rules for current interface. You will need this file only if you install routes into multiple routing tables. This file is not required.
.IP ipv6address
List of IPv6 addresses for current interface. This file is not required.
.IP ipv6route
List of IPv6 routes for current interface. This file is not required.
.IP iwconfig
List of iwconfig commands. This file is only required for WiFi WEP.
.IP wpa_supplicant.conf
wpa_supplicant configuration file. This file is only required for WiFi WPA.
.IP brctl
List of brctl commands. This file is only used by bridges and is not required.
.IP ethtool
List of ethtool commands. This file is only useful for Ethernet interfaces and is not required.
.IP ipx_interface
List of 'ipx_interface add' arguments. This file is required for IPX interfaces.
.IP sysctl.conf
List of sysctl options, which will be processed after interface is up. Lookup SMART SYSCTL SUPPORT. This file is optional.
.IP resolv.conf
Resolver configuration. This file will be copied to /etc/resolv.conf after interface is up. This file is optional.
.IP ifup\-pre
If exists and is executable, is run before CURRENT interface is up, but after it is created.
.IP ifup\-post
If exists and is executable, is run after CURRENT interface is completely up and running.
.IP ifdown\-pre
If exists and is executable, is run before CURRENT interface is going to be shutdown.
.IP ifdown\-post
If exists and is executable, is run after CURRENT interface is completely gone.
.IP pppoptions
This optional file contains additional pppd options for PPP interfaces.
.IP pppinit
This optional file contains chat (not shell) script for modem initialization.
.IP pppconnect
This optional file contains chat (not shell) script to connect to remote node (e.g. dial a number).
.IP pppdisconnect
This optional file contains chat (not shell) script to disconnect from remote node (e.g. hang up).

.LP 
The interface directory can contain 2 special directories: 'fw' and 'qos'. They are used for
firewall and QoS configuration respectively. For QoS configuration manual see etcnet\-qos(8).
.SH "SPECIAL INTERFACES"
/etc/net is shipped with 3 existing interfaces:
.IP lo
This is a must for a Linux host. Loopback interface comes in configuration, suitable for most cases.
.IP default
This is really not an interface, but interface template. 'default' interface forms initial set of options for all interfaces and it doesn't belong to any interface group. This interface allows placing an additional options file into configuration directory: options\-<TYPE>. This optional file has effect ONLY for 'default' interface, it allows to override default options with type\-specific options.
It is not recommended to change options for 'default' interface. Each interface can add extra options or override existing options, if needed.
.IP unknown
This is a special interface, which is used each time /etc/net can't find a suitable configuration, but is requested to do. This interface's purpose is to help configure hotplug interfaces, which don't yet have a configuration.
.SH "SMART SYSCTL SUPPORT"
/etc/net handles several sysctl.conf files:
.IP  /etc/net/sysctl.conf
Processed at startup, no autoprefix.
.IP  /etc/net/ifaces/default/sysctl.conf
Processed at ifup, no autoprefix.
.IP  /etc/net/ifaces/default/sysctl.conf\-$TYPE
Processed at ifup, with autoprefix.
.IP  /etc/net/ifaces/XXXXXX/sysctl.conf
Processed at ifup, with autoprefix.
.LP 
Autoprefix means that if fully specified variables (like in a traditional /etc/sysctl.conf file)
is met, it will be processed as is, but for single word variables like rp_filter or forwarding
appropriate prefix will be tried to find. Autoprefix works only for interface sysctl.conf and
type\-specific sysctl.conf.
.SH "RECURSION AND DEPENDENCIES"
Some interfaces require other interfaces to be up for proper initialization. Some
dependencies are calculated automaticaly, but some need to be configured manually.
If interface A has REQUIRES=B in it's options file, A is the child, B is the parent.
There are 6 options to control dependencies resolution:
.IP HOST=<interface>
.IP REQUIRES='<interface>\ [<interface>\ [<interface>...]]'
.IP IFUP_PARENTS=<boolean>
.IP IFDOWN_PARENTS=<boolean>
.IP IFUP_CHILDREN=<boolean>
.IP IFDOWN_CHILDREN=<boolean>
.LP 
Those options are described in etcnet\-options(5) manpage.
NOTE:
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.
.LP 
In most cases (if ever) the task will be done by proper REQUIRES option.
.SH "VLANTAB SYNTAX"
vlantab provides a way to bulk\-configure VLAN interfaces with only IPv4 address
at each interface. For each VLAN interface you have to place a line:
.IP "<host interface> <VLAN ID>"
Create VLAN interface and automatically name it according to VLAN_NAMETYPE option value.
.IP "<host interface> <VLAN ID> <VLAN interface name>"
Create VLAN interface with specified name.
.IP "<host interface> <VLAN ID> <VLAN interface name> <'ip address' arguments>"
Create VLAN interface with specified name and run 'ip address' with specified arguments.
.SH "HOSTTAB SYNTAX"
This file holds aliases for hostnames. If your hostname is long or unconvinient, you can define an alias here. This alias can be used for tagging files. One hostname should be referenced by one alias only. File format:
.nf 
<hostname1><space><alias1>
<hostname2><space><alias2>
<hostname3><space><alias3>
<hostname4><space><alias4>
<hostname5><space><alias5>
.SH "FILENAMES (FIXME)"
/etc/net scripts implement support for separate namespaces in a single configuration
tree. This is achieved though special suffixes, which are used depending on current values
of network profile and network host.
.SH "CONFIGURATION 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:
.TP 
1. environment variable NETPROFILE (not a good idea I guess)
.TP 
2. file /etc/net/profile (file should contain just one word, e.g. "office" w/o quotes)
.TP 
3. kernel boot parameter "netprofile", e.g. "LILO: linux netprofile=home"
.LP 
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:
.TP 
# service etcnet startwith office
.TP 
# service etcnet restartwith home
.LP 
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 of /etc/net\-0.5.3 init_netprofile is called only from {ifup,ifdown}.*,
{setup,shutdown}\-.* and network.init scripts.
.SH "MULTIHOST CONFIGURATION (FIXME)"
You can create a single configuration tree and distribute it across multiple hosts. If you mark
.SH "ENVIRONMENT"
.IP NETHOST
This variable can hold host ID in multi\-host configuration, which should be used instead of automatically detected.
.IP NETPROFILE
This variable can hold configuration profile name, which should be used instead of automatically detected.
.SH "BUGS"
.TP 
Some kernels have problems with many VLAN interfaces.
.TP 
teql interfaces can't be safely renamed.
.TP 
VLAN interfaces sometimes are initialized into wrong state.
.TP 
Some network drivers have race condition in interface init code, so 'mac' iftab match does not work.
.TP 
ppp interfaces can only be named ppp%d.
.TP 
SkyStar DVB interfaces can only be named dvb*.
.TP 
DHCP does not work for bonding.
.TP 
ppp option 'demand' can hang /etc/net startup forever
.TP 
CONFIG_IPV6 must be on to configure 6\-to\-4 (TYPE=iptun, TUNTYPE=sit) tunnels correctly
.TP 
If you configure dummy interfaces, 'dummy0' interface name must be always unused.
.TP 
Bonding interface name can't be same as another kernel module name.
.SH "SEE ALSO"
.BR ip(8),
.BR tc(8),
.BR etcnet\-options(5),
.BR etcnet\-qos(8),
.BR etcnet\-fw(8),
.BR ifrename(8),
.BR iftab(5)