make the examples in this page work for a simple 2 machine, directly

connected, setup; encourage people to try this way before using for real;

ok hshoexer@

1 files changed, 74 insertions, 36 deletions

diff --git a/share/man/man8/vpn.8 b/share/man/man8/vpn.8
index 711fbc4993f..cd772e97fb8 100644
--- a/share/man/man8/vpn.8
+++ b/share/man/man8/vpn.8
@@ -1,4 +1,4 @@
-.\" $OpenBSD: vpn.8,v 1.91 2005/04/15 07:45:14 jmc Exp $
+.\" $OpenBSD: vpn.8,v 1.92 2005/04/15 08:09:38 jmc Exp $
 .\"
 .\" Copyright 1998 Niels Provos <provos@physnet.uni-hamburg.de>
 .\" All rights reserved.
@@ -44,8 +44,7 @@ linked via a cryptographically secured tunnel to the security gateway of
 the other subnet.
 .Xr ipsec 4
 is used to provide the necessary network-layer cryptographic services.
-This document describes the configuration process for setting up a
-.Nm VPN .
+This document describes the configuration process for setting up a VPN.
 .Pp
 Briefly, creating a VPN consists of the following steps:
 .Pp
@@ -191,6 +190,7 @@ key management daemon.
 To make sure the daemon is properly configured
 to provide the required security services (typically, encryption and
 authentication), start the daemon with debugging or verbose output.
+Sample configuration files are provided below.
 .Pp
 .Xr isakmpd 8
 implements security policy using the
@@ -206,12 +206,17 @@ interface), or key management packets (for
 .Xr isakmpd 8 ,
 .Tn UDP
 packets with source and destination ports of 500) should be allowed to pass.
+Additional filter rules may be present for other traffic,
+though care should be taken that other rules do not leak IPsec traffic.
 .Pp
 .Sy Note :
-The examples in this page use a private (non-routable) IP address
-to denote gateways (GATEWAY_A and GATEWAY_B).
-These addresses are normally public (routable) IP addresses
-and are given as examples only.
+The examples in this page describe a test setup on an internal LAN,
+using private (non-routable) IP addresses.
+In a typical setup,
+at least GATEWAY_A and GATEWAY_B would be configured using
+public (routable) IP addresses.
+NETWORK_A and NETWORK_B may or may not use public IP addresses,
+depending on the network.
 .Pp
 The
 .Xr pf.conf 5
@@ -219,8 +224,8 @@ rules for a tunnel which uses encryption (the ESP IPsec protocol) and
 .Xr isakmpd 8
 on security gateway A might look like this:
 .Bd -literal -offset indent
-GATEWAY_A = "192.168.1.254"
-GATEWAY_B = "192.168.2.1"
+GATEWAY_A = "192.168.1.13"
+GATEWAY_B = "192.168.1.15"
 NETWORK_A = "10.0.50.0/24"
 NETWORK_B = "10.0.99.0/24"
 
@@ -254,16 +259,48 @@ rules, the "quick" clause can be added to the last four rules.
 NAT rules can also be used on the
 .Xr enc 4
 interface.
-Note that it is strongly encouraged that instead of detailed PF
-rules, the SPD (IPsec flow database) be utilized to specify security
-policy, if only to avoid filtering conflicts.
+.Pp
+.Sy Note :
+it is strongly encouraged that instead of detailed PF rules,
+the SPD (IPsec flow database) be utilized to specify security policy,
+if only to avoid filtering conflicts.
 .Sh EXAMPLES
+It is recommended that a test setup be created before attempting to
+deploy a VPN on the internet.
+The examples in this page can be done using two machines
+directly connected to each other,
+and a little imagination.
+The IP address of each machine represents a gateway address;
+the alias (see below) is simply a hook into a fictitious network.
+.Ss Manual and automated keying
+This step is only necessary if the VPN is being set up as a test VPN,
+on an internal LAN.
+.Pp
+The VPN can be represented using two machines (A and B).
+An alias should be added to each machine,
+to give it the appearance of being in another network.
+.Pp
+On machine A:
+.Bd -literal -offset indent
+# ifconfig ne0 192.168.1.13 description "Machine A"
+# ifconfig ne0 alias 10.0.50.1
+.Ed
+.Pp
+On machine B:
+.Bd -literal -offset indent
+# ifconfig bge0 192.168.1.15 description "Machine B"
+# ifconfig bge0 alias 10.0.99.1
+.Ed
+.Pp
+For all other (non-test) cases,
+.Xr ifconfig 8
+should be used to configure machines appropriately.
 .Ss Manual keying
 To create a manual keyed VPN between two class C networks using
 3DES encryption and the following IP addresses:
 .Bd -literal -offset indent
-GATEWAY_A  = 192.168.1.254
-GATEWAY_B  = 192.168.2.1
+GATEWAY_A  = 192.168.1.13
+GATEWAY_B  = 192.168.1.15
 NETWORK_A = 10.0.50.0/24
 NETWORK_B = 10.0.99.0/24
 .Ed
@@ -279,11 +316,11 @@ The SHA-1 authentication key for needs 160 bits, or 20 bytes.
 .It
 Create the Security Associations (on both endpoints):
 .Bd -literal -offset indent
-# /sbin/ipsecadm new esp -src 192.168.2.1 -dst 192.168.1.254 \e
+# /sbin/ipsecadm new esp -src 192.168.1.15 -dst 192.168.1.13 \e
 	-forcetunnel -spi 1000 -enc 3des -auth sha1 \e
 	-keyfile enc_key -authkeyfile auth_key
 
