networking.7 : create network quickstart guide

Now that the handbook has been moved to ports, I think it's very nice to
have a network quickstart guide in-band, in base, in the system manual.
If the user uses any of the following terms "man -k
{network,networking,wifi,quickstart}" this page will come up, which is I
think a very common use case for new users.

Currently, this document explains connecting to a basic Ethernet
network, a basic wifi network, scanning for wifi networks, and airplane
mode, as well as linking to other sections, including the handbook

Co-authored-by: Graham Perrin <grahamperrin@gmail.com>
Reviewed by: imp, bcr, freebsd@igalic.co
Pull Request: https://github.com/freebsd/freebsd-src/pull/833

(cherry picked from commit 75eda0096bf83b9b88996d9903b5d4e504047eba)
(cherry picked from commit 5dced41439109368a8f3c9a818fe518542d7063e)

Approved-by: re (cperciva)

2 files changed, 106 insertions, 0 deletions

diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile
index 11246195201c..7f506c1dfc5f 100644
--- a/share/man/man7/Makefile
+++ b/share/man/man7/Makefile
@@ -47,6 +47,11 @@ MLINKS+= c.7 c11.7
 MLINKS+= c.7 c17.7
 MLINKS+= c.7 c2x.7
 
+.if ${MK_INET} != "no"
+MAN+=	networking.7
+MLINKS+= networking.7 wifi.7
+.endif
+
 .if ${MK_TESTS} != "no"
 ATF=	${SRCTOP}/contrib/atf
 .PATH:	${ATF}/doc
diff --git a/share/man/man7/networking.7 b/share/man/man7/networking.7
new file mode 100644
index 000000000000..869812c05a9b
--- /dev/null
+++ b/share/man/man7/networking.7
@@ -0,0 +1,101 @@
+.\"-
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2024 Alexander Ziaee <concussious@runbox.com>
+.\"
+.Dd April 17, 2024
+.Dt "NETWORKING" 7
+.Os
+.Sh NAME
+.Nm networking ,
+.Nm wifi
+.Nd quickstart guide to connecting to a network
+.Sh DESCRIPTION
+In the following examples, it is assumed that we are connecting to Ethernet
+with the first interface found by the
+.Xr em 4
+driver, and Wi-Fi with the first interface found by the
+.Xr iwn 4
+driver, though your hardware will vary.
+.Sh EXAMPLES
+.Bl -tag -width 0n
+.It Sy Connecting to an Ethernet network with DHCP:
+.Bd -literal -offset 2n
+.Ic # dhclient em0
+.Ed
+.It Sy Connecting to a cellular network with USB tethering:
+.Pp
+Load the USB tethering driver,
+.Xr urndis 4 :
+.Bd -literal -offset 2n
+.Ic # kldload urndis
+.Ed
+.Pp
+Ask for a DHCP lease on the USB tethering interface:
+.Bd -literal -offset 2n
+.Ic # dhclient ue0
+.Ed
+.It Sy Connecting to a Wi-Fi network:
+.Pp
+Identify your Wi-Fi hardware:
+.Bd -literal -offset 2n
+.Ic % sysctl net.wlan.devices
+.Ed
+.Pp
+Configure your Wi-Fi hardware as wlan0 interface:
+.Ed
+.Bd -literal -offset 2n
+.Ic # sysrc wlans_iwn0="wlan0"
+.Ed
+.Pp
+Set that interface to negotiate a DHCP lease with
+.Xr wpa_supplicant 8 :
+.Bd -literal -offset 2n
+.Ic # sysrc ifconfig_wlan0="WPA SYNCDHCP"
+.Ed
+.Pp
+Enter the details of the Wi-Fi network:
+.Bd -literal -offset 2n
+.Ic # wpa_passphrase \(dqmyssid\(dq \(dqmypassphrase\(dq >> wpa_supplicant.conf
+.Ed
+.Pp
+Restart the network interface daemon:
+.Bd -literal -offset 2n
+.Ic # service netif restart
+.Ed
+.Pp
+.It Sy Scanning for Wi-Fi networks:
+.Bd -literal -offset 2n
+.Ic % ifconfig wlan0 scan
+.Ed
+.It Sy Airplane mode:
+.Bd -literal -offset 2n
+.Ic # service netif stop
+.Ed
+.El
+.Sh SEE ALSO
+.Xr bsdconfig 8 ,
+.Xr dhclient 8 ,
+.Xr ifconfig 8 ,
+.Xr wpa_passphrase 8
+.Pp
+The Advanced Networking chapter of the
+.Fx
+Handbook.
+.Sh CAVEATS
+Shell Special Characters in the
+.Ar SSID
+or
+.Ar passphrase
+will need to be escaped for
+.Xr wpa_passphrase 8 ,
+commonly using
+.Ql \e ,
+see the manual page for your shell for more details.
+.Pp
+Currently
+.Ql Ic service netif restart
+does not restart routing.
+A common workaround is to issue
+.Ql Ic service netif restart && service routing restart
+instead.