git: 8f4754a9a6 - main - rc services: add docs for automatic service jails (new in 15-current) Reviewed by: bcr, fernape Differential Revision: https://reviews.freebsd.org/D42779
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Wed, 22 May 2024 13:42:02 UTC
The branch main has been updated by netchild:
URL: https://cgit.FreeBSD.org/doc/commit/?id=8f4754a9a6ee8f2503cfb68d14afa99b17729e7f
commit 8f4754a9a6ee8f2503cfb68d14afa99b17729e7f
Author: Alexander Leidinger <netchild@FreeBSD.org>
AuthorDate: 2024-05-22 13:39:29 +0000
Commit: Alexander Leidinger <netchild@FreeBSD.org>
CommitDate: 2024-05-22 13:39:29 +0000
rc services: add docs for automatic service jails (new in 15-current)
Reviewed by: bcr, fernape
Differential Revision: https://reviews.freebsd.org/D42779
---
.../content/en/articles/rc-scripting/_index.adoc | 75 ++++++++++++++++++++++
.../content/en/books/handbook/config/_index.adoc | 2 +
.../content/en/books/handbook/jails/_index.adoc | 67 +++++++++++++++++++
3 files changed, 144 insertions(+)
diff --git a/documentation/content/en/articles/rc-scripting/_index.adoc b/documentation/content/en/articles/rc-scripting/_index.adoc
index cdfa656e53..6511be73a4 100644
--- a/documentation/content/en/articles/rc-scripting/_index.adoc
+++ b/documentation/content/en/articles/rc-scripting/_index.adoc
@@ -831,6 +831,81 @@ That is, arguments with embedded whitespace may not be processed correctly.
The bug stems from `$*` misuse.
====
+[[rcng-service-jails]]
+== Making a script ready for Service Jails
+
+Scripts which start a long running service are suitable for service jails, and should come with a suitable service jail configuration.
+
+Some examples of scripts which are not suitable to run in a service jail:
+
+* any script which in the start command only changes a runtime setting for programs or the kernel,
+* or tries to mount something,
+* or finds and deletes files
+
+Scripts not suitable to run in a service jail need to prevent the use within service jails.
+
+A script with a long running service which needs to do something listed above before the start or after the stop, can either be split-up into two scripts with dependencies, or use the precommand and postcommand parts of the script to perform this action.
+
+By default, only the start and stop parts of a script are run within a service jail, the rest is run outside the jail.
+As such any setting used in the start/stop parts of the script can not be set from e.g. a precommand.
+
+To make a script ready for use with extref:../../books/handbook/jails/#service-jails[Service Jails], only one more config line needs to be inserted:
+
+[.programlisting]
+....
+#!/bin/sh
+
+. /etc/rc.subr
+
+name="dummy"
+start_cmd="${name}_start"
+stop_cmd=":"
+
+: ${dummy_svcj_options:=""} <.>
+
+dummy_start()
+{
+ echo "Nothing started."
+}
+
+load_rc_config $name
+run_rc_command "$1"
+....
+
+➊ If it makes sense that the script runs in a jail, it must have an overridable service jails configuration.
+If it does not need network access or access to any other resource which is restricted in jails, an empty config like displayed is enough.
+
+Strictly speaking an empty config is not needed, but it explicitly describes that the script is service jails ready, and that it does not need additional jail permissions.
+As such it is highly recommended to add such an empty config in such a case.
+The most common option to use is "net_basic", which enables the use of the hosts IPv4 and IPv6 addresses.
+All possible options are explained in man:rc.conf[5].
+
+If a setting for the start/stop depends on variables from the rc-framework (e.g. set inside man:rc.conf[5]), this needs to be handled by ``load_rc_config`` and ``run_rc_command`` instead of inside a precommand.
+
+If for some reason a script can not be run within a service jail, e.g. because it is not possible to run or it does not make sense to run it in a jail, use the following:
+
+[.programlisting]
+....
+#!/bin/sh
+
+. /etc/rc.subr
+
+name="dummy"
+start_cmd="${name}_start"
+stop_cmd=":"
+
+dummy_start()
+{
+ echo "Nothing started."
+}
+
+load_rc_config $name
+dummy_svcj="NO" # does not make sense to run in a svcj <.>
+run_rc_command "$1"
+....
+
+➊ The disabling needs to happen after the ``load_rc_config`` call, else a man:rc.conf[5] setting may override it.
+
[[rcng-furthur]]
== Further reading
diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc
index 2e77ef70bf..ee25617ad0 100644
--- a/documentation/content/en/books/handbook/config/_index.adoc
+++ b/documentation/content/en/books/handbook/config/_index.adoc
@@ -434,6 +434,8 @@ For instance, to start package:www/nginx[] regardless of the current [.filename]
....
====
+It is also possible to put a service automatically into a jail, see the corresponding crossref:jails[service-jails,Service Jails] explanation.
+
[[configtuning-status-services]]
=== Status of a Service
diff --git a/documentation/content/en/books/handbook/jails/_index.adoc b/documentation/content/en/books/handbook/jails/_index.adoc
index bf17248179..9465c4dccc 100644
--- a/documentation/content/en/books/handbook/jails/_index.adoc
+++ b/documentation/content/en/books/handbook/jails/_index.adoc
@@ -137,6 +137,30 @@ Disadvantages of Thin Jails:
* Dependency Conflicts: If multiple thin jails require different versions of the same libraries or software, managing dependencies can become complex. In some cases, this might require additional effort to ensure compatibility.
* Compatibility Challenges: Applications within a thin jail might encounter compatibility issues if they assume a certain base system environment that differs from the shared components provided by the template.
+[[service-jails]]
+=== Service Jails
+
+A service jail shares the complete filesystem tree directly with the host (the jail root path is [.filename]#/#) and as such can access and modify any file on the host, and shares the same user accounts with the host.
+By default it has no access to the network or other resources which are restricted in jails, but they can be configured to re-use the network of the host and to remove some of the jail-restrictions.
+The use case for service jails is automatic confinement of services/daemons inside a jail with minimal configuration, and without any knowledge of the files needed by such service/daemon.
+Service jails exist since FreeBSD 15.
+
+Advantages of Service Jails:
+
+* Zero Administration: A service jail ready service needs only one config line in [.filename]#/etc/rc.conf#, a service which is not service jails ready needs two config lines.
+* Resource Efficiency: Service jails are more resource efficient than thin jails, as they do not need any additional disk space or network resource.
+* Faster Deployment: Creating and launching service jails is generally faster compared to thin jails if only distinct services/daemons shall be jailed and no parallel instances of the same service/daemon is needed.
+* Shared Resources: Service jails share all resources such as libraries and binaries with the host system. This can potentially lead to more efficient disk caching and improved performance for applications within the jail.
+* Process Isolation: Service jails isolate a particular service, it can not see processes which are not a child of the service jail, even if they run within the same user account.
+
+Disadvantages of Service Jails:
+
+* Reduced Isolation: The primary disadvantage of service jails is that they offer no filesystem isolation compared to thick or thin jails.
+* Security Concerns: The reduced isolation in service jails could pose security risks, as a compromise in one jail might have a greater potential to affect everything on the host system.
+
+Most of the configuration of jails which is discussed below is not needed for service jails.
+To understand how jails work, it is recommended to understand those configuration possibilities. The details about what is needed to configure a service jail is in crossref:jails[service-jails-config, Configuring service jails].
+
[[vnet-jails]]
=== VNET Jails
@@ -867,6 +891,49 @@ The Ubuntu environment can be accessed using the following command:
More information can be found in the chapter crossref:linuxemu[linuxemu,Linux Binary Compatibility].
+[[service-jails-config]]
+=== Configuring Service Jails
+
+A service jail is configured completely via [.filename]#/etc/rc.conf# or man:sysrc[8].
+The base system services are service jails ready.
+They contain a config line which enables networking or lift other restrictions of jails.
+Base system services which do not make sense to run inside jails are configured to not be started as a service jail, even if enabled in [.filename]#/etc/rc.conf#.
+Some examples of such a service are services which want to mount or unmount something in the start of stop method, or only configure something like a route, or firewall, or the like.
+
+Third party services may or may not be service jails ready. To check if a service is service jail ready, the following command can be used:
+
+[source,shell]
+....
+# grep _svcj_options /path/to/rc.d/servicename
+....
+
+If there is no output, the service is not service jail ready, or does not need any additional privileges like e.g. network access.
+
+If the service is not service jail ready, and needs network access, it can be made ready by adding the necessary config to [.filename]#/etc/rc.conf#:
+
+[source,shell]
+....
+# sysrc servicename_svcj_options=net_basic
+....
+
+For all possible `_svcj_options` see the man:rc.conf[5] man-page.
+
+To enable a service jail for a given service, the service needs to be stopped and the `servicename_svcj` variable needs to be set to YES.
+To put man:syslogd[8] into a service jail, use the following sequence of commands:
+
+[source,shell]
+....
+# service syslogd stop
+# sysrc syslogd_svcj=YES
+# service syslogd start
+....
+
+If the `servicename_svcj` variable is changed, the service needs to be stopped before it is changed.
+If it is not stopped, the rc framework will not detect the correct state of the service and will not be able to do what is requested.
+
+Service jails are managed only via man:rc.conf[5]/man:sysrc[8] and the man:service[8] command.
+The jail utilities, like man:jls[8] as described in crossref:jails[jail-management,Jail Management] can be used to investigate the operation, but the man:jail[8] command is not supposed to be used to manage them.
+
[[jail-management]]
== Jail Management