5. Usage examples

Here are some tips, examples and additional information on how to design a network structure with CIPE and configure the devices accordingly.

5.1 General tips		General useful tips on CIPE configuration.
5.2 Example 1		The classic VPN setups.
5.3 Example 2		A PKCIPE setup.
5.4 Connection modes		Overview on different carrier network situations.

5.1 General tips

• The IP address of a CIPE device and it's UDP carrier must be different. Chose a transit network (e.g. 192.168 address) for the CIPE devices if these don't fit into existing structures.
• The route to the UDP carrier ("peer" address) can not go through the CIPE device. If both are on the same route (e.g. both are on the same network, IP-address-wise), add a host route to the "peer" address through the right device or gateway.
• In Linux 2.0, the route add -host $5 dev $1 in `ip-up' is required. Without it the link won't work. This also means the `ip-up' script itself is mandatory.
• Routes through a CIPE device should be set only in the `ip-up' script. Use case selections on $1 or $5 if you have several CIPE links. Use route add ... gw $5, not route add ... dev $1. Remember that Linux deletes any routes through a device when this device goes down.
• If you have a default route, the addresses reachable via the CIPE link are routed via the default when the link is down. This can defeat the purpose of an encrypted link. To guard against this, set a reject route to the affected addresses with higher metric in the system startup script.
• Sometimes it is necessary or advisable to announce the address of the peer via proxy-ARP to avoid more complicated routing setups. The example `ip-up' shows how this can be done. In Linux 2.4 a sysctl can be used to use proxy-ARP for the whole network "behind" the peer.
• On a system running gated, gated is the only thing responsible for setting any routes and the routes through the CIPE device routes belong in `gated.conf' as static routes, or are to be set via a routing protocol. To gated, a CIPE link looks and behaves exactly like a dial-up link. It is strongly recommended to put gdc interface in `ip-up' as well as `ip-down' to tell gated about status changes.
• The configuration of both ends of a link is symmetric. One side's ipaddr is the other's ptpaddr, and one side's me is the other's peer. Since CIPE 0.5, peer is picked up dynamically and the real peer may be different from that set in the config file (but this config item must still be present, it should specify the other end's reverse as a reasonable default).
• When designing a network structure, draw the CIPE links as if they were SLIP/PPP links. Build the routing with these links enabled. Then look at the picture as if the CIPE links weren't there, so you can see the routing needed for the UDP adresses.
• Firewall rules which contain a device are independent of the device's existence. This means that they can be established before the module is loaded and ciped run, and that an explicit device option should be used if the device name is used in firewall rules.
• With PKCIPE, the location and content of the PID files from the ip-up sample scripts is mandatory as they are used as lock files. Omitting these can cause confusion when several instances of pkcipe run at the same time.

5.2 Example 1

This basic example shows how to connect hosts and networks with unofficial network numbers through the Internet. Uses for this are classic VPN setups:

1. Connecting two unofficial subnets through an Internet link
2. Connecting a branch office to the head office through a one-address dialup
3. Connecting a mobile host with varying access points

Internet Internet ^ ^ | | hostz |ppp0 |eth1 200.0.24.3 |200.0.24.65 |200.0.24.1 | +---------routera routerb eth0 200.0.24.1 | | eth0 \_ _ _ _ _ _ _ _/ \---------------+-------+---+ | 10.0.1.1 cipcb0 cipcb0 eth0 | | hosta 10.0.1.1 10.0.2.1 10.0.2.1 | | 10.0.1.88 hostx hosty 10.0.2.5 10.0.2.6

As can be seen from the picture, a CIPE device and another network device can have the same IP address if there are no overlapping routes between them.

The CIPE devices are configured like this:

	routera	routerb
	cipcb0	cipcb0
ipaddr	10.0.1.1	10.0.2.1
ptpaddr	10.0.2.1	10.0.1.1
me	200.0.24.65:9999	200.0.24.1:9999
peer	200.0.24.1:9999	200.0.24.65:9999
static routes	10.0.1.0/24 dev eth0	10.0.2.0/24 dev eth0
	default dev ppp0	200.0.24.0/26 dev eth0
		default dev eth1
routes in ip-up	10.0.2.0/24 gw 10.0.2.1	10.0.1.0/24 gw 10.0.1.1

For case 3, assume routera to be the mobile host, think of eth0 missing and ppp0 having a dynamic address. The routerb config remains unchanged. For routera simply omit the eth0 stuff, add the dynip flag for ciped. routerb picks up its peer dynamically. This even works when routerb is plugged behind a firewall and has to rely on a SOCKS5 server for outside access. (Yes, this can be used to punch holes into firewalls. No, it's not my intention to do anything about it. Local policy issues have to be dealt with locally.)

5.3 Example 2

This example shows how to set up PKCIPE. The overall setup is symmetric, there are no designated servers and clients. However, one end has to accept incoming TCP connections on a chosen port (server mode) and the other one has to connect to it (client mode).

The basic configuration of a link is like this: assuming routera has the address (of the CIPE device) 10.0.1.1 and routerb has the address 10.0.2.1 like in Example 1. Each `/etc/cipe/pk/host' file contains the public key of that host together with options applying to that host:

On routera, `/etc/cipe/pk/routerb' looks like this:

-----BEGIN PUBLIC KEY----- (here is the public key of routerb) -----END PUBLIC KEY----- ipaddr 10.0.1.1 ptpaddr 10.0.2.1

and on routerb, `/etc/cipe/pk/routera' looks like this:

-----BEGIN PUBLIC KEY----- (here is the public key of routera) -----END PUBLIC KEY----- ipaddr 10.0.2.1 ptpaddr 10.0.1.1

This is all of the minimum configuration. Note that no me and peer options are necessary. These are determined by pkcipe. It does not matter which side runs pkcipe in server and which one in client mode.

In server mode, pkcipe has to be started via inetd. This requires the following steps:

1. Choose a port. (This is arbitrary, here I use 963.) Enter this port into `/etc/services' on both machines, giving it a name:

   pkcipe 963/tcp

2. Enter the parameters into `/etc/inetd.conf':

   pkcipe stream tcp nowait root /usr/local/sbin/pkcipe pkcipe

   or if using TCP Wrapper for access control:

   pkcipe stream tcp nowait root /usr/sbin/tcpd /usr/local/sbin/pkcipe

   Restart inetd after any change.

The other end then initiates the connection simply via

pkcipe -c server.machine:pkcipe

It is possible to run this connection through NAT (masquerading) or via SOCKS using a dynamic SOCKS library (socksify/runsocks script). In the latter case it may be necessary to repeat the peer address in a -r server.machine argument.

5.4 Connection modes

Here is in detail how it is possible to build CIPE links between different classes of carriers. Those classes are, based on how they are able to reach the carrier network (usually the Internet):

1. Direct connection on a static IP address.
2. Direct connection on a dynamic IP address.
3. Indirect connection through a SOCKS server.
4. Indirect connection through a NAT (masquerading) router.

This produces ten different combinations:

`1-1'

Can be configured statically like in the simple example. Or any end may run a PKCIPE server and let the other end connect.

`1-2'

The `1' end can run a PKCIPE server and let the `2' end connect. pkcipe gets the right IP addresses at both ends, later changes are handled automatically. (6)

`1-3'

Like `1-2', with a ping in ip-up at the `3' end. The `3' end does not know its effective (as seen by the other end) carrier address, so the PKCIPE exchange produces a wrong peer parameter at the `1' end. The ping corrects that by sending packets with the right address. (7)

`1-4'

Like `1-3'.

`2-2'

One end runs a PKCIPE server and publishes its current IP address using some external service (like a web server or dynamic DNS (8)). The other end fetches this address to connect to and proceeds like in `1-2'.

`2-3'

Like `1-3', except that the `2' end uses an external service to publish its current address.

`2-4'

Like `1-4', except that the `2' end uses an external service to publish its current address.

`3-3'

This is not easily possible with the current code because neither end knows its effective carrier address (i.e. the SOCKS UDP relayer address) before the link is set up, and so neither side can send packets to the other. This information is available in the ip-up script, but transmitting it to the other end would need some means outside of CIPE. It is planned that future versions will be able to handle this via extended capabilities of PKCIPE; this will also require an external service like dynamic DNS with a special setup.

`3-4'

Like `3-3'.

`4-4'

Not possible. Neither side gets to know its effective carrier address at all.

See section 3.5 Dynamic carrier addresses, for a more detailed explanation of some of these configurations.