From nobody Tue Jul 16 10:10:32 2024 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4WNZZc4fmVz5R17f for ; Tue, 16 Jul 2024 10:10:32 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4WNZZc43Gdz58qq; Tue, 16 Jul 2024 10:10:32 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1721124632; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=5XUzgSpvYy5Uqt+Z/fLb2VM11Q0nYBdd0JtBtZEKpI8=; b=i2nxHQdkxnjzXnhtgtocsUzf2KWwWo9dcrkluDoQKXX3XoBSfXFhLWo32Zhkjaz0DK8g/Q +rlmfRwJfq0sCb85+qvEL2FpkXdbtRHzvvWT/T8dGQ/kNa+IzGOA/897zJUz0eDHU4hr0x KHpxpk7rETHh/fY5AwtFPEFJYC92ZmvsN37hyCjZurhSP6qT/I/wCAu5/qedvlYLyPlESP r3LvYoc0RExN2BKideUwUY7QAVlrx/IspjT+y/WlBdEfIlsSG0T0+9GWJXMcdGNk4EXRrz 8dRayWVAep3SBvROFF7tMH3Ya4tm7ZQrsWO/Ba1bhPq1oU8qqWnH/O6iag+w+w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1721124632; a=rsa-sha256; cv=none; b=m5NONihkK/Ufs5VBbuhJb8oqv9N3HY+a0gneImmQpG7iqbzupqMKsxRd+/efg0t5pTf+qb BTTHIU8tocbYFqcORJdecwoozcIzVTR4HK2BGhg1hpySJosXCG6y3ANS7MZUDv0Nai9hWP rvS8a5zTIEmmxY25XiHzw4K2Izn2yhmeg/u1he26S3PXGAH+zVr44rWUhUAz7GihVmoug1 z6ImrQ+khK7hdPphafTwPnJESCgswvLff7A2YoceNGLDMbVcb98Ty7ML74Wfb/1AosOAax QuYG6MkSFLMDJWRlTRjHu60RTRER3y9bPvWlOGMpeHOkhFf1KmsLREfJjHe4Jw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1721124632; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=5XUzgSpvYy5Uqt+Z/fLb2VM11Q0nYBdd0JtBtZEKpI8=; b=QEOAzW6Z1jGIVNVhtV/F5s7E0XHewG9MxgA08N48ztGbtrRuHwBtsCGpgQvxrdVcRYyMTX vzCjSlVnnogjJ87mYlv0j/nINT1LVjO9TowrHkH3E3760BZx1uqr2636dS+CZo6V5UeFua n/8e0MbBp7gUZWoTDTalAEnk1CQuZk9dFMrvHq5UiHO72LlEfTiRrgFJLhfxP1Z+ARTUd+ lxeDUpGjPVA1C9ZT8V6rmLWt9s3kMwf9Pk9ekO+EePSAeczDv8bqO8tDnivzMzNe+MwkPp onotQ4ex9UI5NKFzKAD+dloL3mnQ642GKyge3TRhATTWhrgHdchd4kRw1hZ8uQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4WNZZc3XcLzXZV; Tue, 16 Jul 2024 10:10:32 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 46GAAWj7055838; Tue, 16 Jul 2024 10:10:32 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 46GAAWbI055835; Tue, 16 Jul 2024 10:10:32 GMT (envelope-from git) Date: Tue, 16 Jul 2024 10:10:32 GMT Message-Id: <202407161010.46GAAWbI055835@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Alexander Leidinger Subject: git: e9bc86f962 - main - rc scripting article: file naming convention and "instancing" List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: netchild X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: e9bc86f962c2f68329211cd7e27738066f399a69 Auto-Submitted: auto-generated The branch main has been updated by netchild: URL: https://cgit.FreeBSD.org/doc/commit/?id=e9bc86f962c2f68329211cd7e27738066f399a69 commit e9bc86f962c2f68329211cd7e27738066f399a69 Author: Alexander Leidinger AuthorDate: 2024-07-16 10:07:03 +0000 Commit: Alexander Leidinger CommitDate: 2024-07-16 10:10:29 +0000 rc scripting article: file naming convention and "instancing" - emphasize the file naming convention and why - add a section about "instancing" Reviewed by: Pau Amma (doc/english bits) Differential Revision: https://reviews.freebsd.org/D45897 --- .../content/en/articles/rc-scripting/_index.adoc | 105 ++++++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) diff --git a/documentation/content/en/articles/rc-scripting/_index.adoc b/documentation/content/en/articles/rc-scripting/_index.adoc index 6511be73a4..21a7eb4d68 100644 --- a/documentation/content/en/articles/rc-scripting/_index.adoc +++ b/documentation/content/en/articles/rc-scripting/_index.adoc @@ -185,7 +185,9 @@ That is, each [.filename]#rc.d# script _must_ set `name` before it calls man:rc. Now it is the right time to choose a unique name for our script once and for all. We will use it in a number of places while developing the script. -For a start, let us give the same name to the script file, too. +The content of the name variable needs to match the script name, +some parts of FreeBSD (e.g. <> and the cpuset feature of the rc framework) depend upon this. +As such the filename shall also not contain characters which may be troublesome in scripting (e.g. do not use a hyphen "-" and others). [NOTE] ==== @@ -906,6 +908,107 @@ 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-instancing]] +== Advanced rc-scripting: Instancing + +Sometimes it is useful to run several instances of a service. +Typically you want ot be able to start/stop such instances independently, +and you want to have a separate config file for each instance. +Each instance should be started at boot, +survive updates, +and benefit from updates. + +Here is an example of a rc script which supports this: + +[.programlisting] +.... +#!/bin/sh + +# +# PROVIDE: dummy +# REQUIRE: NETWORKING SERVERS +# KEYWORD: shutdown +# +# Add these following line to /etc/rc.conf.local or /etc/rc.conf +# to enable this service: +# +# dummy_enable (bool): Set it to YES to enable dummy on startup. +# Default: NO +# dummy_user (string): User account to run with. +# Default: www +# + +. /etc/rc.subr + +case $0 in <.> +/etc/rc*) + # during boot (shutdown) $0 is /etc/rc (/etc/rc.shutdown), + # so get the name of the script from $_file + name=$_file + ;; +*) + name=$0 + ;; +esac + +name=${name##*/} <.> +rcvar="${name}_enable" <.> +desc="Short description of this service" +command="/usr/local/sbin/dummy" + +load_rc_config "$name" + +eval "${rcvar}=\${${rcvar}:-'NO'}" <.> +eval "${name}_svcj_options=\${${name}_svcj_options:-'net_basic'}" <.> +eval "_dummy_user=\${${name}_user:-'www'}" <.> + +_dummy_configname=/usr/local/etc/${name}.cfg <.> +pidfile=/var/run/dummy/${name}.pid +required_files ${_dummy_configname} +command_args="-u ${_dummy_user} -c ${_dummy_configfile} -p ${pidfile}" + +run_rc_command "$1" +.... + +➊ and ➋ make sure to set the name variable to the man:basename[1] of the script name. +If the filename is [.filename]#/usr/local/etc/rc.d/dummy#, +name is set to [.filename]#dummy#. +This way changing the filename of the rc script changes automatically the content of the name variable. + +➌ specifies the variable name which is used in [.filename]#rc.conf# to enable this service based upon the filename of this script. +In this example this resolves to dummy_enable. + +➍ makes sure the default for the _enable variable is NO. + +➎ is an example of having some defaults for service specific framework variables, +in this case the service jails options. + +➏ and ➐ set variables internal to the script (pay attention to the underscore in front of _dummy_user to make it different from dummy_user which can be set in [.filename]#rc.conf#). + +The part in ➎ is for variables which are not used inside the script itself but in the rc framework. +All the variables which are used as parameters somewhere in the script are assigned to a generic variable like in ➐ to make it more easy to reference them (no need to eval them at each place of use). + +This script will now behave differently if the start script has a different name. +This allows to creaty symlinks to it: + +[source,shell] +.... +# ln -s dummy /usr/local/etc/rc.d/dummy_foo +# sysrc dummy_foo_enable=YES +# service dummy_foo start +.... + +The above creates an instance of the dummy service with the name dummy_foo. +It does not use the config file [.filename]#/usr/local/etc/dummy.cfg# but the config file [.filename]#/usr/local/etc/dummy_foo.cfg# (➐), +and it uses the PID file [.filename]#/var/run/dummy/dummy_foo.pid# instead of [.filename]#/var/run/dummy/dummy.pid#. + +The services dummy and dummy_foo can be managend indepently of each other, +while having the start script update itself on package update (due to the symlink). +This does not update the REQUIRE line, +as such there is no easy way of depending on a specific instance. +To depend upon a specific instance in the startup order a copy needs to be made instead of using a symlink. +This prevents the automatic pick-up of changes to the start script when an update is installed. + [[rcng-furthur]] == Further reading