Firewall documentation: Mention that /rw/config/qubes-firewall-user-script must start with #!/bin/sh

[yourcase]

Clarification on firewall user script documentation

Firewall documentation mentions that /rw/config/qubes-firewall-user-script should be executable, but doesn't mention that the script must start with #!/bin/sh. Failure to do so ends up in the qubes-firewall service terminating prematurely, subsequently leading to a misconfigured firewall.

Suggested solution

Next to mentioning that the script should be executable, also mention that it should start with the hashbang.

The value to a user, and who that user might be

A user that might have written /rw/config/qubes-firewall-user-script from a new file, like myself, may overlook adding that line, like I did.

Completion criteria checklist

(This section is for developer use only. Please do not modify it.)

[jamke]

Is it really limited to shell script? Can qubes-firewall-user-script be a binary executable theoretically?
If not limited, then there seems to be no problem in docs. If you want to make executable from a text file, you have to add shebang and provide chmod permission to run, it's like everywhere else, isn't it?

[yourcase]

Indeed from the source code (os.posix_spawn) I presume it can be a binary executable in theory.

On the other hand, an executable text file as far as I can see is executable from the command line without the shebang, which gave me the impression that my firewall user script was fine when it was not:

[user@sys-firewall ~]$ echo "echo bla" > testme
[user@sys-firewall ~]$ chmod u+x testme
[user@sys-firewall ~]$ ./testme
bla

I wasn't educated enough to know that an executable textfile is always required to start with a shebang, (fooled by the above bash situation). I can see your point that you can't go and make that remark all through your docs for every user-created executable script, I'll close the issue.

[jamke]

@yourcase great reply accepting and addressing the situation properly from you, thank you.

P.S. About your example (that caused confusion) that text file with shell/bash code can be executed even without shebang: it's because you execute it inside shell/bash, so the logic can be a bit different from general execution with os.posix_spawn or other ways.