From 14f1b6f936f494f6489c66f78c062ccf4ad47dcd Mon Sep 17 00:00:00 2001
From: Eric Callahan <arksine.code@gmail.com>
Date: Sun, 23 Jan 2022 11:34:04 -0500
Subject: [PATCH] docs: update documentation for dbus additions

Signed-off-by:  Eric Callahan <arksine.code@gmail.com
---
 docs/configuration.md | 34 ++++++++++++++++++++++++++
 docs/installation.md  | 55 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)

diff --git a/docs/configuration.md b/docs/configuration.md
index 1c26524..6f95e82 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -80,6 +80,35 @@ enable_object_processing: False
     See the [preprocess-cancellation](https://github.com/kageurufu/cancelobject-preprocessor)
     documentation for details.
 
+### `[machine]`
+
+The `machine` section provides configuration for Moonraker's machine component, which
+is responsible for for collecting "machine" (ie: PC, SBC, etc) data and communicating
+with system services such as systemd.
+
+```ini
+# moonraker.conf
+[machine]
+provider: systemd_dbus
+#   The provider implementation used to collect system service information
+#   and run service actions (ie: start, restart, stop).  This can be "none",
+#   "systemd_dbus", or "systemd_cli".  If the provider is set to "none" service
+#   action APIs will be disabled.  The default is systemd_dbus.
+```
+
+!!! Note
+    See the [install documentation](installation.md#policykit-permissions) for
+    details on PolicyKit permissions when using the DBus provider.
+
+!!! Warning
+    Some distributions (ie: DietPi) disable and mask the `systemd-logind`
+    service.  This service is necessary for the DBus provider to issue
+    `reboot` and `shutdown` commands.  In this scenario, Moonraker will fall
+    back to CLI based `reboot` and `shutdown` commands.  These commands require
+    that Moonraker be able to run `sudo` commands without a password.
+    Alternatively it may be possible to enable the `systemd-logind` service,
+    consult with your distro's documentation.
+
 ### `[database]`
 
 The `database` section provides configuration for Moonraker's lmdb database.
@@ -869,6 +898,11 @@ enable_system_updates: True
 #   that prefer to manage their packages directly.  Note that if this
 #   is set to False users will be need to make sure that all system
 #   dependencies are up to date.  The default is True.
+enable_packagekit: True
+#   This option is available when system updates are enabled via the
+#   "enable_system_updates" option.  When set to True, system package
+#   updates will be processed via PackageKit over D-Bus.  When set to False
+#   the "apt cli" fallback will be used.  The default is True.
 channel: dev
 #   The update channel applied to Klipper and Moonraker.  May be 'dev'
 #   which will fetch updates using git, or 'beta' which will fetch
diff --git a/docs/installation.md b/docs/installation.md
index cf1ff2b..14b0b53 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -185,6 +185,61 @@ These options may be changed by editing
 `/etc/systemd/system/moonraker.service`.  The `install-moonraker.sh` script
 may also be used to modify the config file location.
 
+### PolicyKit Permissions
+
+Some of Moonraker's components require elevated privileges to perform actions.
+Previously these actions could only be run via commandline programs launched
+with the `sudo` prefix.  This has significant downsides:
+
+- The user must be granted `NOPASSWD` sudo access.  Raspberry Pi OS
+  grants the Pi user this access by default, however most other distros
+  require that this be enabled through editing `visudo` or adding files
+  in `/etc/sudoers.d/`.
+- Some linux distributions require additional steps such as those taken
+  in `sudo_fix.sh`.
+- Running CLI programs is relatively expensive.  This isn't an issue for
+  programs that are run once at startup, but is undesirable if Moonraker
+  wants to poll information about the system.
+
+Moonraker now supports communicating with system services via D-Bus.
+Operations that require elevated privileges are authrorized through
+PolicyKit. On startup Moonraker will check for the necessary privileges
+and warn users if they are not available.  Warnings are presented in
+`moonraker.log` and directly to the user through some clients.
+
+To resolve these warnings users have two options:
+
+1) Install the PolicyKit permissions with the `set-policykit-rules.sh` script,
+   for example:
+
+```shell
+cd ~/moonraker/scripts
+./set-policykit-rules.sh
+sudo service moonraker restart
+```
+
+2) Configure Moonraker to use the legacy backend implementations for
+   the `machine` and/or `update_manager` components, ie:
+
+```ini
+# Use the systemd CLI provider rather than the DBus Provider
+[machine]
+provider: systemd_cli
+
+# Disable PackageKit to fallback to the APT CLI Package Update
+# implementation.
+[update_manager]
+enable_packagekit: False
+
+# Alternatively system updates can be disabled
+[update_manager]
+enable_system_updates: False
+```
+
+!!! Note
+    Previously installed PolicyKit rules can be removed by running
+    `set-policykit-rules.sh -c`
+
 ### Retrieving the API Key
 
 Some clients may require an API Key to connect to Moonraker.  After the