Handbook / rc-article update for Service Jails

[netchild]

Summary

Depends upon:
https://reviews.freebsd.org/D40370
https://reviews.freebsd.org/D40371

This is not tested at all. First step is to get the content correct and understandable. Not sure if I used the correct extref, if it can be more drilled down (pointing to the jails chapter), and I'm not sure about the markup I deducted from looking at the surroundings.

[carlavilla]

Thanks for that, I'll take a look this night to the changes.

[bcr]

You can also run vale on your doc to get some helpful output.

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

861

I think there is a word missing around the "empty config like" part (line, file?).

868

s/shall/should/g

documentation/content/en/books/handbook/jails/_index.adoc

143

s/Service/service/g

148

Is this a section heading?

894

s/Basesystem/Base system/

915

s/So//
s/can be used/Use the following sequence/ (active voice)

[netchild]

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

861

Is s/empty config like displayed/empty config like above/ better?

868

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".

documentation/content/en/books/handbook/jails/_index.adoc

148

No. It is a list like for Thick Jails and Thin Jails in the existing text above.

[netchild]

documentation/content/en/books/handbook/jails/_index.adoc

143

I tried to match the style of the existing Thick Jails and Thin Jails above this new part. I may have not understood when to use the uppercase "Thick jail" vs. the "thick jail" part... Can you give me a hint before I blindly lowercase "Service" in the middle of a sentence?

[pauamma_gundo.com]

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

837

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).

860

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").

868

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:"

882

Missing }?

889

Use a suitable admonition type here too.

documentation/content/en/books/handbook/config/_index.adoc

437

s/There is also the possibility/It is also possible/

documentation/content/en/books/handbook/jails/_index.adoc

892

s/basesystem/base system/ here too.

[netchild]

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

860

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.

868

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]

Address issues from comments.

[pauamma_gundo.com]

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

860

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.

[fernape]

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

837

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

849

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?

860

I feel this sentence is a bit long/complex. I don't know how to simplify it though. What is the conveying idea?

860

Probably Service -> service. This applies to all the article and the modification in the handbook.

865

The most common options to use... --> The most common option to use...

Also typo explicitely --> explicitly

868

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.

876

I think we don't need that numbered bullet.

documentation/content/en/books/handbook/config/_index.adoc

437

This crossref points to http://localhost:1313/en/books/handbook/jail/#service-jails when it should point to http://localhost:1313/en/articles/rc-scripting/#rcng-service-jails

documentation/content/en/books/handbook/jails/_index.adoc

145

Something to change the use of jailing as a verb (which is repetitive with regards to service jail):

The use case for service jails is automatic jailing... --> The use case for service jails is automatic confinement of services/daemons inside a jail...

The last part does not read very clear to me: with the least amount of configuration refers to the jail, but in the middle there is information about needed files...

How about:

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.

149

This list does not render properly. A blank line between the above line an the first bullet is needed (I did not test it). You can run make run and visit the local doc set to do some proofreading.

150

Service --> service and then Thin --> thin for consistency.

894

Very long line with many examples in the middle of the sentence. How about:

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 servicew 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.

Also typo someting/ --> something//

896

3rd --> Third

905

Typo neccessary --> necessary

912

_svcj_options --> _svcj_options (to signal this is "code" text and not "normal" text).

924

Try to avoid the use of you. Use the passive voice here.

928

This crossref points to http://localhost:1313/en/books/handbook/jail/#jail-management while it should point to http://localhost:1313/en/books/handbook/jails/#jail-management (note the jail --> jails in the URL). These are easily caught with make run :-)

[netchild]

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

849

First numbered bullet is not needed. The text is for the second.

860

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.

868

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.

documentation/content/en/books/handbook/config/_index.adoc

437

This is supposed to stay in the handbook. It shall link to the added part below. The link looks correct as is.

documentation/content/en/books/handbook/jails/_index.adoc

149

I more or less copy&pasted what was above. There are no blank lines either. Do you have a reference to which ports/packages I need to install to be able to "make run".

150

Done... but all the existing parts around it use uppercase versions of Thick/Thin...

[netchild]

Address comments in the review.

[netchild]

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

837

I hope this works better. See my comment about what I need to install to test this myself.

[fernape]

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

837

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.

868

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.

documentation/content/en/books/handbook/config/_index.adoc

437

The link gave a 403. Can you check with make run?

documentation/content/en/books/handbook/jails/_index.adoc

149

Just hugo.

[fernape]

documentation/content/en/books/handbook/config/_index.adoc

437

Scratch that. The link works fine. Sorry for the noise.

[netchild]

I have reworded the rc-scripting part. Does this make it more easy / clear?

[fernape]

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

9

This is clearer, thanks!

I would like to suggest some changes.

Since the title is "Making a script ready for Service Jails", move the sentence in line 8 at the begining, i.e start by identifying what a script suitable for a service jail looks like.
The sentence in line 7 is lengthy. Can we convert it in an actual bullet list? Something like:
Some examples of scripts that are not suitable to run in a service jail are:

• Example 1
• Example 2

...
Then, the sentence in line 9 fits nicely when it says ... which is listed above.... I would just simplify it to:
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.

45

this needs to be handled *by*/*in*...

Also formatting of the names of load_rc_config and run_rc_command

47

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... --> If for some reason a script can not be run within a service jail...

We have already given plenty of examples of why a script might not be possible to run.

[netchild]

Fix issues outlined in the reviews (links are ok now, lists are rendered correctly, ...) and some minor change in phrasing.

[netchild]

Address the last big comment from @fernape .

[bcr]

Looks good to me, thanks!

[fernape]

LGTM too.

Thank you very much for the work in writing this up and addressing the requests for change.