troubleshoot_apt_news_security_confinement.md: wip

dev-docs/howtoguides/troubleshoot_apt_news_security_confinement.md

@@ -0,0 +1,87 @@
+# How to troubleshoot apt_news security confinement
+
+The `apt-news` service uses two types of security confinements:
+  - systemd isolation features
+  - apparmor profile
+
+These security features restrict what the service can do on the system, and it's quite common that an application faced with unexpected permission denied errors, or unavailability of resources, will just crash, or behave unexpectedly.
+
+If you suspect the security confinement might be impacting the `apt-news` service, here are some troubleshooting tips.
+
+## Panic: disable everything
+
+To completely remove the security features and make sure they are or are not the cause of the problem you are troubleshooting, do the following:
+
+1. Edit `/lib/systemd/system/apt-news.service` and remove or comment the `AppArmorProfile` line, and the security isolation lines. Here is what the minimal version of that file should look like:
+```
+  [Unit]
+  Description=Update APT News
+
+  [Service]
+  Type=oneshot
+  ExecStart=/usr/bin/python3 /usr/lib/ubuntu-advantage/apt_news.py
+```
+
+2. Reload the systemd units:
+
+```
+  sudo systemctl daemon-reload
+```
+
+3. Use the service and observe if the problem you are troubleshooting is still there. If it's still there, then the security features are not the cause.
+
+
+
+## Troubleshooting Apparmor
+
+The Apparmor profile for the `apt-news` service is loaded via the `AppArmorProfile` directive in the unit file `/lib/systemd/system/apt-news.service`:
+```
+  [Service]
+  ...
+  AppArmorProfile=ubuntu_pro_apt_news
+```
+
+This will apply the specified apparmor profile on service startup. If the profile does not exist, the service startup will fail. The actual profile is located in `/etc/apparmor.d/ubuntu_pro_apt_news`, and is loaded into the kernel at package install/upgrade time, or when the system boots.
+
+To verify if the Apparmor profile is causing the issues you are observing, the first troubleshooting attempt should be to put it in "complain" mode. In that mode, it will allow everything, but log if something would have been blocked had the profile been in "enforce" mode.
+
+To place the profile in complain mode, first install the `apparmor-utils` package, if it's not installed already:
+```
+  sudo apt install apparmor-utils
+```
+
+Then run this command:
+```
+  sudo aa-complain /etc/apparmor.d/ubuntu_pro_apt_news
+```
+
+This will both change the profile file to include the `complain` flag, and reload it into the kernel.
+
+Next, keep an eye on the `dmesg` output with something like this:
+```
+sudo dmesg -wT | grep -E 'apparmor=\".*(profile=\"ubuntu_pro_|name=\"ubuntu_pro_)'
+```
+
+And exercise the service. For example, to be sure it will run, first remove some files:
+```
+sudo rm -rf /var/lib/apt/periodic/update-success-stamp /run/ubuntu-advantage /var/lib/ubuntu-advantage/messages/*
+```
+
+And then start the service:
+```
+sudo systemctl start apt-news.service
+```
+
+If you see any logs with `ALLOWED` in them, then that action is something that would have been blocked by the apparmor profile had it not been in "complain" mode, and is something you should add to the apparmor profile.
+
+To make changes to the apparmor profile, edit the `/etc/apparmor.d/ubuntu_pro_apt_news` file, save, and reload the profile with the following command:
+```
+sudo apparmor_parser -r -W -T /etc/apparmor.d/ubuntu_pro_apt_news
+```
+
+Explaining the full syntax of the apparmor profiles is out of scope for this document. You can find more information in the [apparmor.d manpage](https://manpages.ubuntu.com/manpages/noble/man5/apparmor.d.5.html). The Ubuntu Server Guide also has a good introduction on the topic in the [Security - AppArmor](https://ubuntu.com/server/docs/security-apparmor) page.
+
+ATTENTION: be mindful of the differences in Ubuntu Releases regarding the apparmor profile syntax!
+
+
+### Deactivating