Use example.com to improve clarity of documentation
PATCH 1/1 Use example.com to improve clarity of documentation
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.
--- doc/openvpn.8 | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-)
doc/openvpn.8 +18 -17
@@ -6427,12 +6427,12 @@ and 1 for the CA certificate. .nf .ft 3 .in +4 [email protected]... [email protected]... X509_0_CN=Test-Client X509_0_O=OpenVPN-TEST X509_0_ST=NA X509_0_C=KG [email protected]... [email protected]... X509_1_O=OpenVPN-TEST X509_1_L=BISHKEK X509_1_ST=NA
@@ -6576,13 +6576,13 @@ for use with OpenVPN. .SS VPN Address Setup: For purposes of our example, our two machines will be called -.B may.kg +.B host1.example.com and -.B june.kg. +.B host2.example.com. If you are constructing a VPN over the internet, then replace -.B may.kg +.B host1.example.com and -.B june.kg +.B host2.example.com with the internet hostname or IP address that each machine will use to contact the other over the internet.
@@ -6590,8 +6590,8 @@ Now we will choose the tunnel endpoints. Tunnel endpoints are private IP addresses that only have meaning in the context of the VPN. Each machine will use the tunnel endpoint of the other machine to access it over the VPN. In our example, -the tunnel endpoint for may.kg -will be 10.4.0.1 and for june.kg, 10.4.0.2. +the tunnel endpoint for host1.example.com +will be 10.4.0.1 and for host2.example.com, 10.4.0.2. Once the VPN is established, you have essentially created a secure alternate path between the two hosts
@@ -6600,16 +6600,16 @@ control which network traffic passes between the hosts (a) over the VPN or (b) independently of the VPN, by choosing whether to use (a) the VPN endpoint address or (b) the public internet address, -to access the remote host. For example if you are on may.kg and you wish to connect to june.kg +to access the remote host. For example if you are on host1.example.com and you wish to connect to host2.example.com via .B ssh without using the VPN (since .B ssh has its own built-in security) you would use the command -.B ssh june.kg. +.B ssh host2.example.com. However in the same scenario, you could also use the command .B telnet 10.4.0.2 -to create a telnet session with june.kg over the VPN, that would +to create a telnet session with host2.example.com over the VPN, that would use the VPN to secure the session rather than .B ssh.
@@ -6626,11 +6626,11 @@ you will get a weird feedback loop. .LP On may: .IP -.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9 +.B openvpn \-\-remote host2.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9 .LP On june: .IP -.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9 +.B openvpn \-\-remote host1.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9 .LP Now verify the tunnel is working by pinging across the tunnel. .LP
@@ -6667,11 +6667,11 @@ program. .LP On may: .IP -.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key +.B openvpn \-\-remote host2.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key .LP On june: .IP -.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \-\-secret key +.B openvpn \-\-remote host1.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \-\-secret key .LP Now verify the tunnel is working by pinging across the tunnel. .LP
@@ -6709,11 +6709,11 @@ parameters you can use the included file dh1024.pem. .LP On may: .IP -.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 +.B openvpn \-\-remote host2.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 .LP On june: .IP -.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 +.B openvpn \-\-remote host1.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 .LP Now verify the tunnel is working by pinging across the tunnel. .LP
@@ -6888,3 +6888,4 @@ as published by the Free Software Foundation. .\"********************************************************* .SH AUTHORS James Yonan <[email protected]...> +Phillip Smith <[email protected]...>
Signature · 1 line
2.6.2
PATCH 1/1 Use example.com to improve clarity of documentation
Hi all,
I sent the below patch last week, but it doesn't seem to have made it to the mail list for some reason, despite being delivered to SourceForge:
18 Nov 2015 12:07:31 [email protected]
216.34.181.68 accepted message./Remote host said: 250 OK
id=1ZyrDo-0007pR-Cm/
Cheers,
~p
---------- Forwarded message ----------
From: Phillip Smith <[email protected]...>
Date: 18 November 2015 at 11:51
Subject: [PATCH] Use example.com to improve clarity of documentation
To: [email protected]
Cc: Phillip Smith <[email protected]...>
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.
--- doc/openvpn.8 | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-)
doc/openvpn.8 +6 -6
@@ -6427,12 +6427,12 @@ and 1 for the CA certificate. .nf .ft 3 .in +4 [email protected]... [email protected]... X509_0_CN=Test-Client X509_0_O=OpenVPN-TEST X509_0_ST=NA X509_0_C=KG [email protected]... [email protected]... X509_1_O=OpenVPN-TEST X509_1_L=BISHKEK X509_1_ST=NA
@@ -6576,13 +6576,13 @@ for use with OpenVPN. .SS VPN Address Setup: For purposes of our example, our two machines will be called -.B may.kg +.B host1.example.com and -.B june.kg. +.B host2.example.com. If you are constructing a VPN over the internet, then replace -.B may.kg +.B host1.example.com and -.B june.kg +.B host2.example.com with the internet hostname or IP address that each machine will use to contact the other over the internet.
@@ -6590,8 +6590,8 @@ Now we will choose the tunnel endpoints. Tunnel
endpoints are
private IP addresses that only have meaning in the context of the VPN. Each machine will use the tunnel endpoint of the other machine to access it over the VPN. In our example,
-the tunnel endpoint for may.kg
-will be 10.4.0.1 and for june.kg, 10.4.0.2.
+the tunnel endpoint for host1.example.com
+will be 10.4.0.1 and for host2.example.com, 10.4.0.2.
Once the VPN is established, you have essentially
created a secure alternate path between the two hosts
@@ -6600,16 +6600,16 @@ control which network
traffic passes between the hosts
(a) over the VPN or (b) independently of the VPN, by choosing whether to
use
(a) the VPN endpoint address or (b) the public internet address,
-to access the remote host. For example if you are on may.kg and you wish to connect to june.kg
+to access the remote host. For example if you are on host1.example.com and you wish to connect to host2.example.com
via
.B ssh
without using the VPN (since
.B ssh
has its own built-in security) you would use the command
-.B ssh june.kg.
+.B ssh host2.example.com.
However in the same scenario, you could also use the command .B telnet 10.4.0.2
-to create a telnet session with june.kg over the VPN, that would +to create a telnet session with host2.example.com over the VPN, that would
use the VPN to secure the session rather than
.B ssh.
@@ -6626,11 +6626,11 @@ you will get a weird feedback loop.
.LP
On may:
.IP
-.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
+.B openvpn \-\-remote host2.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
.LP
On june:
.IP
-.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
+.B openvpn \-\-remote host1.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
.LP
Now verify the tunnel is working by pinging across the tunnel. .LP
@@ -6667,11 +6667,11 @@ program.
.LP
On may:
.IP
-.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key
+.B openvpn \-\-remote host2.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key
.LP
On june:
.IP
-.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \-\-secret key
+.B openvpn \-\-remote host1.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \-\-secret key
.LP
Now verify the tunnel is working by pinging across the tunnel. .LP
@@ -6709,11 +6709,11 @@ parameters you can use the included file dh1024.pem.
.LP
On may:
.IP
-.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
+.B openvpn \-\-remote host2.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
.LP
On june:
.IP
-.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
+.B openvpn \-\-remote host1.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
.LP
Now verify the tunnel is working by pinging across the tunnel. .LP
@@ -6888,3 +6888,4 @@ as published by the Free Software Foundation.
.\"********************************************************* .SH AUTHORS
James Yonan <[email protected]...>
+Phillip Smith <[email protected]...>
--
2.6.2
Hi,
Quoted 5 lines · Phillip Smith
I sent the below patch last week, but it doesn't seem to have made it to the mail list for some reason, despite being delivered to SourceForge:
18 Nov 2015 12:07:31 [email protected]
216.34.181.68 accepted message./Remote host said: 250 OK
id=1ZyrDo-0007pR-Cm/
It made it to me via the list just fine. It's just that nobody had time to look at it and form an opinion yet.
gert
Signature · 4 lines
USENET is *not* the non-clickable part of WWW!
//www.muc.de/~gert/
Gert Doering - Munich, Germany [email protected]...
fax: +49-89-35655025 [email protected]...Hi,
Quoted 3 lines · Phillip Smith
The example.com domain is set aside defined by IANA for use as documentation
examples.
Replacing references to "june.kg" etc., which could one day become someone's private domain, is not a bad move. Though, not sure why choose example.com over example.net or example.org, or even tlds like .example, .test etc. which are also reserved for docs.
That apart, this is not a carefully constructed patch. It misses several occurrences of "may" and "june" -- even the patch context shows some:
@@ -6626,11 +6626,11 @@ you will get a weird feedback loop.
Quoted 2 lines
.LP
see this one:
Quoted 9 lines
On may:
-.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
+.B openvpn \-\-remote host2.example.com \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
.LP
On june:
and there again, to list a few..
[..]
doc/openvpn.8 as published by the Free Software Foundation. · line 6891
Quoted 6 lines
doc/openvpn.8 +1
-0@@ -6888,3 +6888,4 @@ as published by the Free Software Foundation. .\"********************************************************* .SH AUTHORS James Yonan <[email protected]...> +Phillip Smith <[email protected]...>
Finally, the AUTHORS section in manpage is a place to document the principal AUTHOR(S) of the program that it describes. Traditionally the original author goes there, sometimes with a pointer to full credits.
For all those reasons NAK from me.
Selva
Quoted 3 lines · Selva Nair
Replacing references to "june.kg" etc., which could one day become someone's private domain, is not a bad move. Though, not sure why choose example.com over example.net or example.org, or even tlds like .example, .test etc. which are also reserved for docs.
Thanks for your feedback. I guess there's no real reason for 'example.com' over the others you list, except I had to choose one, and personally I find whatever.example.com easier to read and process as a hostname than whatever.example or something.test
Quoted 2 lines
That apart, this is not a carefully constructed patch. It misses several occurrences of "may" and "june" -- even the patch context shows some:
You're right, I was a little hasty. I will clean up and resubmit.
Quoted 1 line
Finally, the AUTHORS section in manpage is a place to document the principal AUTHOR(S) of the program that it describes. Traditionally the original author goes there, sometimes with a pointer to full credits.
Duly noted; I was not sure as I thought it strange there was only 1 name listed to date. I will not include my name in revision 2.