Update machine settings information

docs/manage/_index.md

@@ -7,20 +7,15 @@ type: "docs"
 no_list: true
 open_on_desktop: true
 overview: true
+description: "Viam's fleet management tooling allows you to remotely deploy and manage software on any fleet of devices. You can monitor all connected devices and troubleshoot any issues - from anywhere."
 ---
 
+Viam's fleet management tooling allows you to remotely deploy and manage software on any fleet of devices. You can monitor all connected devices and troubleshoot any issues - from anywhere.
+
 <p>
 {{<imgproc src="/platform-overviews/fleet.png" resize="1200x" style="width:800px" class="aligncenter imgzoom" declaredimensions=true alt="ALT">}}
 </p>
 
-<!-- Viam fleet management allows you to deploy, manage, and monitor any number of machines alone or in collaboration with others.
-You can manage and control your fleet of {{< glossary_tooltip term_id="machine" text="smart machines" >}} from the [Viam app](https://app.viam.com), using the [CLI](/cli/), or using the [fleet management API](/appendix/apis/fleet/). -->
-
-<!-- Maybe add images of this:
-For example, you might have 30 robots in one warehouse and 500 in another.
-You can monitor and teleoperate all of the robots from one online dashboard, and grant permission to other users to do the same.
-You can grant users different levels of access to individual machines or to groups of machines. -->
-
 {{< how-to-expand "Deploy a fleet of machines" "3" "INTERMEDIATE" "light" >}}
 {{< cards >}}
 {{% card link="/manage/fleet/reuse-configuration/" noimage="true" %}}

docs/manage/fleet/system-settings.md

@@ -0,0 +1,154 @@
+---
+linkTitle: "Configure machine settings"
+title: "Configure machine operating system settings"
+weight: 50
+layout: "docs"
+type: "docs"
+description: "Configure network settings, operating system package updates and logging defaults."
+---
+
+The `viam-agent` configuration allows you to configure:
+
+- [settings for package updates for the host operating system](#configure-os-package-updates)
+- [networks a machine can connect to](#configure-networks)
+- [parameters for operating system logging](#configure-operating-system-logging)
+
+## Manage OS package updates
+
+By default, the configuration in <FILE>/etc/apt/apt.conf.d/</FILE> determines the behavior for updating operating system packages.
+To manage OS package updates using Viam, add an `"agent-syscfg"` object to the `"agent"` object in the machine's JSON configuration, if it doesn't already exist.
+Then, add the `"upgrades"` field in its attributes:
+
+```json
+"agent": {
+    "agent-syscfg": {
+        "release_channel": "stable",
+        "attributes": {
+            "upgrades": {
+                "type": "all|security|disabled"
+            }
+        }
+    }
+}
+```
+
+When the `type` attribute is specified for `"upgrades"`, `viam-agent` will install the `unattended-upgrades` package and replace `20auto-upgrades` and `50unattended-upgrades` in <FILE>/etc/apt/apt.conf.d/</FILE> with an Origins-Pattern list generated automatically from configured repositories on the system.
+Custom repos installed on the system at the time the setting is enabled will be included.
+
+You can set automatic upgrades for all packages by setting the field value to `{ "type": "all" }`.
+Alternatively, you can set automatic upgrades for only packages containing `"security"` in their codename (for example `bookworm-security`), by setting the field value to `{ "type": "security" }`.
+To disable automatic upgrades, set the field value to `{ "type": "disabled" }`.
+
+For complete reference information, see [viam-agent](/configure/agent/#agent-syscfg).
+
+## Configure networks
+
+By default, your machine can connect to networks added at the operating system level, for example, directly in NetworkManager.
+
+For an already-online device, you can add new WiFi networks by updating the `"agent"` value in the machine's JSON configuration.
+This is primarily useful for a machine that moves between different networks, so the machine can automatically connect when moved between locations.
+
+To add networks, add the `networks` field to the `agent-provisioning`'s `attributes` object and set `"roaming_mode": true`.
+You may need to add the `agent-provisioning` object to the `agent` object if it doesn't already exist.
+
+{{< alert title="Note" color="note" >}}
+If you are using the Viam app to add networks to a machine’s configuration, the machine will need to be connected to the internet to retrieve the configuration information containing the network credentials before it can use them.
+{{< /alert >}}
+
+The following configuration defines the connection information and credentials for two WiFi networks named `fallbackNetOne` and `fallbackNetTwo`.
+`viam-agent` will try to connect to `fallbackNetOne` first, since its priority is highest.
+If the `fallbackNetOne` is not available or the machine can connect but internet is not available, `viam-agent` will then attempt to connect to `fallbackNetTwo`.
+
+```json
+"agent": {
+    "agent-provisioning": {
+        ...
+        "attributes": {
+            "roaming_mode": true,
+            "networks": [
+                {
+                "type": "wifi",
+                "ssid": "fallbackNetOne",
+                "psk": "myFirstPassword",
+                "priority": 30
+                },
+                {
+                "type": "wifi",
+                "ssid": "fallbackNetTwo",
+                "psk": "mySecondPassword",
+                "priority": 10
+                }
+            ]
+        }
+    }
+}
+```
+
+For complete reference information, see [viam-agent](/configure/agent/#networks).
+
+## Configure operating system logging
+
+By default, the maximum disk space `journald` will use for `viam-server` logs is 512MB.
+
+To adjust these settings update the `"agent"` value in the machine's JSON configuration.
+
+For complete reference information, see [viam-agent](/configure/agent/#agent-syscfg) and the [`journald` docs](https://www.freedesktop.org/software/systemd/man/latest/journald.conf.html#SystemMaxUse=).
+
+### Set the maximum disk space
+
+To set the maximum disk space `journald` will use to persist logs, add the `system_max_use` field to the `agent-syscfg`'s `attributes` object.
+You may need to add the `agent-syscfg` object to the `agent` object if it doesn't already exist.
+
+The configured values will take precedence over operating system defaults.
+
+```json
+"agent": {
+    "agent-syscfg": {
+        "release_channel": "stable",
+        "attributes": {
+            "logging": {
+                "system_max_use": "512M"
+            }
+        }
+    }
+}
+```
+
+### Set the runtime space limit space
+
+To set the temporary space limit for logs, add the `runtime_max_use` field to the `agent-syscfg`'s `attributes` object.
+You may need to add the `agent-syscfg` object to the `agent` object if it doesn't already exist.
+
+The configured values will take precedence over operating system defaults.
+
+```json
+"agent": {
+    "agent-syscfg": {
+        "release_channel": "stable",
+        "attributes": {
+            "logging": {
+                "runtime_max_use": "512M"
+            }
+        }
+    }
+}
+```
+
+### Use the default operating system settings
+
+This configuration does not modify the OS-level logging configuration.
+
+The operating system defaults for `journald` will determine the logging settings.
+
+```json
+"agent": {
+    "agent-syscfg": {
+        "release_channel": "stable",
+        "attributes": {
+            "logging": {
+                "disable": true
+            }
+        }
+    }
+}
+```

docs/manage/reference/agent.md

@@ -194,10 +194,9 @@ Edit and fill in the attributes as applicable.
 
 #### Version updates
 
-To avoid unexpected downtime when `viam-server` is updated, you can configure a [Maintenance Window](/
-architecture/viam-server/#maintenance-window).
-With a configured maintenance window, `viam-agent` will restart and upgrade `viam-server` only when ma
-intenance is allowed and when `viam-server` is not currently processing config changes.
+When a new version of `viam-server` becomes available, `viam-agent` will restart and upgrade `viam-server` immediately.
+To limit when `viam-server` can be updated, you can configure a [Maintenance Window](/architecture/viam-server/#maintenance-window).
+With a configured maintenance window, `viam-agent` will restart and upgrade `viam-server` only when maintenance is allowed and when `viam-server` is not currently processing config changes.
 
 #### Fast start mode
 
@@ -275,13 +274,13 @@ The following configuration defines the connection information and credentials f
 
 ### `agent-syscfg`
 
-`agent-syscfg` is a plugin for `viam-agent` that provides a number of system and operating system configuration helpers.
+`agent-syscfg` is a plugin for `viam-agent` that allows you to configure logging settings and automated upgrades for packages installed on the operating system.
 
 <!-- prettier-ignore -->
 | Option | Type | Required? | Description |
 | ------ | ---- | --------- | ----------- |
 | `disable_subsystem` | boolean | Optional | When set to `true` it disables `agent-syscfg`. |
-| `attributes` | object | Optional | <ul><li>`logging`: parameters for logging<ul><li>`system_max_use`: sets the maximum disk space `journald` will user for persistent log storage. Numeric values are in bytes, with optional single letter suffix for larger units, for example. K, M, or G. Default: `512M`.</li><li>`runtime_max_use`: sets the runtime/temporary limit. Numeric values are in bytes, with optional single letter suffix for larger units, for example. K, M, or G. Default: `512M`.</li><li>`disable`: If `false` (default), Viam enforces the given logging configurations. If `true`: Viam does NOT modify logging configuration, and the operating system defaults are used.</li></ul></li><li>`upgrades`: using `upgrades` installs the `unattended-upgrades` package, and replace `20auto-upgrades` and `50unattended-upgrades` in <FILE>/etc/apt/apt.conf.d/</FILE>, with the latter's Origins-Pattern list being generated automatically from configured repositories on the system, so custom repos (at the time the setting is enabled) will be included.<ul><li>`type`: Configured unattended upgrades for Debian bullseye and bookworm. Options: `""` (no effect), `"disable"` (disables automatic upgrades), `"security"` (only enables updates from sources with "security" in their codename, ex: `bookworm-security`), `"all"` (enable updates from all configured sources).</li></ul></li></ul> |
+| `attributes` | object | Optional | <ul><li>`logging`: parameters for logging<ul><li>`system_max_use`: sets the maximum disk space `journald` will user for persistent log storage. Numeric values are in bytes, with optional single letter suffix for larger units, for example. K, M, or G. Default: `512M`.</li><li>`runtime_max_use`: sets the runtime/temporary limit. Numeric values are in bytes, with optional single letter suffix for larger units, for example. K, M, or G. Default: `512M`.</li><li>`disable`: If `false` (default), Viam enforces the given logging configurations. If `true`: Viam does NOT modify logging configuration, and the operating system defaults are used.</li></ul></li><li>`upgrades`: using `upgrades` installs the `unattended-upgrades` package, and replace `20auto-upgrades` and `50unattended-upgrades` in <FILE>/etc/apt/apt.conf.d/</FILE>, with an automatically generated Origins-Pattern list that is generated based on that of `50unattended-upgrades`. Custom repos installed on the system at the time the setting is enabled will be included.<ul><li>`type`: Configured unattended upgrades for Debian bullseye and bookworm. Options: `""` (no effect), `"disable"` (disables automatic upgrades), `"security"` (only enables updates from sources with "security" in their codename, ex: `bookworm-security`), `"all"` (enable updates from all configured sources).</li></ul></li></ul> |
 
 The following configuration allows all upgrades from configured sources and sets the maximum disk space `journald` will user for persistent log storage to 128MB and the runtime limit to 96MB: