man/ifupdown-multi-interfaces.5.rst: new
Robert Edmonds
10 years ago
| 0 | ifupdown-multi-interfaces | |
| 1 | ========================= | |
| 2 | ---------------------------------------------------------- | |
| 3 | ifupdown-multi extension for the interfaces(5) file format | |
| 4 | ---------------------------------------------------------- | |
| 5 | ||
| 6 | :Date: 17 September 2013 | |
| 7 | :Version: 0.1.0 | |
| 8 | :Manual section: 5 | |
| 9 | :Manual group: File formats | |
| 10 | ||
| 11 | DESCRIPTION | |
| 12 | ----------- | |
| 13 | ||
| 14 | `/etc/network/interfaces` contains network interface information for the | |
| 15 | **ifup**\(8) and **ifdown**\(8) commands. This manpage describes the | |
| 16 | **ifupdown-multi** extensions to the the standard **interfaces**\(5) file | |
| 17 | format. | |
| 18 | ||
| 19 | The **ifupdown-multi** extensions to **ifupdown** integrate Linux's policy | |
| 20 | routing based support for multiple default gateways on independent network | |
| 21 | connections. These extensions can replace a typical shell script based approach | |
| 22 | that directly invokes a sequence of **ip**\(8) commands for configuring | |
| 23 | multiple uplinks with declarative syntax in the `/etc/network/interfaces` file. | |
| 24 | ||
| 25 | **ifupdown-multi** records the policy information used to bring up each network | |
| 26 | interface when **ifup**\(8) is run and removes the same policy routing | |
| 27 | information when **ifdown**\(8) is run. | |
| 28 | ||
| 29 | IFACE OPTIONS | |
| 30 | ------------- | |
| 31 | ||
| 32 | The standard **address** and **netmask** options must be set for each | |
| 33 | interface. The **gateway** option must *NOT* be set. | |
| 34 | ||
| 35 | The new **multi_gateway** and **multi_table** options must be set to configure | |
| 36 | policy routing with **ifupdown-multi**. | |
| 37 | ||
| 38 | Additionally, the **multi_gateway_weight** and **multi_preferred_prefixes** | |
| 39 | options can be specified in order to control optional policy routing features. | |
| 40 | ||
| 41 | **multi_gateway** *address* | |
| 42 | Default gateway for this interface. (Required.) | |
| 43 | ||
| 44 | **multi_table** *id* | |
| 45 | Table identifier. This must be a numeric value, and each interface must have a | |
| 46 | unique value. Recommended range: 1-1000. (Required.) | |
| 47 | ||
| 48 | **multi_gateway_weight** *weight* | |
| 49 | Set this gateway's weight. This value is directly passed as the *weight* | |
| 50 | parameter to the *nexthop* part of an **ip-route**\(8) route object. Higher | |
| 51 | values indicate higher relative bandwidth or quality. (Optional.) | |
| 52 | ||
| 53 | **multi_preferred_prefixes** *prefix* [*prefix*]... | |
| 54 | Prefer this connection for the given prefixes. This option configures the | |
| 55 | routing policy database using the **ip-rule**\(8) command to use this | |
| 56 | connection for the specified prefixes. (Optional.) | |
| 57 | ||
| 58 | EXAMPLES | |
| 59 | -------- | |
| 60 | ||
| 61 | The following example shows a basic configuration with two network interfaces. | |
| 62 | *eth0* is on the 198.51.100.0/24 network, while *eth1* is on the 203.0.113.0/24 | |
| 63 | network. Each interface stanza has a "multi_gateway" option, as opposed to the | |
| 64 | usual "gateway" option. Each interface stanza also needs a "multi_table" option, | |
| 65 | whose parameter is a small, unique non-negative integer. (This number will be | |
| 66 | used internally to uniquely identify an interface-specific routing table.) | |
| 67 | ||
| 68 | :: | |
| 69 | ||
| 70 | auto eth0 | |
| 71 | iface eth0 inet static | |
| 72 | address 198.51.100.123 | |
| 73 | netmask 255.255.255.0 | |
| 74 | multi_table 1 | |
| 75 | multi_gateway 198.51.100.1 | |
| 76 | ||
| 77 | auto eth1 | |
| 78 | iface eth1 inet static | |
| 79 | address 203.0.113.234 | |
| 80 | netmask 255.255.255.0 | |
| 81 | multi_table 2 | |
| 82 | multi_gateway 203.0.113.1 | |
| 83 | ||
| 84 | The following example shows a more complicated setup using optional | |
| 85 | **ifupdown-multi** parameters. It is similar to the first example, but the | |
| 86 | network connection on *eth0* is preferred for most connections, and several | |
| 87 | network prefixes prefer to use one or the other network connection. | |
| 88 | ||
| 89 | :: | |
| 90 | ||
| 91 | auto eth0 | |
| 92 | iface eth0 inet static | |
| 93 | address 198.51.100.123 | |
| 94 | netmask 255.255.255.0 | |
| 95 | multi_table 1 | |
| 96 | multi_gateway 198.51.100.1 | |
| 97 | multi_gateway_weight 5 | |
| 98 | multi_preferred_prefixes 10.0.0.0/8 | |
| 99 | ||
| 100 | auto eth1 | |
| 101 | iface eth1 inet static | |
| 102 | address 203.0.113.234 | |
| 103 | netmask 255.255.255.0 | |
| 104 | multi_table 2 | |
| 105 | multi_gateway 203.0.113.1 | |
| 106 | multi_gateway_weight 1 | |
| 107 | multi_preferred_prefixes 172.16.0.0/12 192.168.0.0/16 | |
| 108 | ||
| 109 | FILES | |
| 110 | ----- | |
| 111 | ||
| 112 | `/etc/network/interfaces` | |
| 113 | System-wide network interface configuration. See **interfaces**\(5). | |
| 114 | ||
| 115 | `/var/run/network/ifupdown-multi.*` | |
| 116 | State information used by **ifupdown-multi**. | |
| 117 | ||
| 118 | SEE ALSO | |
| 119 | -------- | |
| 120 | ||
| 121 | **interfaces**\(5), **ifup**\(8), **ip**\(8), **ip-route**\(8), **ip-rule**\(8). | |
| 122 | ||
| 123 | Linux Advanced Routing & Traffic Control HOWTO -- Chapter 4: Rules. | |
| 124 | http://www.tldp.org/HOWTO/Adv-Routing-HOWTO/lartc.rpdb.html |