NAME

/etc/net - basic and advanced network configuration in Linux

SYNOPSIS

ifup <interface>

ifdown <interface>

service network <start|stop|restart|reload...>

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.

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.

/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.

/etc/net/sysctl.conf

sysctl startup file

/etc/net/ipv4rule ???

ip rules startup table ('ip -4 rule add' args)

/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.

/etc/net/hosttab

This optional file can be used during MULTIHOST CONFIGURATION.

/etc/net/ifup-pre-local

If exists and is executable, is run before ANY interface is up, but after it is created.

/etc/net/ifup-post-local

If exists and is executable, is run after ANY interface is completely up and running.

/etc/net/ifdown-pre-local

If exists and is executable, is run before ANY interface is going to be shutdown.

/etc/net/ifdown-post-local

If exists and is executable, is run after ANY interface is completely gone.

/etc/net/netup-pre

If exists and is executable, is run before starting network.

/etc/net/netup-post

If exists and is executable, is run after starting network.

/etc/net/netdown-pre

If exists and is executable, is run before stopping network.

/etc/net/netdown-post

If exists and is executable, is run after stopping network.

INTERFACE CONFIGURATION

To complete interface configuration one should perform the following steps for each network interface found at Linux host:

Create interface configuration directory /etc/net/ifaces/<NAME>

Fill it with configuration files accordingly to INTERFACE DIRECTORY LAYOUT.

INTERFACE GROUPS

There are 5 interface groups in /etc/net model:

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.

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.

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.

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.

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.

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.

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.

options

Main options file. This file is required. See etcnet-options manpage for list of options available.

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.

ipneigh

List of 'ip ne' commands, can be used to control ARP table, e.g. add static ARP entries. This file is not required.

ipv4address

List of IPv4 addresses for current interface. This file is not required, but often used.

ipv4route

List of IPv4 routes for current interface. This file is not required, but often used.

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.

ipv6address

List of IPv6 addresses for current interface. This file is not required.

ipv6route

List of IPv6 routes for current interface. This file is not required.

iwconfig

List of iwconfig commands. This file is only required for WiFi WEP.

wpa_supplicant.conf

wpa_supplicant configuration file. This file is only required for WiFi WPA.

bridge

List of bridge commands. This file is only used by bridges and is not required.

ethtool

List of ethtool commands. This file is only useful for Ethernet interfaces and is not required.

ipxinterface

List of 'ipx_interface add' arguments. This file is required for IPX interfaces.

sysctl.conf

List of sysctl options, which will be processed after interface is up. Lookup SMART SYSCTL SUPPORT. This file is optional.

resolv.conf

Resolver configuration. This file will be copied to /etc/resolv.conf after interface is up. This file is optional.

ifup-pre

If exists and is executable, is run before CURRENT interface is up, but after it is created.

ifup-post

If exists and is executable, is run after CURRENT interface is completely up and running.

ifdown-pre

If exists and is executable, is run before CURRENT interface is going to be shutdown.

ifdown-post

If exists and is executable, is run after CURRENT interface is completely gone.

pppoptions

This optional file contains additional pppd options for PPP interfaces.

pppinit

This optional file contains chat (not shell) script for modem initialization.

pppconnect

This optional file contains chat (not shell) script to connect to remote node (e.g. dial a number).

pppdisconnect

This optional file contains chat (not shell) script to disconnect from remote node (e.g. hang up).

l2tptunnel

This file contains options to establish L2TP tunnel. This options are directly passed to l2tpconfig command.

l2tpsession

This file contains options to establish L2TP session. This options are directly passed to l2tpconfig command.

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).

SPECIAL INTERFACES

/etc/net is shipped with 3 existing interfaces:

lo

This is a must for a Linux host. Loopback interface comes in configuration, suitable for most cases.

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.

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.

SMART SYSCTL SUPPORT

/etc/net handles several sysctl.conf files:

/etc/net/sysctl.conf

Processed at startup, no autoprefix.

/etc/net/ifaces/default/sysctl.conf

Processed at ifup, no autoprefix.

/etc/net/ifaces/default/sysctl.conf-$TYPE

Processed at ifup, with autoprefix.

/etc/net/ifaces/XXXXXX/sysctl.conf

Processed at ifup, with autoprefix.

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.

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:

HOST=<interface>

REQUIRES='<interface> [<interface> [<interface>...]]'

IFUP_PARENTS=<boolean>

IFDOWN_PARENTS=<boolean>

IFUP_CHILDREN=<boolean>

IFDOWN_CHILDREN=<boolean>

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.

In most cases (if ever) the task will be done by proper REQUIRES option.

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:

<host interface> <VLAN ID>

Create VLAN interface and automatically name it according to VLAN_NAMETYPE option value.

<host interface> <VLAN ID> <VLAN interface name>

Create VLAN interface with specified name.

<host interface> <VLAN ID> <VLAN interface name> <'ip address' arguments>

Create VLAN interface with specified name and run 'ip address' with specified arguments.

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:

<hostname1><space><alias1>
<hostname2><space><alias2>
<hostname3><space><alias3>
<hostname4><space><alias4>
<hostname5><space><alias5>

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.

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:

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 "netprofile", e.g. "LILO: linux netprofile=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 for the different network card.

To switch between configurations without editing /etc/net/profile one can use:

# service network startwith office

# service network restartwith home

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.

MULTIHOST CONFIGURATION (FIXME)

You can create a single configuration tree and distribute it across multiple hosts. If you mark

ENVIRONMENT

NETHOST

This variable can hold host ID in multi-host configuration, which should be used instead of automatically detected.

NETPROFILE

This variable can hold configuration profile name, which should be used instead of automatically detected.

BUGS

Some kernels have problems with many VLAN interfaces.

teql interfaces can't be safely renamed.

VLAN interfaces sometimes are initialized into wrong state.

ppp interfaces can only be named ppp%d.

SkyStar DVB interfaces can only be named dvb*.

DHCP does not work for bonding.

ppp option 'demand' can hang /etc/net startup forever

CONFIG_IPV6 must be on to configure 6-to-4 (TYPE=iptun, TUNTYPE=sit) tunnels correctly

If you configure dummy interfaces, 'dummy0' interface name must be always unused.

Bonding interface name can't be same as another kernel module name.

SEE ALSO

ip(8), tc(8), etcnet-options(5), etcnet-qos(8), etcnet-fw(8),