Add docs about assigning NM conn profiles to other firewall zones (#43)

This PR adds how-to guides related to
openUC2/os-rpi#160

This PR also adjusts the names of sections in the OS usage docs.

Author: ethanjli

docs/dev/sw/imswitch/01_Quickstart.mdx

@@ -22,7 +22,7 @@ The below diagramm visualizes the different modules that are connected to the op
 ## Getting Started
 
 ### Accessing ImSwitch
-Refer to our [usage guides](../../../usage/components/os/guides/day-1/sw-access/README.md#browser-apps).
+Refer to our [usage guides](../../../usage/components/os/guides/day-1/access.md#browser-apps).
 
 ### Modifying ImSwitch Configuration
 To adjust settings, edit the configuration file:
@@ -83,7 +83,7 @@ Use the Raspberry Pi Imager to flash the image onto an SD card, then insert the
 
 ### Installing software updates
 
-Refer to our [usage guides](../../../usage/components/os/guides/day-2/sw-updates/README.md).
+Refer to our [usage guides](../../../usage/components/os/guides/day-2/updates.md).
 
 ### Troubleshooting pallet configurations
 

docs/dev/sw/imswitch/Advanced/02_Usage/Updates.md

@@ -11,7 +11,7 @@ The update process involves three main components:
 
 ## In openUC2 OS
 
-Refer to our [usage guides](../../../../../usage/components/os/guides/day-2/sw-updates/README.md).
+Refer to our [usage guides](../../../../../usage/components/os/guides/day-2/updates.md).
 
 ## With Native Python Installation
 
@@ -217,12 +217,12 @@ chmod +x update_imswitch.sh
 3. **Test UC2-REST:**
    ```python
    from UC2REST import UC2Client
-                  client = UC2Client(serialport="/dev/ttyUSB0")
-                  if client.is_connected:
-                      print("UC2-REST connection successful")
-                      # Test basic commands
-                      client.led.set_led(channel=1, intensity=50)
-                      client.led.set_led(channel=1, intensity=0)
+                     client = UC2Client(serialport="/dev/ttyUSB0")
+                     if client.is_connected:
+                         print("UC2-REST connection successful")
+                         # Test basic commands
+                         client.led.set_led(channel=1, intensity=50)
+                         client.led.set_led(channel=1, intensity=0)
    ```
 
 4. **Test New Features:**

docs/usage/components/os/README.md

@@ -1 +1,4 @@
 # openUC2 OS
+
+openUC2 OS is the operating system for openUC2 machines.
+It is a customization layer over [Raspberry Pi OS](https://www.raspberrypi.com/software/operating-systems/), with a version-controlled OS configuration and update system.

docs/usage/components/os/explanations/networking/exposure.md

@@ -1,6 +1,6 @@
 # Exposure of Software
 
-Because openUC2 OS is designed for [headless](https://en.wikipedia.org/wiki/Headless_software) operation, its software is exposed to be [accessed](../../guides/day-1/sw-access/README.md) over [network connections](../../guides/day-1/connectivity/README.md).
+Because openUC2 OS is designed for [headless](https://en.wikipedia.org/wiki/Headless_software) operation, its software is exposed to be [accessed](../../guides/day-1/access.md) over [network connections](../../guides/day-1/connectivity.md).
 Here, we explain the OS's mechanisms for making software accessible over network connections— including the operational and security implications of the default configuration of these mechanisms.
 
 The overall model is that a user (or computer or software program) trying to access a software program on an openUC2 OS machine will initiate a connection to the machine.
@@ -34,28 +34,31 @@ This is the most generally-usable way that users can access openUC2 OS's softwar
 Thus, the firewall is configured to allow full access from such connections to all known programs running on the machine, including apps exposed by the [ingress proxy for trusted access](#trusted-access) which give unauthenticated users full administrative privileges on the OS.
 
 The security assumptions implied by this configuration are that:
-- The [password of the machine's Wi-Fi hotspot has been changed](../../guides/day-1/security/README.md#how-to-change-the-wi-fi-hotspots-password) to something more secure than the default value of `youseetoo`; otherwise, it would be trivially easy for an attacker to gain access to the machine from a nearby location.
+- The [password of the machine's Wi-Fi hotspot has been changed](../../guides/day-1/security.md#how-to-change-the-wi-fi-hotspots-password) to something more secure than the default value of `youseetoo`; otherwise, it would be trivially easy for an attacker to gain access to the machine from a nearby location.
 - If someone has enough physical access to the openUC2 OS machine to be able set up a direct connection to the machine from another computer, then that person should be able to access all software on the machine from that other computer.
 
 By default, connections through a [Tailscale](https://tailscale.com/) tailnet are treated as direct connections.
-This configuration is needed to support the OS's [remote-assistance functionality](../../guides/day-1/connectivity/README.md#for-remote-assistance-from-openuc2); however, this configuration can be changed to [make the firewall treat the tailnet like an untrusted network](../../guides/day-1/security/README.md#how-to-control-access-to-unauthenticated-administrative-apps-over-tailscale).
+This configuration is needed to support the OS's [remote-assistance functionality](../../guides/day-1/connectivity.md#for-remote-assistance-from-openuc2); however, this configuration can be changed to [make the firewall treat the tailnet like an untrusted network](../../guides/day-1/security.md#over-tailscale).
+
+Similarly, networking configurations can be changed to [make the firewall treat a particular direct physical connection like an untrusted network](../../guides/day-1/security.md#how-to-block-access-to-all-apps).
 
 ### Public access
 
 [Connections from public networks](../../reference/networking/firewall.md#public) are connections to the machine from a network which may have untrusted computers and/or people.
 
-By default, any network connection which isn't a direct connection is assumed to be significantly more vulnerable to undesired access and malicious attacks. Thus, the firewall is configured to deny access to programs which give unauthenticated users full administrative privileges on the OS; however, this can be overridden to [allow access](../../guides/day-1/sw-access/README.md#to-unauthenticated-administrative-apps-over-local-area-networks).
+By default, any network connection which isn't a direct connection is assumed to be significantly more vulnerable to undesired access and malicious attacks. Thus, the firewall is configured to deny access to programs which give unauthenticated users full administrative privileges on the OS; however, this can be overridden to [allow access](../../guides/day-1/access.md#to-all-unauthenticated-administrative-apps).
 
 However, the firewall is configured allow access to programs which give users full administrative privileges on the OS upon authentication, as well as programs for unprivileged operation of the machine:
-- By default, access to Cockpit (which exposes full administrative access to the OS) on port 9090 is allowed, because it requires authentication; however, this configuration can be changed to [block access](../../guides/day-1/security/README.md#to-cockpit).
-- By default, access to SSH (which exposes full administrative access to the OS) is allowed, because it requires authentication; however, this configuration can be changed to [block access](../../guides/day-1/security/README.md#to-ssh).
+- By default, access to Cockpit (which exposes full administrative access to the OS) on port 9090 is allowed, because it requires authentication; however, this configuration can be changed to [block access](../../guides/day-1/security.md#to-cockpit).
+- By default, access to SSH (which exposes full administrative access to the OS) is allowed, because it requires authentication; however, this configuration can be changed to [block access](../../guides/day-1/security.md#to-ssh).
 - By default, access to the [ingress proxy for untrusted access](#untrusted-access) is allowed on port 80 (through a port-forwarding rule to port 8000 where the ingress proxy listens), instead of the [ingress proxy for trusted access](#trusted-access); as a result, all apps exposed by the untrusted-access ingress proxy are exposed for public access.
 
 The security assumptions implied by this configuration are that:
-- The [password of the machine's `pi` user has been changed](../../guides/day-1/security/README.md#how-to-change-the-pi-users-password) to something more secure than the default value of `youseetoo`; otherwise, it would be trivially easy for an attacker to gain access to the machine over an untrusted network.
+- The [password of the machine's `pi` user has been changed](../../guides/day-1/security.md#how-to-change-the-pi-users-password) to something more secure than the default value of `youseetoo`; otherwise, it would be trivially easy for an attacker to gain access to the machine over an untrusted network.
 - The operator of the machine intends to access non-administrative programs from other computers on the network.
 
-If a particular network should be granted the same level of access as direct connections, the firewall configuration can be adjusted accordingly. (TODO: add link to a how-to guide)
+If a particular network should be granted the same level of access as direct connections, [the firewall configuration can be adjusted accordingly](../../guides/day-1/access.md#to-all-unauthenticated-administrative-apps).
+Or, if a particular network should not allow any access, [the firewall configuration can be adjusted accordingly](../../guides/day-1/security.md#how-to-block-access-to-specific-apps-over-lans).
 
 ## Ingress proxying
 
@@ -116,9 +119,9 @@ Untrusted access is exposed on a separate port (in this case port 8000) so that
 By default, access to the following application servers is allowed for convenience:
 
 - The landing page; however, this configuration can be changed to block access.
-- ImSwitch, which can arbitrarily control hardware attached to the openUC2 OS machine; however, this configuration can be changed to [block access](../../guides/day-1/security/README.md#to-imswitch).
-- The user file manager, which can download and delete data acquired by ImSwitch; however, this configuration can be changed to [block access](../../guides/day-1/security/README.md#to-the-user-file-manager).
-- Cockpit, which exposes full administrative access to the OS after user authentication; however, this configuration can be changed to [block access](../../guides/day-1/security/README.md#to-cockpit).
+- ImSwitch, which can arbitrarily control hardware attached to the openUC2 OS machine; however, this configuration can be changed to [block access](../../guides/day-1/security.md#to-imswitch).
+- The user file manager, which can download and delete data acquired by ImSwitch; however, this configuration can be changed to [block access](../../guides/day-1/security.md#to-the-user-file-manager).
+- Cockpit, which exposes full administrative access to the OS after user authentication; however, this configuration can be changed to [block access](../../guides/day-1/security.md#to-cockpit).
 - The embedded openUC2 documentation; however, this configuration can be changed to block access.
 
 This ingress proxy is always accessible on port 8000; however, in the [firewall zone for public access](#public-access) this ingress proxy is also accessible on port 80 (since the trusted-access ingress proxy is not accessible on port 80 in that zone).

docs/usage/components/os/guides/day-0/README.md

@@ -14,5 +14,5 @@ If this is your first time deploying openUC2 OS, we strongly recommend going thr
 The how-to guides here are written for people who already have previous familiarity with deploying openUC2 OS.
 Here, we assume that you just need guidance for planning a successful deployment of another instance of openUC2 OS, or for re-deploying an existing instance of openUC2 OS.
 
-1. [Software Installation](./sw-install/README.md): these guides help you to determine what variant & version of openUC2 OS you will install on your machine.
-2. [Machine Connectivity](./connectivity/README.md): these guides help you to determine how you will connect to your openUC2 OS machine's software, and how you will make your machine's software easy to access— since openUC2 OS supports many ways of doing these things depending on your operational requirements.
+1. [OS Installation](./installation.md): these guides help you to determine what variant & version of openUC2 OS you will install on your machine.
+2. [Machine Connectivity](./connectivity.md): these guides help you to determine how you will connect to your openUC2 OS machine's software, and how you will make your machine's software easy to access— since openUC2 OS supports many ways of doing these things depending on your operational requirements.

…s/os/guides/day-0/connectivity/README.md …mponents/os/guides/day-0/connectivity.mddocs/usage/components/os/guides/day-0/connectivity/README.md renamed to docs/usage/components/os/guides/day-0/connectivity.md docs/usage/components/os/guides/day-0/connectivity/README.md renamed to docs/usage/components/os/guides/day-0/connectivity.md

@@ -5,7 +5,7 @@ toc_max_heading_level: 4
 
 # Machine Connectivity
 
-The how-to guides here will help you to prepare for successful [configuration of machine connectivity](../../day-1/connectivity/README.md) as part of your [day-1 deployment procedures](../../day-1/README.md).
+The how-to guides here will help you to prepare for successful [configuration of machine connectivity](../day-1/connectivity.md) as part of your [day-1 deployment procedures](..//day-1/README.md).
 
 ## How to choose a networking topology
 
@@ -18,10 +18,10 @@ If your computer has a single Wi-Fi module and you normally rely on it to connec
 We officially support two categories of ways to be able to access the internet from your computer while it's connected to the machine:
 
 1. By internet access sharing from the machine:
-   1. You will [connect your computer to the machine's Wi-Fi hotspot](../../day-1/connectivity/README.md#via-the-machines-wi-fi-hotspot).
-   2. Then you will [connect the machine to the internet](../../day-1/connectivity/README.md#how-to-connect-the-machine-to-the-internet). The machine will automatically share its internet access to your computer through its Wi-Fi hotspot.
+   1. You will [connect your computer to the machine's Wi-Fi hotspot](../day-1/connectivity.md#via-the-machines-wi-fi-hotspot).
+   2. Then you will [connect the machine to the internet](../day-1/connectivity.md#how-to-connect-the-machine-to-the-internet). The machine will automatically share its internet access to your computer through its Wi-Fi hotspot.
 
-2. By connecting to the machine with a wired connection: you will keep your computer connected to the internet via its normal Wi-Fi connection, and then connect your computer to the machine [via an Ethernet cable](../../day-1/connectivity/README.md#via-an-ethernet-cable) or [via a USB-C cable](../../day-1/connectivity/README.md#via-a-usb-c-cable).
+2. By connecting to the machine with a wired connection: you will keep your computer connected to the internet via its normal Wi-Fi connection, and then connect your computer to the machine [via an Ethernet cable](../day-1/connectivity.md#via-an-ethernet-cable) or [via a USB-C cable](../day-1/connectivity.md#via-a-usb-c-cable).
 
 In determining the most appropriate method for you, you should consider:
 
@@ -58,7 +58,7 @@ For help with choosing the best method for your particular circumstances, or for
 If you need to be able to connect your computer to multiple openUC2 OS machines, then you can either:
 
 1. Connect to each machine one-at-a-time:
-   whenever you need to [connect your computer to some other machine](../../day-1/connectivity/README.md#how-to-connect-to-the-machine), you will need to first disconnect your computer from the machine which it's currently connected to.
+   whenever you need to [connect your computer to some other machine](../day-1/connectivity.md#how-to-connect-to-the-machine), you will need to first disconnect your computer from the machine which it's currently connected to.
 2. Connect to multiple machines simultaneously.
 
 The second approach requires consideration and handling of various networking-related nuances and differences between networks in their configurations, while the first approach avoids those issues.
@@ -68,27 +68,27 @@ Here are your options for the second approach:
 
 Due to the default static IP address configurations in the machines, by default your computer cannot correctly use:
 
-- simultaneous [connections to the Wi-Fi hotspots](../../day-1/connectivity/README.md#via-the-machines-wi-fi-hotspot) of multiple machines
-- simultaneous [connections to the built-in Ethernet ports](../../day-1/connectivity/README.md#via-an-ethernet-cable) of multiple machines
-- simultaneous [connections to the dedicated USB-C ports](../../day-1/connectivity/README.md#via-a-usb-c-cable) of multiple machines
+- simultaneous [connections to the Wi-Fi hotspots](../day-1/connectivity.md#via-the-machines-wi-fi-hotspot) of multiple machines
+- simultaneous [connections to the built-in Ethernet ports](../day-1/connectivity.md#via-an-ethernet-cable) of multiple machines
+- simultaneous [connections to the dedicated USB-C ports](../day-1/connectivity.md#via-a-usb-c-cable) of multiple machines
 
 Instead, you will need to either
 
-1. use a different [connection method](../../day-1/connectivity/README.md#how-to-connect-to-the-machine) for each machine; or
+1. use a different [connection method](../day-1/connectivity.md#how-to-connect-to-the-machine) for each machine; or
 2. change the static IP address configurations of one or more of the machines (please contact openUC2 support for help with this).
 
 Once you've connected to the machines, you will be able to access their landing pages either
 
-1. [via the machine-specific domain name](../../day-1/connectivity/README.md#how-to-access-the-machines-landing-page) of each machine; or
-2. [via a static IP address](../../day-1/connectivity/README.md#via-a-static-ip-address) specific to the network connection method for each machine
+1. [via the machine-specific domain name](../day-1/connectivity.md#how-to-access-the-machines-landing-page) of each machine; or
+2. [via a static IP address](../day-1/connectivity.md#via-a-static-ip-address) specific to the network connection method for each machine
 
 #### with indirect connections over a Tailscale tailnet
 
-1. Set up remote access [through the same Tailscale tailnet](../../day-1/connectivity/README.md#through-your-own-tailscale-tailnet) on each machine.
-2. Set up connections between your computer and each machine [via the Tailscale tailnet](../../day-1/connectivity/README.md#via-tailscale).
-3. Access each machine's landing page [via its Tailscale MagicDNS domain name](../../day-1/connectivity/README.md#via-a-tailscale-magicdns-domain-name).
+1. Set up remote access [through the same Tailscale tailnet](../day-1/connectivity.md#through-your-own-tailscale-tailnet) on each machine.
+2. Set up connections between your computer and each machine [via the Tailscale tailnet](../day-1/connectivity.md#via-tailscale).
+3. Access each machine's landing page [via its Tailscale MagicDNS domain name](../day-1/connectivity.md#via-a-tailscale-magicdns-domain-name).
 
 #### with indirect connections over a LAN
 
-1. Set up connections between your computer and each machine [via the same Local Area Network](../../day-1/connectivity/README.md#via-a-local-area-network) (LAN), e.g. a Wi-Fi router or an Ethernet router.
-2. Access each machine's landing page via its `http://openuc2-{machine name}.local` domain name, as described in the guide for [using a machine-specific domain name](../../day-1/connectivity/README.md#via-a-machine-specific-domain-name).
+1. Set up connections between your computer and each machine [via the same LAN](../day-1/connectivity.md#via-a-lan), e.g. a Wi-Fi router or an Ethernet router.
+2. Access each machine's landing page via its `http://openuc2-{machine name}.local` domain name, as described in the guide for [using a machine-specific domain name](../day-1/connectivity.md#via-a-machine-specific-domain-name).

…nts/os/guides/day-0/sw-install/README.md …mponents/os/guides/day-0/installation.mddocs/usage/components/os/guides/day-0/sw-install/README.md renamed to docs/usage/components/os/guides/day-0/installation.md docs/usage/components/os/guides/day-0/sw-install/README.md renamed to docs/usage/components/os/guides/day-0/installation.md

@@ -2,7 +2,7 @@
 sidebar_position: 10
 ---
 
-# Software Installation
+# Installation
 
 ## How to choose an operating system