diff --git a/documentation/content/en/articles/rc-scripting/_index.adoc b/documentation/content/en/articles/rc-scripting/_index.adoc --- a/documentation/content/en/articles/rc-scripting/_index.adoc +++ b/documentation/content/en/articles/rc-scripting/_index.adoc @@ -831,6 +831,81 @@ 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 --- a/documentation/content/en/books/handbook/config/_index.adoc +++ b/documentation/content/en/books/handbook/config/_index.adoc @@ -434,6 +434,8 @@ .... ==== +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 --- a/documentation/content/en/books/handbook/jails/_index.adoc +++ b/documentation/content/en/books/handbook/jails/_index.adoc @@ -137,6 +137,30 @@ * 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 @@ 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