Browse code

Use bob.example.com and alice.example.com to improve clarity of documentation

This patch uses generic "bob.example.com" and "alice.example.com"
hostnames to replace the current "may" and "june" examples. Generic
names chosen rather than other names like "server"/"client" or
"head-office"/"remote-office" etc which may create other unintended
or implicit meanings to the reader.

The example.com domain is set aside defined by IANA for use as
documentation examples. Refer to: http://www.iana.org/domains/reserved
Using this well-known domain makes comprehension of documentation easier.
This patch incorporates feedback from Gert Doering and Selva Nair.

Signed-off-by: Phillip Smith <fukawi2@gmail.com>
Acked-by: Steffan Karger <steffan.karger@fox-it.com>
Message-Id: <1450743146-9050-1-git-send-email-fukawi2@gmail.com>
URL: http://article.gmane.org/gmane.network.openvpn.devel/10875
Signed-off-by: Gert Doering <gert@greenie.muc.de>

Phillip Smith authored on 2015/12/22 09:12:26
Showing 1 changed files
... ...
@@ -6601,13 +6601,13 @@ for use with OpenVPN.
6601 6601
 .SS VPN Address Setup:
6602 6602
 For purposes
6603 6603
 of our example, our two machines will be called
6604
-.B may.kg
6604
+.B bob.example.com
6605 6605
 and
6606
-.B june.kg.
6606
+.B alice.example.com.
6607 6607
 If you are constructing a VPN over the internet, then replace
6608
-.B may.kg
6608
+.B bob.example.com
6609 6609
 and
6610
-.B june.kg
6610
+.B alice.example.com
6611 6611
 with the internet hostname or IP address that each machine will use
6612 6612
 to contact the other over the internet.
6613 6613
 
... ...
@@ -6615,8 +6615,8 @@ Now we will choose the tunnel endpoints.  Tunnel endpoints are
6615 6615
 private IP addresses that only have meaning in the context of
6616 6616
 the VPN.  Each machine will use the tunnel endpoint of the other
6617 6617
 machine to access it over the VPN.  In our example,
6618
-the tunnel endpoint for may.kg
6619
-will be 10.4.0.1 and for june.kg, 10.4.0.2.
6618
+the tunnel endpoint for bob.example.com
6619
+will be 10.4.0.1 and for alice.example.com, 10.4.0.2.
6620 6620
 
6621 6621
 Once the VPN is established, you have essentially
6622 6622
 created a secure alternate path between the two hosts
... ...
@@ -6625,16 +6625,16 @@ control which network
6625 6625
 traffic passes between the hosts 
6626 6626
 (a) over the VPN or (b) independently of the VPN, by choosing whether to use
6627 6627
 (a) the VPN endpoint address or (b) the public internet address,
6628
-to access the remote host. For example if you are on may.kg and you wish to connect to june.kg
6628
+to access the remote host. For example if you are on bob.example.com and you wish to connect to alice.example.com
6629 6629
 via
6630 6630
 .B ssh
6631 6631
 without using the VPN (since
6632 6632
 .B ssh
6633 6633
 has its own built-in security) you would use the command
6634
-.B ssh june.kg.
6634
+.B ssh alice.example.com.
6635 6635
 However in the same scenario, you could also use the command
6636 6636
 .B telnet 10.4.0.2
6637
-to create a telnet session with june.kg over the VPN, that would
6637
+to create a telnet session with alice.example.com over the VPN, that would
6638 6638
 use the VPN to secure the session rather than
6639 6639
 .B ssh.
6640 6640
 
... ...
@@ -6649,21 +6649,21 @@ you will get a weird feedback loop.
6649 6649
 .\"*********************************************************
6650 6650
 .SS Example 1: A simple tunnel without security
6651 6651
 .LP
6652
-On may:
6652
+On bob:
6653 6653
 .IP
6654
-.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
6654
+.B openvpn \-\-remote alice.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
6655 6655
 .LP
6656
-On june:
6656
+On alice:
6657 6657
 .IP
6658
-.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
6658
+.B openvpn \-\-remote bob.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
6659 6659
 .LP
6660 6660
 Now verify the tunnel is working by pinging across the tunnel.
6661 6661
 .LP
6662
-On may:
6662
+On bob:
6663 6663
 .IP
6664 6664
 .B ping 10.4.0.2
6665 6665
 .LP
6666
-On june:
6666
+On alice:
6667 6667
 .IP
6668 6668
 .B ping 10.4.0.1
6669 6669
 .LP
... ...
@@ -6676,7 +6676,7 @@ program.  Omit the
6676 6676
 option to have OpenVPN run quietly.
6677 6677
 .\"*********************************************************
6678 6678
 .SS Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)
6679
-First build a static key on may.
6679
+First build a static key on bob.
6680 6680
 .IP
6681 6681
 .B openvpn \-\-genkey \-\-secret key
6682 6682
 .LP
... ...
@@ -6685,39 +6685,39 @@ This command will build a random key file called
6685 6685
 (in ascii format).
