Repository navigation
Explicitly document in openrc-run(8) man page that service scripts must be POSIX sh #1067
Description
Currently, the openrc-run(8) man page doesn't explicitly state what shell flavour is acceptable in service scripts. The closest it comes is referencing sh(1p) in SEE ALSO.
Given that there are many common shell constructs which aren't actually POSIX - cf. the "Shell/Scripting" page on the Gentoo wiki - i feel it's important to note that scripts currently must be POSIX sh (although #288, opened in 2019 and last updated with the "enhancement" label at the start of 2023, discusses adding support for them to be in Bash). In the absence of this information, people might end up mystified when they write service scripts that 'should' work but somehow don't.
To give a concrete example of people assuming service scripts can be written in Bash, a contributor has just added a script for a Docker user service to the wiki, and in doing so, has specified that its lang is bash. (And, side note, i'll be suggesting to that person that they contribute that script to the Docker ebuild.)
EDIT: i've just noticed that service-script-guide.md says:
Service scripts are shell scripts. OpenRC aims at using only the standardized POSIX sh subset for portability reasons. The default interpreter (build-time toggle) is /bin/sh, so using for example mksh is not a problem.
That seems to me to imply that #288 has actually been implemented? But regardless, this suggests to me that the openrc-run(8) man page should be built based on what interpreter has been chosen for the build, so that e.g. users on Gentoo, where the default interpreter is used, will get a man page for openrc-run(8) that starts with something like:
openrc-run is basically an interpreter for shell scripts which provides an easy interface to the often complex system commands and daemons. On this system, OpenRC has been built with /bin/sh (POSIX shell) as the interpreter for service scripts.
When a service runs a command it first ...
where "POSIX sh" is explicitly mentioned, rather than just "/bin/sh", because otherwise it doesn't necessarily convey what constructs can and can't be used to anyone who isn't regularly writing shell.
Activity
[-]Explicitly document that service scripts must be POSIX sh[/-][+]Explicitly document in openrc-run(8) man page that service scripts must be POSIX sh[/+]meoovv commentedon Sep 27, 2026
afaiu, discussion in #288 is about officially supporting usecase of specifying any shell(not just providing ability to do so), including support for changing interpreter at runtime on a per-service basis.
not to mention that strict posix sh isnt manadatory for openrc itself - if your system's /bin/sh doesnt break openrc's shell scripts, you can use all of it's abilities, so mentioning posix would only be appropriate in the upstreaming section of service-writing guide.
maybe a note mentioning that /bin/sh is usually a POSIX sh implementation would be helpful.
the most popular /bin/sh is
(d)ashand not "pure posix" shells, though.flexibeast commentedon Sep 27, 2026
@meoovv:
Sorry, i'm not sure i'm following. Let me ask this.
When i write a service script, and assuming OpenRC's "out of the box" defaults, what shell syntax will the interpreter be expecting? Or to put it another way: out of the box, what's OpenRC's default interpreter?
meoovv commentedon Sep 28, 2026
openrc’s default interpreter is /bin/sh, which points to different shells on different distributions: arch uses bash, debian uses dash (an ash fork), and alpine uses busybox ash.
in most cases, you should adhere to the posix standard. however, documenting POSIX syntax as the default makes no sense, as this simply isnt true, shells vary across distros, and in practice, you’re more likely to face
ashrather than a pure posix shell on linux and bsd. POSIX should be mentioned in the service-writing guide.flexibeast commentedon Sep 28, 2026
(As some background, i'm quite familiar with shells; i'm the creator and primary maintainer of the "Shell/Scripting" page on the Gentoo wiki.)
Okay, thank you. So then the openrc-run(8) man page should open with something like:
navi-desu commentedon Sep 28, 2026
it expects /bin/sh to be a posix shell, as that has to interpret openrc's shell bits as well as the init script, and any recommendation or documentation we give should be in posix-shell land
but users are ofc free to use shells that extend posix sh in their personal scripts, if they feel so inclined -- distros should avoid that
i'll probably add some of this to #1092 since that's already a pr going
thesamesam commentedon Sep 28, 2026
Indeed. What matters is what OpenRC's contract requires, and that's POSIX shell (and this is important for people writing init scripts to know, a distro can ofc allow extensions if it wants).