-# /sbin/ipsecadm new esp -src 192.168.1.254 -dst 192.168.2.1 \e
+# /sbin/ipsecadm new esp -src 192.168.1.13 -dst 192.168.1.15 \e
 	-forcetunnel -spi 1001 -enc 3des -auth sha1 \e
 	-keyfile enc_key -authkeyfile auth_key
 .Ed
@@ -293,28 +330,28 @@ outbound flows, the latter is the ingress filter for the
 incoming security association):
 .Bd -literal -offset indent
 # ipsecadm flow -out -require -proto esp \e
-	-src 192.168.1.254 -dst 192.168.2.1 \e
+	-src 192.168.1.13 -dst 192.168.1.15 \e
 	-addr 10.0.50.0/24 10.0.99.0/24
 # ipsecadm flow -in -require -proto esp \e
-	-src 192.168.1.254 -dst 192.168.2.1 \e
+	-src 192.168.1.13 -dst 192.168.1.15 \e
 	-addr 10.0.99.0/24 10.0.50.0/24
 .Ed
 .It
 Create the matching IPsec flows on machine B:
 .Bd -literal -offset indent
 # ipsecadm flow -out -require -proto esp \e
-	-src 192.168.1.254 -dst 192.168.2.1 \e
+	-src 192.168.1.13 -dst 192.168.1.15 \e
 	-addr 10.0.50.0/24 10.0.99.0/24
 # ipsecadm flow -in -require -proto esp \e
-	-src 192.168.1.254 -dst 192.168.2.1 \e
+	-src 192.168.1.13 -dst 192.168.1.15 \e
 	-addr 10.0.99.0/24 10.0.50.0/24
 .Ed
 .It
 Configure the firewall rules on machine A
 using the previously defined ruleset:
 .Bd -literal -offset indent
-GATEWAY_A = "192.168.1.254"
-GATEWAY_B = "192.168.2.1"
+GATEWAY_A = "192.168.1.13"
+GATEWAY_B = "192.168.1.15"
 NETWORK_A = "10.0.50.0/24"
 NETWORK_B = "10.0.99.0/24"
 
@@ -324,10 +361,10 @@ NETWORK_B = "10.0.99.0/24"
 Configure the firewall rules on machine B, modifying the
 definitions as appropriate:
 .Bd -literal -offset indent
-GATEWAY_A = "192.168.2.1"
-GATEWAY_B = "192.168.1.254"
-NETWORK_A = "10.0.99.0/24"
-NETWORK_B = "10.0.50.0/24"
+GATEWAY_A = "192.168.1.13"
+GATEWAY_B = "192.168.1.15"
+NETWORK_A = "10.0.50.0/24"
+NETWORK_B = "10.0.99.0/24"
 
 (rest of ruleset, modified as appropriate)
 .Ed
@@ -355,7 +392,7 @@ for machine A:
 # traffic (i.e. encrypted & authenticated).
 
 [Phase 1]
-192.168.2.1=		peer-machineB
+192.168.1.15=		peer-machineB
 
 # 'Phase 2' defines which connections the daemon
 # should establish.  These connections contain the actual
@@ -369,7 +406,7 @@ Connections=		VPN-A-B
 [peer-machineB]
 Phase=			1
 Transport=		udp
-Address=		192.168.2.1
+Address=		192.168.1.15
 Configuration=		Default-main-mode
 Authentication=		yoursharedsecret
 
@@ -420,7 +457,7 @@ for machine B:
 # traffic (i.e. encrypted & authenticated).
 
 [Phase 1]
-192.168.1.254=		peer-machineA
+192.168.1.13=		peer-machineA
 
 # 'Phase 2' defines which connections the daemon
 # should establish.  These connections contain the actual
@@ -434,7 +471,7 @@ Connections=		VPN-B-A
 [peer-machineA]
 Phase=			1
 Transport=		udp
-Address=		192.168.1.254
+Address=		192.168.1.13
 Configuration=		Default-main-mode
 Authentication=		yoursharedsecret
 
@@ -505,8 +542,8 @@ it must be installed without any permissions for "group" or "other".
 Configure the firewall rules on machine A
 using the previously defined ruleset:
 .Bd -literal -offset indent
-GATEWAY_A = "192.168.1.254"
-GATEWAY_B = "192.168.2.1"
+GATEWAY_A = "192.168.1.13"
+GATEWAY_B = "192.168.1.15"
 NETWORK_A = "10.0.50.0/24"
 NETWORK_B = "10.0.99.0/24"
 
@@ -516,10 +553,10 @@ NETWORK_B = "10.0.99.0/24"
 Configure the firewall rules on machine B, modifying the
 definitions as appropriate:
 .Bd -literal -offset indent
-GATEWAY_A = "192.168.2.1"
-GATEWAY_B = "192.168.1.254"
-NETWORK_A = "10.0.99.0/24"
-NETWORK_B = "10.0.50.0/24"
+GATEWAY_A = "192.168.1.13"
+GATEWAY_B = "192.168.1.15"
+NETWORK_A = "10.0.50.0/24"
+NETWORK_B = "10.0.99.0/24"
 
 (rest of ruleset, modified as appropriate)
 .Ed
@@ -560,6 +597,7 @@ Firewall configuration file.
 .Xr isakmpd.conf 5 ,
 .Xr isakmpd.policy 5 ,
 .Xr pf.conf 5 ,
+.Xr ifconfig 8 ,
 .Xr ipsecadm 8 ,
 .Xr isakmpd 8 ,
 .Xr pfctl 8 ,