a few people have bugged me for an example. hopefully this is enough.

diff --git a/share/man/man4/sec.4 b/share/man/man4/sec.4
index c0a940c..79c86a6 100644 (file)
--- a/share/man/man4/sec.4
+++ b/share/man/man4/sec.4
@@ -1,4 +1,4 @@
-.\" $OpenBSD: sec.4,v 1.2 2023/08/07 16:29:36 jmc Exp $
+.\" $OpenBSD: sec.4,v 1.3 2024/08/30 13:09:10 dlg Exp $
 .\"
 .\" Copyright (c) 2023 David Gwynne <dlg@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 7 2023 $
+.Dd $Mdocdate: August 30 2024 $
 .Dt SEC 4
 .Os
 .Sh NAME
@@ -46,6 +46,8 @@ and
 .Xr isakmpd 8
 (the latter via
 .Xr ipsecctl 8 ) .
+.\" These IPsec IKE daemons negotiate ESP tunnel mode between 0.0.0.0/0
+.\" and 0.0.0.0/0.
 .Pp
 .Nm
 interfaces can be created at runtime using the
@@ -57,6 +59,73 @@ configuration file for
 The interface itself can be configured with
 .Xr ifconfig 8 ;
 see its manual page for more information.
+.Sh EXAMPLES
+.Nm
+can be used to provide secure and confidential IP connectivity
+between sites over the public internet.
+For example, a cloud provider may provide connectivity between
+networks they host for a customer, and that customers own
+.Dq on premises
+networks using IPsec tunnels.
+.Ox
+can be set up on the customer side given the following parameters:
+.Pp
+.Bl -tag -width Customer-Gateway -offset indent -compact
+.It Pre-Shared Key
+7kA7evdkd50Q5YdCCF9t8eftgEgL4vk2
+.El
+.Pp
+Outside IP Addresses:
+.Bl -tag -width Customer-Gateway -offset indent -compact
+.It Customer Gateway
+192.0.2.8
+.It Provider Gateway
+198.51.100.14
+.El
+.Pp
+Inside IP Addresses:
+.Bl -tag -width Customer-Gateway -offset indent -compact
+.It Customer Gateway
+169.254.229.42/30
+.It Provider Gateway
+169.254.229.41/30
+.El
+.Pp
+A
+.Nm
+interface can be configured on the customer gateway:
+.Bd -literal -offset indent
+# ifconfig sec0 create
+# ifconfig sec0 tunnel 169.254.229.42/30 169.254.229.41
+# ifconfig sec0 up
+.Ed
+.Pp
+.Xr iked 8
+can be used for IKEv2 negotiation of the IPsec tunnel with the following
+.Xr iked.conf 5
+configuration:
+.Bd -literal -offset indent
+ikev2 "s2s" active \\
+       from any to any \\
+       local 192.0.2.8 peer 198.51.100.14 \\
+       psk "7kA7evdkd50Q5YdCCF9t8eftgEgL4vk2" \\
+       iface sec0
+.Ed
+.Pp
+Once
+.Xr iked 8
+is running with this configuration, communication between the
+customer and provider gateways is enabled.
+.Pp
+Routes to networks hosted by the provider can be added using the
+providers
+.Dq inside IP
+address as the gateway address, or negotiated using a dynamic routing
+protocol.
+Multiple
+.Nm
+interfaces may be configured to talk to separate provider gateways,
+providing redundancy or multiple paths between sites.
 .Sh SEE ALSO
 .Xr ipsec 4 ,
 .Xr netintro 4 ,