- Document more explicitly how the mac_portacl(4) policy works.

- Document all the policy sysctl's.
- Note that mac_portacl(4) appeared in FreeBSD 5.1.
- A bit of mdoc(7) fixes.

Much of the new text was inspired by the source code comments.

Reviewed by:	rwatson

share/man/man4/mac_portacl.4

@@ -30,12 +30,12 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 11, 2003
+.Dd February 13, 2004
 .Dt MAC_PORTACL 4
 .Os
 .Sh NAME
 .Nm mac_portacl
-.Nd network port access control policy
+.Nd "network port access control policy"
 .Sh SYNOPSIS
 To compile the port access control policy into your kernel,
 place the following lines in your kernel
@@ -81,11 +81,60 @@ and
 .Va net.inet.ip.portrange.reservedhigh
 .Xr sysctl 8
 MIBs.
-.Ss Runtime Configuration
-The port access control list is specified in the
-.Va security.mac.portacl.rules
+.Pp
+The
+.Nm
+policy only affects ports explicitly bound by a user process (either
+for a listen/outgoing
+.Tn TCP
+socket, or a send/receive
+.Tn UDP
+socket).
+This policy will not limit ports bound implicitly for outgoing
+connections where the process has not explicitly selected a port:
+these are automatically selected by the IP stack.
+.Pp
+When
+.Nm
+is enabled it will control binding access to ports up to the port
+number set in the
+.Va security.mac.portacl.port_high
 .Xr sysctl 8
-MIB in the following format:
+variable.
+By default all attempts to bind to
+.Nm
+controlled ports will fail if not explicitly allowed by the port
+access control list, though binding by the superuser will be allowed,
+if the
+.Xr sysctl 8
+variable
+.Va security.mac.portacl.suser_exempt
+is set to a non-zero value.
+.Ss Runtime Configuration
+The following
+.Xr sysctl 8
+MIBs are available for fine-tuning the enforcement of this MAC policy.
+All
+.Xr sysctl 8
+variables, except
+.Va security.mac.portacl.rules ,
+can also be set as
+.Xr loader 8
+tunables in
+.Xr loader.conf 5 .
+.Bl -tag -width indent
+.It Va security.mac.portacl.enabled
+Enforce the
+.Nm
+policy.
+(Default: 1).
+.It Va security.mac.portacl.port_high
+The highest port number
+.Nm
+will enforce rules for.
+(Default: 1023).
+.It Va security.mac.portacl.rules
+The port access control list is specified in the the following format:
 .Pp
 .Sm off
 .Bd -literal -offset indent
@@ -148,8 +197,16 @@ entry will not function
 (i.e., even the specified user/group may not be able to bind to the specified
 port).
 .El
+.It Va security.mac.portacl.suser_exempt
+Allow superuser (i.e. root) to bind to all
+.Nm
+protected ports, even if the port access control list does not
+explicitly allow this.
+(Default: 1).
+.El
 .Sh SEE ALSO
 .Xr mac 3 ,
+.Xr ip 4 ,
 .Xr mac_biba 4 ,
 .Xr mac_bsdextended 4 ,
 .Xr mac_ifoff 4 ,
@@ -161,7 +218,11 @@ port).
 .Xr mac 9
 .Sh HISTORY
 MAC first appeared in
-.Fx 5.0 .
+.Fx 5.0
+and
+.Nm
+first appeared in
+.Fx 5.1 .
 .Sh AUTHORS
 This software was contributed to the
 .Fx