git: 39f92a4c4c49 - releng/14.1 - networking.7 : create network quickstart guide

The branch releng/14.1 has been updated by imp:

URL: https://cgit.FreeBSD.org/src/commit/?id=39f92a4c4c49490e8a3a4549fae054c0e59f6459

commit 39f92a4c4c49490e8a3a4549fae054c0e59f6459
Author:     Alexander Ziaee <concussious@runbox.com>
AuthorDate: 2024-04-17 15:51:35 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2024-05-21 20:09:04 +0000

    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)
---
 share/man/man7/Makefile     |   5 +++
 share/man/man7/networking.7 | 101 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)

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.