Documentation should not state that user firewall config scripts are executed at every firewall change

[icequbes1]

Qubes OS version
R4.0

Affected component(s) or functionality
Documentation

Brief summary
It appears prior to R4.0, user-created scripts could be populated with extra commands to run upon every update of firewall rules for AppVMs that had qubes-firewall service enabled.

This does not appear to be the case anymore, as:

1. /rw/config/qubes-firewall.d/* scripts are only executed in a qubes-firewall-enabled AppVM when qubes-firewall first runs.
2. /rw/config/qubes-firewall-user-script is only executed in aqubes-firewall-enabled AppVM when qubes-firewall first runs.

This leads to confusion for users manually configuring firewall rules and are relying on the 'executed after every update' statements to be true.

Expected behavior

Users assume their firewall scripts are getting executed upon every firewall change.

Actual behavior

Firewall scripts are only executed once. Any updates to these scripts are not applied unless the firewall AppVM reboots (or a systemctl restart qubes-firewall command).

Additional context

1. Contents of the default /rw/config/qubes-firewall-user-script as created by /usr/lib/qubes/init/setup-rw.sh:

   # This script is called in AppVMs after every firewall update (configuration
   # change, starting some VM etc). This is a good place to write own custom
   # firewall rules, in addition to autogenerated ones. Remember that in most cases
   # you'll need to insert the rules at the beginning (iptables -I) for it to be
   # effective.
   

2. Further documentation stating the use of /rw/config/qubes-firewall-user-script:

   In ProxyVMs (or AppVMs with qubes-firewall service enabled), scripts placed in the following directories will be executed in the listed order followed by qubes-firewall-user-script after each firewall update. Good place to write custom firewall rules.1

   the above iptables rules should be written into firewallVM’s qubes-firewall-user-script script which is run on every firewall update, and A and B’s rc.local script which is run when the qube is launched. The qubes-firewall-user-script is necessary because Qubes orders every firewallVM to update all the rules whenever a new connected qube is started.2

This issue is not a report that user scripts are being ignored - only that trigger for their execution is not properly conveyed to users, which may lead users to have improper assumptions. At worst case, their perceived commands are not executed until the firewall AppVM is restarted if they relied on the commands to execute after performing a firewall rule update.

Solutions you've tried

Remove the idea that these scripts are executed upon every change and documentation matches implementation.

Relevant documentation you've consulted

• https://www.qubes-os.org/doc/config-files/
• https://www.qubes-os.org/doc/firewall/

Related, non-duplicate issues

• qubes-firewall-user-script is ignored #3260
• Document requirements for secure GPU-accelerated rendering #4234

[andrewdavidwong]

It sounds like there is still a question of whether the bug lies in the docs or in the firewall scripts not executing. In other words: which one is the intended behavior: the current behavior, or the behavior described in the docs? CC: @marmarek

[unman]

On Fri, Dec 18, 2020 at 05:22:13PM -0800, Andrew David Wong wrote: It sounds like there is still a question of whether the bug lies in the docs or in the firewall scripts not executing. In other words: which one is the intended behavior: the current behavior, or the behavior described in the docs? CC: @marmarek

The bug is in the docs - the current behaviour is by design.

[andrewdavidwong]

Thanks for the quick answer, @unman.

@icequbes1, would you like to help us fix this by submitting a doc PR?
https://www.qubes-os.org/doc/doc-guidelines/

[icequbes1]

@andrewdavidwong Yes, I will submit a doc PR. In addition to that I will submit a PR against qubes-core-agent-4.0.58 so the commentary accurately reflects when the script will be invoked.

It sounds like there is still a question of whether the bug lies in the docs or in the firewall scripts not executing. In other words: which one is the intended behavior: the current behavior, or the behavior described in the docs? CC: @marmarek

Based on #3260, and more specifically this1 comment from @marmarek, the current behavior matches the design that was stated, so I do not perceive this as a coding bug.

The "bug", if you will, is to address changing existing users' understanding of what should should live in /rw/config/qubes-firewall-user-script and understanding when it is executed. If users believe their script is executed after a firewall change AND the actions taken in the script relied on dynamic rule updates, it would lead to inconsistency as to the state of the firewall.

This issue was opened as I had a qubes-firewall-user-script that would add additional rules to the nftables chains created by qubes-firewall and discovered they were not executing on rule updates, which then led me to #3260 after inspecting the qubes-firewall code. Further analysis led me to believe only qubes-firewall wants to touch the nftables rules and that I should make my changes to iptables rules instead.

Perhaps the ability to execute the script after firewall changes is now an enhancement, but the core of this issue is to ensure current operation is properly conveyed.

[DemiMarie]

@icequbes1 Writing your own nftables rules is fine, since nftables has an unlimited number of tables and you can pick your own names for them.

[icequbes1]

@DemiMarie Yes, however my use case involved modifying rules on the qubes-firewall table - adding some counter and log rules in various positions to pull more state out of what the firewall is doing.

I assumed I could rely on my firewall user script to be executed after the rule updates performed by qubes-firewall. That reliance is due to the fact the chain for each attached qube gets flushed on rule updates.

It would be useful in my case for qubes-firewall to execute something I provide whenever it performs rule updates, but this behavior is separate from the original stated purpose of qubes-firewall-user-script1:

The qubes-firewall-user-script is necessary because Qubes orders every firewallVM to update all the rules whenever a new connected qube is started.

[qubesos-bot]

Automated announcement from builder-github

The package core-agent-linux has been pushed to the r4.1 testing repository for the CentOS centos8 template.
To test this update, please install it with the following command:

sudo yum update --enablerepo=qubes-vm-r4.1-current-testing

Changes included in this update

[qubesos-bot]

Automated announcement from builder-github

The package qubes-core-agent_4.1.19-1 has been pushed to the r4.1 testing repository for the Debian template.
To test this update, first enable the testing repository in /etc/apt/sources.list.d/qubes-*.list by uncommenting the line containing buster-testing (or appropriate equivalent for your template version), then use the standard update command:

sudo apt-get update && sudo apt-get dist-upgrade

Changes included in this update

[qubesos-bot]

Automated announcement from builder-github

The component core-agent-linux (including package python2-dnf-plugins-qubes-hooks-4.1.19-1.fc32) has been pushed to the r4.1 testing repository for the Fedora template.
To test this update, please install it with the following command:

sudo yum update --enablerepo=qubes-vm-r4.1-current-testing

Changes included in this update

[qubesos-bot]

Automated announcement from builder-github

The package qubes-core-agent_4.1.24-1+deb10u1 has been pushed to the r4.1 stable repository for the Debian template.
To install this update, please use the standard update command:

sudo apt-get update && sudo apt-get dist-upgrade

Changes included in this update

[qubesos-bot]

Automated announcement from builder-github

The package core-agent-linux has been pushed to the r4.1 stable repository for the CentOS centos8 template.
To install this update, please use the standard update command:

sudo yum update

Changes included in this update

[qubesos-bot]

Automated announcement from builder-github

The component core-agent-linux (including package python2-dnf-plugins-qubes-hooks-4.1.24-1.fc32) has been pushed to the r4.1 stable repository for the Fedora template.
To install this update, please use the standard update command:

sudo yum update

Changes included in this update