How do I use it?

Let's illustrate by use of an example:

Suppose you have the following two machines at your disposal on the ubiquitous LAN:

We'll assume that they're connected by a "real" interface, and that they can communicate through generic methods. Here's how you create a tunnel between "pseudo" addresses 12.0.0.1 and 12.0.0.2:

On machine A (10.0.0.25), enter:

# ifconfig gre0 create                 <- create the pseudo device
# ifconfig gre0 12.1 12.2 link1        <- set the local (inner) addrs
# ifconfig gre0 tunnel 10.25 10.163    <- set the encapsulating (outer) addrs
# ifconfig gre0                        <- print the current state

The IP packet that's sent from machine A looks like this:

+------------+----------+------+
| dst 10.163 | dst 12.2 | data |
+------------+----------+------+
\_IP address_/\______data______/

On machine B (10.0.0.163), do the reverse:

# ifconfig gre0 12.2 12.1 link1
# ifconfig gre0 tunnel 10.163 10.25
# ifconfig gre0

Since the IP packet is decapsulated on machine B, it now looks like this:

+------------+------------------+
|  dst 12.2  |    data          |
+------------+------------------+
\_IP address_/\______data______/

From machine A, you should now be able to ping 12.0.0.2. What happens under the covers is an IP packet with source 12.0.0.1 and destination 12.0.0.2 is encapsulated with the "real" source 10.0.0.25 and destination 10.0.0.163.

That's interesting but not very useful since you would have accomplished the same thing if you went to 10.0.0.163 directly. Let's take a look at a more typical example.