To create a persistent static route to a remote network via a gateway.

Suppose that a host is connected via eth0 to the subnet 192.168.0.0/24 with the address 192.168.0.7.

The default gateway for this subnet is 192.168.0.1, but to reach the subnet 10.0.0.0/8 it is necessary to use a different gateway at 192.168.0.2.

Ideally the route should be added immediately after the relevant interface has been brought up, and removed immediately before it is taken down.

This can be achieved using up and down commands in /etc/network/interfaces.

First ensure that the relevant interface is down (if it is not already):

/etc/network/interfaces

ifdown eth0

Next add suitable up and down commands to the relevant interface definition within the interfaces file.

If an interface definition does not already exist then you will need to add one:

/etc/network/interfaces

auto eth0
iface eth0 inet static
  address 192.168.0.7
  netmask 255.255.255.0
  gateway 192.168.0.1
  up /sbin/route add -net 10.0.0.0 netmask 255.0.0.0 gw 192.168.0.2
  down /sbin/route del -net 10.0.0.0 netmask 255.0.0.0

If there is more than one route to be created then this can be done using multiple up and down commands.

Once the interfaces file has been modified, bring the interface back up:

ifup eth0

Print the routing table using the route command:

route -n

When the interface is up you should be able to see the new route (the line with a destination of 10.0.0.0):

Kernel IP routing table
Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
192.168.0.0     0.0.0.0         255.255.255.0   U     0      0        0 eth0
10.0.0.0        192.168.0.2     255.0.0.0       UG    0      0        0 eth0
0.0.0.0         192.168.0.1     0.0.0.0         UG    0      0        0 eth0

If you take the interface down again then all three of these routes should disappear.

If ifup gives an error of the form:

SIOCADDRT: Network is unreachable
Failed to bring up eth0.

then the likely cause is that the specified gateway is not directly reachable via any local interface. Gateways must be reachable in a single hop: having a route to them is not sufficient.

In place of 'Network is unreachable', recent versions of the Kernel may return the rather less helpful message:

SIOCDELRT: No such process
Failed to bring up eth0.

An error of the form:

SIOCADDRT: File exists
Failed to bring up eth0.

indicates that there is already a route to the specified destination via the specified gateway.

One way this could happen is by bringing the interface up manually (using ifconfig and route) and then attempting to bring it up using ifup.

If you suspect that something like this has happened then you should manually restore the interface and routing table (using ifconfig and route) to the state expected by ifup and ifdown.