From 2a33b3a4fe95b0e98a4c18d4e1952a0aa2613847 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 2 Jan 2025 14:51:46 +0100 Subject: [PATCH] Update machine settings information (#3772) --- docs/manage/_index.md | 11 +- docs/manage/fleet/system-settings.md | 154 +++++++++++++++++++++++++++ docs/manage/reference/agent.md | 11 +- docs/manage/system-settings.md | 15 --- 4 files changed, 162 insertions(+), 29 deletions(-) create mode 100644 docs/manage/fleet/system-settings.md delete mode 100644 docs/manage/system-settings.md diff --git a/docs/manage/_index.md b/docs/manage/_index.md index eba20339a9..e0b6bf68f0 100644 --- a/docs/manage/_index.md +++ b/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. +

{{}}

- - - - {{< how-to-expand "Deploy a fleet of machines" "3" "INTERMEDIATE" "light" >}} {{< cards >}} {{% card link="/manage/fleet/reuse-configuration/" noimage="true" %}} diff --git a/docs/manage/fleet/system-settings.md b/docs/manage/fleet/system-settings.md new file mode 100644 index 0000000000..dd7799385a --- /dev/null +++ b/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 /etc/apt/apt.conf.d/ 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 /etc/apt/apt.conf.d/ 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 + } + } + } +} +``` diff --git a/docs/manage/reference/agent.md b/docs/manage/reference/agent.md index 8f9e498558..95f7453714 100644 --- a/docs/manage/reference/agent.md +++ b/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. | Option | Type | Required? | Description | | ------ | ---- | --------- | ----------- | | `disable_subsystem` | boolean | Optional | When set to `true` it disables `agent-syscfg`. | -| `attributes` | object | Optional | | +| `attributes` | object | Optional | | 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: diff --git a/docs/manage/system-settings.md b/docs/manage/system-settings.md deleted file mode 100644 index 42c324236e..0000000000 --- a/docs/manage/system-settings.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -linkTitle: "Configure machine settings" -title: "Configure machine operating system settings" -weight: 50 -layout: "docs" -type: "docs" -description: "TODO" ---- - - -## Configure operating system settings - -agent-syscfg - -## Configure networks