Improve documentation

Co-authored-by: Cory Francis Myers <[email protected]>
freedomofpress · Jan 28, 2025 · 6c8f3b4 · 6c8f3b4
1 parent 87d6e1a
commit 6c8f3b4
Show file tree

Hide file tree

Showing 3 changed files with 7 additions and 9 deletions.
diff --git a/noble-migration/src/bin/upgrade.rs b/noble-migration/src/bin/upgrade.rs
@@ -1,7 +1,7 @@
 //! Migrate a SecureDrop server from focal to noble
 //!
-//! This script should never be run directly, only via the
-//! systemd service.
+//! This script must never be run directly, only via the
+//! systemd service, which is enforced by checking $LAUNCHED_BY_SYSTEMD in main() below.
 use anyhow::{bail, Context, Result};
 use log::{debug, error, info};
 use rand::{thread_rng, Rng};
@@ -18,9 +18,9 @@ use std::{
     process::{self, Command, ExitCode},
 };
 
-/// Package-provided instructions on whether auto-migrations should run
+/// Configuration for the migration process (installed by securedrop-config)
 const CONFIG_PATH: &str = "/usr/share/securedrop/noble-upgrade.json";
-/// Serialized version of `State`
+/// Serialized version of `State` (left by the last run of this script)
 const STATE_PATH: &str = "/etc/securedrop-noble-migration-state.json";
 const MON_OSSEC_CONFIG: &str = "/var/ossec/etc/ossec.conf";
 /// Environment variable to allow developers to inject an extra APT source
@@ -606,8 +606,7 @@ struct UpgradeConfig {
 struct HostUpgradeConfig {
     /// whether upgrades are enabled
     enabled: bool,
-    /// all servers <= this bucket will be upgraded, i.e. 1 upgrades bucket 1,
-    /// 2 upgrades buckets 1 and 2, etc.
+    /// The `bucket` setting increases inclusively: i.e., `bucket=1` enables hosts in bucket 1 to upgrade; `bucket=2` enables hosts in buckets 1 and 2 to upgrade; etc.
     bucket: usize,
 }
 

diff --git a/noble-migration/src/lib.rs b/noble-migration/src/lib.rs
@@ -49,7 +49,7 @@ pub fn os_codename() -> Result<String> {
 /// See <https://github.com/freedomofpress/securedrop/issues/7316>.
 fn check_ssh_group() -> Result<bool> {
     // There are no clean bindings to getgrpname in rustix,
-    // so jut shell out to getent to get group members
+    // so just shell out to getent to get group members
     let output = process::Command::new("getent")
         .arg("group")
         .arg("ssh")

diff --git a/securedrop/debian/securedrop-app-code.postinst b/securedrop/debian/securedrop-app-code.postinst
@@ -311,8 +311,7 @@ case "$1" in
     database_migration
 
     # Restart apache now that we've updated everything, setup AppArmor
-    # and applied all migrations. Only restart if it is not masked, which
-    # it is during the noble migration.
+    # and applied all migrations. While the Noble migration is in progress, the service unit is masked and must not be restarted.
     apache2_status=$(systemctl is-enabled apache2 2>/dev/null ||:)
     if [ "$apache2_status" != "masked" ]; then
         systemctl restart apache2