rc.conf.5: modernise network_interfaces

It's not 1996 anymore, and we use CIDR nowadays.  Update the various
ifconfig_ examples to use CIDR notation instead of netmasks, and also
add an example of a basic ifconfig_ entry that most users will be
interested in.

Reviewed by: imp
Pull Request: https://github.com/freebsd/freebsd-src/pull/1217

1 files changed, 37 insertions, 20 deletions

diff --git a/share/man/man5/rc.conf.5 b/share/man/man5/rc.conf.5
index ad84bcbd576c..91da91691756 100644
--- a/share/man/man5/rc.conf.5
+++ b/share/man/man5/rc.conf.5
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd November 13, 2023
+.Dd May 4, 2024
 .Dt RC.CONF 5
 .Os
 .Sh NAME
@@ -1420,13 +1420,18 @@ variables as described below.
 .Pp
 An
 .Va ifconfig_ Ns Aq Ar interface
-variable is also assumed to exist for each value of
+variable is assumed to exist for each value of
 .Ar interface .
 When an interface name contains any of the characters
 .Dq Li .-/+
 they are translated to
 .Dq Li _
 before lookup.
+For example, the interface
+.Va em0.102
+would be configured using the variable
+.Va ifconfig_em0_102 .
+.Pp
 The variable can contain arguments to
 .Xr ifconfig 8 ,
 as well as special case-insensitive keywords described below.
@@ -1434,6 +1439,18 @@ Such keywords are removed before passing the value to
 .Xr ifconfig 8
 while the order of the other arguments is preserved.
 .Pp
+For example, to assign the IPv4 address 192.0.2.1/24 to the interface em0:
+.Bd -literal
+ifconfig_em0="inet 192.0.2.1/24 up"
+.Ed
+.Pp
+If the variable
+.Va ifconfig_ Ns Ao Ar interface Ac Ns Pa _ipv6
+is set, then
+.Va ifconfig_ Ns Aq Ar interface
+does not need to be set unless an IPv4 address should also be assigned to
+the interface.
+.Pp
 It is possible to add IP alias entries using
 .Xr ifconfig 8
 syntax with the address family keyword such as
@@ -1442,8 +1459,8 @@ Assuming that the interface in question was
 .Li em0 ,
 it might look something like this:
 .Bd -literal
-ifconfig_em0_alias0="inet 127.0.0.253 netmask 0xffffffff"
-ifconfig_em0_alias1="inet 127.0.0.254 netmask 0xffffffff"
+ifconfig_em0_alias0="inet 127.0.0.253/32"
+ifconfig_em0_alias1="inet 127.0.0.254/32"
 .Ed
 .Pp
 It also possible to configure multiple IP addresses in Classless
@@ -1472,12 +1489,12 @@ netif_ipexpand_max="4096"
 .Pp
 In the case of
 .Li 192.0.2.5-23/24 ,
-the address 192.0.2.5 will be configured with the
-netmask /24 and the addresses 192.0.2.6 to 192.0.2.23 with
-the non-conflicting netmask /32 as explained in the
+the address 192.0.2.5 will be configured with the prefix length /24 and the
+addresses 192.0.2.6 to 192.0.2.23 with the non-conflicting prefix length /32 as
+explained in the
 .Xr ifconfig 8
 alias section.
-Note that this special netmask handling is only for
+Note that this special CIDR handling is only for
 .Li inet ,
 not for the other address families such as
 .Li inet6 .
@@ -1509,10 +1526,10 @@ its contents are passed to
 Execution stops at the first unsuccessful access, so if
 something like this is present:
 .Bd -literal
-ifconfig_em0_alias0="inet 127.0.0.251 netmask 0xffffffff"
-ifconfig_em0_alias1="inet 127.0.0.252 netmask 0xffffffff"
-ifconfig_em0_alias2="inet 127.0.0.253 netmask 0xffffffff"
-ifconfig_em0_alias4="inet 127.0.0.254 netmask 0xffffffff"
+ifconfig_em0_alias0="inet 127.0.0.251/32"
+ifconfig_em0_alias1="inet 127.0.0.252/32"
+ifconfig_em0_alias2="inet 127.0.0.253/32"
+ifconfig_em0_alias4="inet 127.0.0.254/32"
 .Ed
 .Pp
 Then note that alias4 would
@@ -1529,13 +1546,13 @@ variable, which has the same functionality as
 and can have all of the entries in a variable like the following:
 .Bd -literal
 ifconfig_em0_aliases="\\
-	inet 127.0.0.251 netmask 0xffffffff \\
-	inet 127.0.0.252 netmask 0xffffffff \\
-	inet 127.0.0.253 netmask 0xffffffff \\
-	inet 127.0.0.254 netmask 0xffffffff"
+	inet 127.0.0.251/32 \\
+	inet 127.0.0.252/32 \\
+	inet 127.0.0.253/32 \\
+	inet 127.0.0.254/32"
 .Ed
 .Pp
-It also supports CIDR notation.
+It also supports netmask notation for backward compatibility.
 .Pp
 If the
 .Pa /etc/start_if . Ns Aq Ar interface
@@ -1688,7 +1705,7 @@ variable.
 It is also possible to rename an interface by doing:
 .Bd -literal
 ifconfig_em0_name="net0"
-ifconfig_net0="inet 192.0.2.1 netmask 0xffffff00"
+ifconfig_net0="inet 192.0.2.1/24"
 .Ed
 .It Va ipv6_enable
 .Pq Vt bool
@@ -2045,9 +2062,9 @@ interfaces with:
 .Bd -literal
 gif_interfaces="gif0 gif1"
 gifconfig_gif0="100.64.0.1 100.64.0.2"
-ifconfig_gif0="inet 10.0.0.1 10.0.0.2 netmask 255.255.255.252"
+ifconfig_gif0="inet 10.0.0.1/32 10.0.0.2"
 gifconfig_gif1="inet6 2a00::1 2a01::1"
-ifconfig_gif1="inet 10.1.0.1 10.1.0.2 netmask 255.255.255.252"
+ifconfig_gif1="inet 10.1.0.1/32 10.1.0.2"
 .Ed
 .It Va ppp_enable
 .Pq Vt bool