Differential D42779 Diff 138445 documentation/content/en/articles/rc-scripting/_index.adoc

Changeset View

Standalone View

documentation/content/en/articles/rc-scripting/_index.adoc

Context not available.
	The bug stems from `$*` misuse.	The bug stems from `$*` misuse.
	====	====

		[[rcng-service-jails]]
		== Making a script ready for Service Jails

		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, is not suitable for a service jail and needs to prevent the use within service jails.
		pauamma_gundo.comUnsubmitted Done Inline Actions s/the use/use/ Also, if you want to point to the service jails section of the jails chapter specifically, s\|handbook\|handbook/jails/#service-jails\| (I think). pauamma_gundo.com: s/the use/use/ Also, if you want to point to the service jails section of the jails chapter…
		fernapeUnsubmitted Done Inline Actions This does not work for me in a `make run`. It gives a 404 because the final link points to http://localhost:1313/en/articles/rc-scripting/handbook/jails/#service-jails instead of http://localhost:1313/en/books/handbook/jails/#service-jails fernape: This does not work for me in a `make run`. It gives a 404 because the final link points to http…
		netchildAuthorUnsubmitted Done Inline Actions I hope this works better. See my comment about what I need to install to test this myself. netchild: I hope this works better. See my comment about what I need to install to test this myself.
		fernapeUnsubmitted Done Inline Actions If you're using `hugo` that's all you need: # The run target uses hugo's built-in webserver to make the documentation site # available for local browsing. The documentation should have been built prior # to attempting to use the `run` target. By default, hugo will start its # webserver on port 1313. fernape: If you're using `hugo` that's all you need: ``` # The run target uses hugo's built-in…
		Scripts which start a long running service are suitable for service jails, and should come with a suitable service jail configuration.
		A script with a long running service which needs to do something before the start or after the stop which is listed as not suitable above, 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

		fernapeUnsubmitted Done Inline Actions This second point (the `<.>`) is never referenced in the text below the code snippet. The first `<.>` is in the `name="dummy"` line, but the text that references the point does not talk about that specific line. Are those numbered bullets intended? fernape: This second point (the `<.>`) is never referenced in the text below the code snippet. The first…
		netchildAuthorUnsubmitted Done Inline Actions First numbered bullet is not needed. The text is for the second. netchild: First numbered bullet is not needed. The text is for the second.
		. /etc/rc.subr

		name="dummy"
		start_cmd="${name}_start"
		stop_cmd=":"

		: ${dummy_svcj_options:=""} <.>

		dummy_start()
		{
		echo "Nothing started."
		pauamma_gundo.comUnsubmitted Done Inline Actions Instead of raw Unicode, use one of the admonition types in https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#admonitions . s/log running/long-running/ s/or tries/tries/ s/shall/must/ s/overidable/overridable/ Also, it's not clear from that sentence as written whether "tries to mount..." and "finds and deletes..." are meant as list items at the same level as "make a config change...". If they are indeed, I'd change the verbs to infinitives ("try", "find", and "delete"). pauamma_gundo.com: Instead of raw Unicode, use one of the admonition types in https://docs.asciidoctor.
		netchildAuthorUnsubmitted Done Inline Actions I used the raw unicode stuff like in other parts of the document. I tried to adhere to the existing style. In the URL you provided, I haven't seen how I can write an (1)-symbol or similar on my keyboard... For the rest: changed locally and waiting for a clarification for the above part. netchild: I used the raw unicode stuff like in other parts of the document. I tried to adhere to the…
		pauamma_gundo.comUnsubmitted Done Inline Actions I used the raw unicode stuff like in other parts of the document. I tried to adhere to the existing style. In the URL you provided, I haven't seen how I can write an (1)-symbol or similar on my keyboard... For the rest: changed locally and waiting for a clarification for the above part. Ah, missed that it was a callout target. Never mind. pauamma_gundo.com: > I used the raw unicode stuff like in other parts of the document. I tried to adhere to the…
		fernapeUnsubmitted Done Inline Actions I feel this sentence is a bit long/complex. I don't know how to simplify it though. What is the conveying idea? fernape: I feel this sentence is a bit long/complex. I don't know how to simplify it though. What is the…
		netchildAuthorUnsubmitted Done Inline Actions What it shall tell is: If it is starting a potentially long-running service -> needs an overridable config. If it only makes a config change -> not suitable for service jails. If it only changes the runtime settings in the kernel -> not suitable for jails. If it tries to mount something -> not suitable for jails. If it only runs find and executes stuff on them -> not suitable for jails. netchild: What it shall tell is: If it is starting a potentially long-running service -> needs an…
		fernapeUnsubmitted Done Inline Actions Probably Service -> service. This applies to all the article and the modification in the handbook. fernape: Probably //Service// -> //service//. This applies to all the article and the modification in…
		}
		bcrUnsubmitted Done Inline Actions I think there is a word missing around the "empty config like" part (line, file?). bcr: I think there is a word missing around the "empty config like" part (line, file?).
		netchildAuthorUnsubmitted Done Inline Actions Is s/empty config like displayed/empty config like above/ better? netchild: Is s/empty config like displayed/empty config like above/ better?

		load_rc_config $name
		run_rc_command "$1"
		....
		fernapeUnsubmitted Done Inline Actions The most common options to use... --> The most common option to use... Also typo explicitely --> explicitly fernape: //The most common options to use...// --> //The most common option to use...// Also typo…

		➊ 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.
		bcrUnsubmitted Done Inline Actions s/shall/should/g bcr: s/shall/should/g
		netchildAuthorUnsubmitted Done Inline Actions In this context: I understand "shall" like "do not run it" (and "you have to use"). I understand "should" like "it doesn't make sense to run it, but if you absolutely want to it would be technically possible", or "you could use this" for the second use. I want to express "do not do that" and "make sure this is included". netchild: In this context: I understand "shall" like "do not run it" (and "you have to use"). I…
		pauamma_gundo.comUnsubmitted Done Inline Actions Suggestion: "If the script is not run in a service jail, e.g. because that's not possible or does not make sense, use the following:" pauamma_gundo.com: Suggestion: "If the script is not run in a service jail, e.g. because that's not possible or…
		netchildAuthorUnsubmitted Done Inline Actions What about this? If a script can not be run within a Service jail, e.g. because it is not possible or it does not make sense to run it in a jail (e.g. short running runtime configuration change), use the following: netchild: What about this? > If a script can not be run within a Service jail, e.g. because it is not…
		fernapeUnsubmitted Done Inline Actions I think this is complex because there are two `e.g.` subsentences, one in parenthesis the other not. This should be simplified. How about `If a script is not intended to be run in a Service Jail, use the following`. fernape: I think this is complex because there are two `e.g.` subsentences, one in parenthesis the other…
		netchildAuthorUnsubmitted Done Inline Actions There is a difference between not intended to be run and not suitable to be run. "I do not intent to, I do not care" is different than "this doesn't make sense". This is supposed to tell "if it doesn't make sense at all" and give examples when it doesn't make sense. netchild: There is a difference between not intended to be run and not suitable to be run. "I do not…
		fernapeUnsubmitted Done Inline Actions The original line expresses two ideas: it can not be executed in a jail doesn't make sense to be executed in a jail Then maybe `if the service is not going to be run in a jail`... The reason doesn't really matter. fernape: The original line expresses two ideas: * it can not be executed in a jail * doesn't make…

		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 load_rc_config and run_rc_command instead of inside a precommand.

		fernapeUnsubmitted Done Inline Actions I think we don't need that numbered bullet. fernape: I think we don't need that numbered bullet.
		If 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

		pauamma_gundo.comUnsubmitted Done Inline Actions Missing }? pauamma_gundo.com: Missing }?
		. /etc/rc.subr

		name="dummy"
		start_cmd="${name}_start"
		stop_cmd=":"

		dummy_start()
		pauamma_gundo.comUnsubmitted Done Inline Actions Use a suitable admonition type here too. pauamma_gundo.com: Use a suitable admonition type here too.
		{
		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]]	[[rcng-furthur]]
	== Further reading	== Further reading

Context not available.