6686 6686
 Now copy
6687 6687
 .B key
6688
-to june over a secure medium such as by
6688
+to alice over a secure medium such as by
6689 6689
 using the
6690 6690
 .BR scp (1)
6691 6691
 program.
6692 6692
 .LP
6693
-On may:
6693
+On bob:
6694 6694
 .IP
6695
-.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key
6695
+.B openvpn \-\-remote alice.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key
6696 6696
 .LP
6697
-On june:
6697
+On alice:
6698 6698
 .IP
6699
-.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \-\-secret key
6699
+.B openvpn \-\-remote bob.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \-\-secret key
6700 6700
 .LP
6701 6701
 Now verify the tunnel is working by pinging across the tunnel.
6702 6702
 .LP
6703
-On may:
6703
+On bob:
6704 6704
 .IP
6705 6705
 .B ping 10.4.0.2
6706 6706
 .LP
6707
-On june:
6707
+On alice:
6708 6708
 .IP
6709 6709
 .B ping 10.4.0.1
6710 6710
 .\"*********************************************************
6711 6711
 .SS Example 3: A tunnel with full TLS-based security
6712 6712
 For this test, we will designate
6713
-.B may
6713
+.B bob
6714 6714
 as the TLS client and
6715
-.B june
6715
+.B alice
6716 6716
 as the TLS server.
6717 6717
 .I Note that client or server designation only has meaning for the TLS subsystem.  It has no bearing on OpenVPN's peer-to-peer, UDP-based communication model.
6718 6718
 
6719 6719
 First, build a separate certificate/key pair
6720
-for both may and june (see above where
6720
+for both bob and alice (see above where
6721 6721
 .B \-\-cert
6722 6722
 is discussed for more info).  Then construct
6723 6723
 Diffie Hellman parameters (see above where
... ...
@@ -6732,21 +6732,21 @@ client.crt and server.crt.  For Diffie Hellman
6732 6732
 parameters you can use the included file dh1024.pem.
6733 6733
 .I Note that all client, server, and certificate authority certificates and keys included in the OpenVPN distribution are totally insecure and should be used for testing only.
6734 6734
 .LP
6735
-On may:
6735
+On bob:
6736 6736
 .IP
6737
-.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-tls\-client \-\-ca ca.crt \-\-cert client.crt \-\-key client.key \-\-reneg\-sec 60 \-\-verb 5
6737
+.B openvpn \-\-remote alice.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-tls\-client \-\-ca ca.crt \-\-cert client.crt \-\-key client.key \-\-reneg\-sec 60 \-\-verb 5
6738 6738
 .LP
6739
-On june:
6739
+On alice:
6740 6740
 .IP
6741
-.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-tls\-server \-\-dh dh1024.pem \-\-ca ca.crt \-\-cert server.crt \-\-key server.key \-\-reneg\-sec 60 \-\-verb 5
6741
+.B openvpn \-\-remote bob.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-tls\-server \-\-dh dh1024.pem \-\-ca ca.crt \-\-cert server.crt \-\-key server.key \-\-reneg\-sec 60 \-\-verb 5
6742 6742
 .LP
6743 6743
 Now verify the tunnel is working by pinging across the tunnel.
6744 6744
 .LP
6745
-On may:
6745
+On bob:
6746 6746
 .IP
6747 6747
 .B ping 10.4.0.2
6748 6748
 .LP
6749
-On june:
6749
+On alice:
6750 6750
 .IP
6751 6751
 .B ping 10.4.0.1
6752 6752
 .LP
... ...
@@ -6766,12 +6766,12 @@ option to use OpenVPN's default key renegotiation interval of one hour.
6766 6766
 .SS Routing:
6767 6767
 Assuming you can ping across the tunnel,
6768 6768
 the next step is to route a real subnet over
6769
-the secure tunnel.  Suppose that may and june have two network
6769
+the secure tunnel.  Suppose that bob and alice have two network
6770 6770
 interfaces each, one connected
6771 6771
 to the internet, and the other to a private
6772 6772
 network.  Our goal is to securely connect
6773
-both private networks.  We will assume that may's private subnet
6774
-is 10.0.0.0/24 and june's is 10.0.1.0/24.
6773
+both private networks.  We will assume that bob's private subnet
6774
+is 10.0.0.0/24 and alice's is 10.0.1.0/24.
6775 6775
 .LP
6776 6776
 First, ensure that IP forwarding is enabled on both peers.
6777 6777
 On Linux, enable routing:
... ...
@@ -6782,11 +6782,11 @@ and enable TUN packet forwarding through the firewall:
6782 6782
 .IP
6783 6783
 .B iptables \-A FORWARD \-i tun+ \-j ACCEPT
6784 6784
 .LP
6785
-On may:
6785
+On bob:
6786 6786
 .IP
6787 6787
 .B route add \-net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
6788 6788
 .LP
6789
-On june:
6789
+On alice:
6790 6790
 .IP
6791 6791
 .B route add \-net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
6792 6792
 .LP