Date: Fri, 29 May 2026 16:02:01 +0000 From: Olivier Certner <olce@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 39818654ae87 - main - mac_do.4: Document executable paths, default jail values and consistency Message-ID: <6a19b879.34041.444d4be8@gitrepo.freebsd.org>
index | next in thread | raw e-mail
The branch main has been updated by olce: URL: https://cgit.FreeBSD.org/src/commit/?id=39818654ae879788807d3a87c2d75cc700cc7113 commit 39818654ae879788807d3a87c2d75cc700cc7113 Author: Olivier Certner <olce@FreeBSD.org> AuthorDate: 2026-05-20 16:23:33 +0000 Commit: Olivier Certner <olce@FreeBSD.org> CommitDate: 2026-05-29 15:40:25 +0000 mac_do.4: Document executable paths, default jail values and consistency While here, fix the bug of mentioning 'enable' as a possible value for the 'mac.do' jail parameter whereas it is 'new' instead. Reviewed by: bapt MFC after: 1 month Sponsored by: The FreeBSD Foundation Pull Request: https://ron-dev.freebsd.org/FreeBSD/src/pulls/38 --- share/man/man4/mac_do.4 | 189 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 143 insertions(+), 46 deletions(-) diff --git a/share/man/man4/mac_do.4 b/share/man/man4/mac_do.4 index 8c08e072be88..7f05d5f88bf8 100644 --- a/share/man/man4/mac_do.4 +++ b/share/man/man4/mac_do.4 @@ -1,8 +1,8 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2024 Baptiste Daroussin <bapt@FreeBSD.org> -.\" Copyright (c) 2024 The FreeBSD Foundation +.\" Copyright (c) 2024, Baptiste Daroussin <bapt@FreeBSD.org> +.\" Copyright (c) 2024, 2026, The FreeBSD Foundation .\" .\" Portions of this documentation were written by Olivier Certner .\" <olce@FreeBSD.org> at Kumacom SARL under sponsorship from the FreeBSD @@ -42,13 +42,23 @@ policy module allows unprivileged users to change process credentials according to rules configured by the administrator. It supports per-jail configuration. .Pp -Currently, the +The .Nm -policy module only produces effects to processes spawned from the +policy module only produces effects on processes spawned from specific +executables from a configurable whitelist. +By default, this whitelist only contains the .Pa /usr/bin/mdo executable, please see .Xr mdo 1 for more details on this program. +.Pp +Section +.Sx CREDENTIALS RULES +specifies the format of credentials transition rules, and section +.Sx CONFIGURATION +explains how to configure +.Nm , +including rules and authorized executables. .Sh CREDENTIALS RULES Rules specify which transitions of process credentials .Nm @@ -267,84 +277,170 @@ then converted to unsigned ones as specified in the C standard for the and .Vt gid_t types, which are both 32-bit unsigned integers. -.Sh RUNTIME CONFIGURATION -The following +.Sh CONFIGURATION +Each parameter of +.Nm +has a corresponding +.Xr sysctl 8 +knob. +.Nm +supports per-jail values for most parameters. +.Ss Sysctl Knobs +The .Xr sysctl 8 -knobs are available: +knobs presented by +.Nm +are of two types: Global ones, which influence all uses of the module, and +per-jail ones, which allow to retrieve or change the setting applicable to +a jail +.Pq or the host +from within. +They are tagged accordingly in the list below. +.Pp +The indicated default values for per-jail parameters applies to the host. +Those applying to jails are described in the +.Sx Jail Parameters +subsection below. +.Pp +The following knobs are available: .Bl -tag -width indent .It Va security.mac.do.enabled Enable the .Nm policy. -(Default: 1). -.It Va security.mac.do.rules -The list of credential rules, whose syntax is described in the -.Sx CREDENTIALS RULES -section above. -This list is specific to each jail. -Please see the -.Sx JAIL SUPPORT -section below for more details on the interaction of -.Nm -with jails. +.Pq Global. Default: 1. .It Va security.mac.do.print_parse_error Logs a message on trying to set incorrect rules via the .Va security.mac.do.rules .Xr sysctl 8 knob. +.Pq Global. Default: 1. +.It Va security.mac.do.rules +The list of credentials transition rules, whose syntax is described in the +.Sx CREDENTIALS RULES +section above. +An empty string effectively disables the policy. +.Pq Per-jail. Default: Empty. +.It Va security.mac.do.exec_paths +The list of absolute paths +.Pq relative to the current jail's root +to authorized executables, separated by colons +.Pq Ql ":" . +Only processes launched from these executables are considered by the +.Nm +policy. +An empty string effectively disables the policy. +.Po +Per-jail. Default: +.Ql "/usr/bin/mdo" . +.Pc .El -.Sh JAIL SUPPORT +.Ss Jail Parameters +Most parameters of .Nm -supports per-jail configuration of rules. +are per-jail +.Po +see the +.Sx "Sysctl Knobs" +subsection above +.Pc . +Those that are per-jail have corresponding jail parameters that can be used to +set their initial values on jail creation or modify their values in a running +jail from outside the jail. .Pp -By default, at creation, a new jail has no credentials rules, effectively -disabling +By default, as it is for the host, a new jail has .Nm -for its processes. +disabled for its processes, as if the +.Va mac.do +parameter below was explicitly set to +.Ql disable . .Pp -The following jail parameters are defined: +Each unspecified parameter other than +.Va mac.do +defaults to a copy of its value in the currently applicable configuration for +a running jail, or from the parent jail on jail creation. +.Pp +The following jail parameters are available: .Bl -tag -width indent .It Va mac.do Possible values are: +.Pp .Bl -tag -width "'disable'" -compact .It Ql new .Nm -will enforce specific credential rules in the jail. -The -.Va mac.do.rules -jail parameter must also be set in this case. +will use a specific configuration for the jail. +This case degrades to +.Ql disable +if one of the other jail parameters end up empty after applying the default +values rule +.Pq see the preamble . .It Ql disable Disables .Nm in the jail. -Strictly equivalent to jail creation's default behavior and to setting the rules -to an empty string. +This is achieved by ensuring that at least one of the +.Va mac.do.rules +and +.Va mac.do.exec_paths +jail parameters are empty. +If none of them ends up empty after applying the default values rule +.Pq see the preamble , +.Va mac.do.rules +is forced to an empty value. +An explicit +.Ql disable +is incompatible with explicit non-empty values for all other jail parameters and +will trigger an error. .It Ql inherit -The jail's credentials rules are inherited from the jail's parent +The other per-jail parameters are inherited from those applicable to the jail's +parent .Pq which may themselves have been inherited . -Modified rules propagate to all children jails configured for inheritance. +Configuration modifications immediately propagate to all descendant jails +configured for inheritance +.Po +as long as there is no intervening jail having its own specific configuration +.Pc . .El +.Pp +The default value depends on the absence or presence and value of the other jail +parameters. +As soon as one of the latter is present and not empty, the default value is +.Ql new , +else it is +.Ql disable . +Inheritance is never established implicitly, it must be explicitly requested. .It Va mac.do.rules The credentials rules for the jail. -It is always equal to the value that can be retrieved by the +See the description of the corresponding .Xr sysctl 8 knob .Va security.mac.do.rules -described in section -.Sx RUNTIME CONFIGURATION . -If set, and the jail parameter -.Va mac.do -is not so explicitly, the value of the latter will default to -.Ql disable -if empty, else to -.Ql new . +in subsection +.Sx "Sysctl Knobs" +above. +See also the preamble for the default values rule. +.It Va mac.do.exec_paths +The authorized executables. +See the description of the corresponding +.Xr sysctl 8 +knob +.Va security.mac.do.exec_paths +in subsection +.Sx "Sysctl Knobs" +above. +See also the preamble for the default values rule. .El +.Ss Consistency +Values read or set from jail parameters are always consistent with their +corresponding +.Xr sysctl 8 +knobs, effectively operating on the same internal +.Dq variable . .Pp -Each jail must have -.Xr mdo 1 -installed at path -.Pa /usr/bin/mdo , -as this path is currently not configurable. +All accesses to some parameter or some jail configuration as a whole, whether +a read or a modification, are sequentially consistent. +In other words, they appear to be atomic, and all threads see them happening in +the same order. .Sh EXAMPLES Here are several examples of single rules matching processes having a real user ID of 10001: @@ -405,6 +501,7 @@ current supplementary groups must be kept. .Sh AUTHORS .An Olivier Certner Aq Mt olce@FreeBSD.org .An Baptiste Daroussin Aq Mt bapt@FreeBSD.org +.An Kushagra Srivastava Aq Mt kushagra1403@gmail.com .Sh BUGS Currently, .Nmhome | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?6a19b879.34041.444d4be8>