diff --git a/docs/manage/fleet/provision/end-user-setup.md b/docs/manage/fleet/provision/end-user-setup.md index fae43b682a..b70585b07c 100644 --- a/docs/manage/fleet/provision/end-user-setup.md +++ b/docs/manage/fleet/provision/end-user-setup.md @@ -139,7 +139,7 @@ Note that any features that require internet access will not function if the con You can now use your machine. -If your machine needs to be able to connect to more than one WiFi network, you can add additional networks in the [`viam-agent` network configuration](/manage/reference/viam-agent/#networks). +If your machine needs to be able to connect to more than one WiFi network, you can add additional networks in the [`viam-agent` network configuration](/manage/reference/viam-agent/#network_configuration). You can also override other configuration details in the [`viam-agent` configuration](/manage/reference/viam-agent/#configuration). To control your machine, you can navigate to its **CONTROL** tab in the [Viam app](https://app.viam.com). diff --git a/docs/manage/fleet/provision/setup.md b/docs/manage/fleet/provision/setup.md index 7c9411c048..c6572be8c8 100644 --- a/docs/manage/fleet/provision/setup.md +++ b/docs/manage/fleet/provision/setup.md @@ -187,7 +187,7 @@ Create a file called viam-provisioning.json with the following form "model": "", # the machine's model "fragment_id": "", # the fragment id, required for mobile app "hotspot_prefix": "", # machine creates a hotspot during setup - "disable_dns_redirect": true, # disable if using a mobile app + "disable_captive_portal_redirect": false, # set to true if using a mobile app "hotspot_password": "", # password for the hotspot "networks" : [] } @@ -202,12 +202,12 @@ Create a file called viam-provisioning.json with the following form "model": "C-3PO", "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663", "hotspot_prefix": "skywalker-setup", - "disable_dns_redirect": true, + "disable_captive_portal_redirect": false, "hotspot_password": "skywalker123", - "roaming_mode": false, - "offline_timeout": "3m30s", - "user_timeout": "2m30s", - "fallback_timeout": "15m" + "turn_on_hotspot_if_wifi_has_no_internet": false, + "offline_before_starting_hotspot_minutes": "3m30s", + "user_idle_minutes": "2m30s", + "retry_connection_timeout_minutes": "15m" } ``` @@ -228,14 +228,14 @@ It also configures timeouts to control how long `viam-agent` waits for a valid l | `hotspot_interface` | string | Optional | The interface to use for hotspot/provisioning/wifi management. Default: first discovered 802.11 device. | | `hotspot_prefix` | string | Optional | `viam-agent` will prepend this to the hostname of the device and use the resulting string for the provisioning hotspot SSID. Default: `"viam-setup"`. | | `hotspot_password` | string | Optional | The Wifi password for the provisioning hotspot. Default: `"viamsetup"`. | -| `disable_dns_redirect` | boolean | Optional | By default, ALL DNS lookups using the provisioning hotspot will redirect to the device. This causes most phones/mobile devices to automatically redirect the user to the captive portal as a "sign in" screen. When disabled, only domains ending in .setup (ex: viam.setup) will be redirected. This generally avoids displaying the portal to users and is mainly used in conjunction with a mobile provisioning application workflow. Default: `false`. | -| `roaming_mode` | boolean | Optional | By default, the device will only attempt to connect to a single wifi network (the one with the highest priority), provided during initial provisioning/setup using the provisioning mobile app or captive web portal. Wifi connection alone is enough to consider the device as "online" even if the global internet is not reachable. If the primary network configured during provisioning cannot be connected to and roaming mode is enabled, the device will attempt connections to all configured networks in `networks`, and only consider the device online if the internet is reachable. Default: `false`. | -| `offline_timeout` | boolean | Optional | Will only enter provisioning mode (hotspot) after being disconnected longer than this time. Useful on flaky connections, or when part of a system where the device may start quickly, but the wifi/router may take longer to be available. Default: `"2m"` (2 minutes). | -| `user_timeout` | boolean | Optional | Amount of time before considering a user (using the captive web portal or provisioning app) idle, and resuming normal behavior. Used to avoid interrupting provisioning mode (for example for network tests/retries) when a user might be busy entering details. Default: `"5m"` (5 minutes). | -| `fallback_timeout` | boolean | Optional | Provisioning mode will exit after this time, to allow other unmanaged (for example wired) or manually configured connections to be tried. Provisioning mode will restart if the connection/online status doesn't change. Default: `"10m"` (10 minutes). | -| `networks` | array | Optional | Add additional networks the machine can connect to for provisioning. We recommend that you add WiFi settings in the operating system (for example, directly in NetworkManager) rather than in this file, or in the corresponding machine config in the Viam app, if networks aren't needed until after initial provisioning. See [Networks](/manage/reference/viam-agent/#networks). Default: `[]`. | -| `wifi_power_save` | boolean | Optional | If set, will explicitly enable or disable power save for all WiFi connections managed by NetworkManager. | -| `device_reboot_after_offline_minutes` | integer | Optional | If set, `viam-agent` will reboot the device after it has been offline for the specified duration. Default: `0` (disabled). | +| `disable_captive_portal_redirect` | boolean | Optional | By default, all DNS lookups are redirected to the "sign in" portal, which can cause mobile devices to automatically display the portal. When set to true, only DNS requests for domains ending in .setup, like `viam.setup` are redirected, preventing the portal from appearing unexpectedly, especially convenient when using a mobile app for provisioning. Default: `false`. | +| `turn_on_hotspot_if_wifi_has_no_internet` | boolean | Optional | By default, the device connects to a single prioritized WiFi network (provided during provisioning) and is considered online even if the global internet is not reachable. When `turn_on_hotspot_if_wifi_has_no_internet` is true and the primary network lacks internet connectivity, the device will try all configured networks and only mark itself as online if it successfully connects to the internet. Default: `false`. | +| `offline_before_starting_hotspot_minutes` | integer | Optional | Will only enter provisioning mode (hotspot) after being disconnected longer than this time. Useful on flaky connections, or when part of a system where the device may start quickly, but the wifi/router may take longer to be available. Default: `2` (2 minutes). | +| `user_idle_minutes` | integer | Optional | Amount of time before considering a user (using the captive web portal or provisioning app) idle, and resuming normal behavior. Used to avoid interrupting provisioning mode (for example for network tests/retries) when a user might be busy entering details. Default: `5` (5 minutes). | +| `retry_connection_timeout_minutes` | integer | Optional | Provisioning mode will exit after this time, to allow other unmanaged (for example wired) or manually configured connections to be tried. Provisioning mode will restart if the connection/online status doesn't change. Default: `10` (10 minutes). | +| `networks` | array | Optional | Add additional networks the machine can connect to for provisioning. We recommend that you add WiFi settings in the operating system (for example, directly in NetworkManager) rather than in this file, or in the corresponding machine config in the Viam app, if networks aren't needed until after initial provisioning. See [Networks](/manage/reference/viam-agent/#network_configuration). Default: `[]`. | +| `wifi_power_save` | boolean | Optional | Boolean, which, if set, will explicitly enable or disable power save for all WiFi connections managed by NetworkManager. If not set, the system default applies. Default: `NULL`. | +| `device_reboot_after_offline_minutes` | integer | Optional | If set, `viam-agent` will reboot the device after it has been offline (and in hotspot mode) for the specified duration. Default: `0` (disabled). | {{% /expand%}} @@ -251,10 +251,10 @@ If you know in advance which other networks a machine should be able to connect However, if you want to add additional networks to the provisioning configuration you can add them to the `networks` field value. {{< alert title="Important" color="note" >}} -You must enable `roaming_mode` in the [`agent-provisioning` configuration](/manage/fleet/provision/setup/#configure-agent-provisioning) of the machine to allow the machine to connect to the specified networks after provisioning. +You must enable `turn_on_hotspot_if_wifi_has_no_internet` in the [`agent-provisioning` configuration](/manage/fleet/provision/setup/#configure-agent-provisioning) of the machine to allow the machine to connect to the specified networks after provisioning. {{< /alert >}} -If `roaming_mode` is enabled, `agent-provisioning` will try to connect to each specified network in order of `priority` from highest to lowest. +If `turn_on_hotspot_if_wifi_has_no_internet` is enabled, `agent-provisioning` will try to connect to each specified network in order of `priority` from highest to lowest. | Name | Type | Description | @@ -272,13 +272,13 @@ The following configuration defines the connection information and credentials f "model": "C-3PO", "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663", "hotspot_prefix": "skywalker-setup", - "disable_dns_redirect": true, + "disable_captive_portal_redirect": false, "hotspot_password": "skywalker123", - "roaming_mode": false, - "offline_timeout": "3m30s", - "user_timeout": "2m30s", - "fallback_timeout": "15m", - "roaming_mode": true, + "turn_on_hotspot_if_wifi_has_no_internet": false, + "offline_before_starting_hotspot_minutes": "3m30s", + "user_idle_minutes": "2m30s", + "retry_connection_timeout_minutes": "15m", + "turn_on_hotspot_if_wifi_has_no_internet": true, "networks": [ { "type": "wifi", @@ -449,9 +449,9 @@ sudo ./preinstall.sh /path/to/rootfs ### Device not detecting networks -Some systems can't scan for WiFi networks while in hotspot mode, meaning they won't automatically detect networks coming online or into range until the `fallback_timeout` expires. -The `fallback_timeout` causes your device to exit hotspot mode, at which point your device will be able to detect newly available networks. -If your device does not connect to your network, adjust the `fallback_timeout` value in the [`agent-provisioning` configuration](/manage/fleet/provision/setup/#configure-agent-provisioning). +Some systems can't scan for WiFi networks while in hotspot mode, meaning they won't automatically detect networks coming online or into range until the `retry_connection_timeout_minutes` expires. +The `retry_connection_timeout_minutes` causes your device to exit hotspot mode, at which point your device will be able to detect newly available networks. +If your device does not connect to your network, adjust the `retry_connection_timeout_minutes` value in the [`agent-provisioning` configuration](/manage/fleet/provision/setup/#configure-agent-provisioning). ### Test GRPC components of the provisioning service @@ -496,7 +496,7 @@ For a guide you can give to end users for setting up their machine, see [Setup m - `agent-provisioning` will use the provided network if it can connect, even if that network does not have internet access. Note that any features that require internet access will not function if the connected WiFi network is not connected to the internet. - If you want `agent-provisioning` to require that a WiFi network be connected to the internet in order to connect to it, enable roaming mode. + If you want `agent-provisioning` to require that a WiFi network be connected to the internet in order to connect to it, enable `turn_on_hotspot_if_wifi_has_no_internet`. 1. `viam-agent` then starts `viam-server` with the provided configuration and the machine becomes **live**. @@ -536,7 +536,7 @@ For a guide you can give to end users for setting up their machine, see [Setup m - `agent-provisioning` will use the provided network if it can connect, even if that network does not have internet access. Note that any features that require internet access will not function if the connected WiFi network is not connected to the internet. - If you want `agent-provisioning` to require that a WiFi network be connected to the internet in order to connect to it, enable roaming mode. + If you want `agent-provisioning` to require that a WiFi network be connected to the internet in order to connect to it, enable `turn_on_hotspot_if_wifi_has_no_internet`. 1. `viam-agent` then starts `viam-server` with the provided configuration and the machine becomes **live**. diff --git a/docs/manage/fleet/system-settings.md b/docs/manage/fleet/system-settings.md index 134a049ccd..ec5d0f5d4f 100644 --- a/docs/manage/fleet/system-settings.md +++ b/docs/manage/fleet/system-settings.md @@ -16,30 +16,27 @@ The `viam-agent` configuration allows you to configure: ## 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: +To manage OS package updates using Viam, add a `"system_configuration"` object to the `"agent"` object in the machine's JSON configuration, if it doesn't already exist. +Then, add the `"os_auto_upgrade_type"` field in its attributes: ```json "agent": { - "agent-syscfg": { - "release_channel": "stable", - "attributes": { - "upgrades": { - "type": "all|security|disabled" - } - } + "system_configuration": { + "os_auto_upgrade_type": "security" } } ``` -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. +When the `os_auto_upgrade_type` is set, `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" }`. +You can set automatic upgrades to the following options: + +- `"all"`: automatic upgrades are performed for all packages +- `"security"`: automatic upgrades for only packages containing `"security"` in their codename (for example `bookworm-security`) +- `""`: disable automatic upgrades -For complete reference information, see [viam-agent](/manage/reference/viam-agent/#agent-syscfg). +For complete reference information, see [viam-agent](/manage/reference/viam-agent/#system-configuration). ## Configure networks @@ -48,8 +45,7 @@ By default, your machine can connect to networks added at the operating system l 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. +To add networks, add or update the `additional_networks` field to the `agent` object and set `"turn_on_hotspot_if_wifi_has_no_internet": true`. {{< 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. @@ -61,30 +57,24 @@ If the `fallbackNetOne` is not available or the machine can connect but internet ```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 - } - ] + "additional_networks": [ + { + "type": "wifi", + "ssid": "fallbackNetOne", + "psk": "myFirstPassword", + "priority": 30 + }, + { + "type": "wifi", + "ssid": "fallbackNetTwo", + "psk": "mySecondPassword", + "priority": 10 } - } + ] } ``` -For complete reference information, see [viam-agent](/manage/reference/viam-agent/#networks). +For complete reference information, see [viam-agent](/manage/reference/viam-agent/#network_configuration). ## Configure operating system logging @@ -92,63 +82,36 @@ By default, the maximum disk space `journald` will use for `viam-server` logs is To adjust these settings update the `"agent"` value in the machine's JSON configuration. -For complete reference information, see [viam-agent](/manage/reference/viam-agent/#agent-syscfg) and the [`journald` docs](https://www.freedesktop.org/software/systemd/man/latest/journald.conf.html#SystemMaxUse=). +For complete reference information, see [viam-agent](/manage/reference/viam-agent/#system-configuration) 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. +To set the maximum disk space `journald` will use to persist logs, add the `logging_journald_system_max_use_megabytes` field to the `system_configuration` object. +You may need to add the `system_configuration` 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" - } - } + "system_configuration": { + "os_auto_upgrade_type": "security", + "logging_journald_system_max_use_megabytes": 512 } } ``` ### 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. +To set the temporary space limit for logs, add the `logging_journald_runtime_max_use_megabytes` field to the `system_configuration` object. +You may need to add the `system_configuration` 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 - } - } + "system_configuration": { + "os_auto_upgrade_type": "security", + "logging_journald_runtime_max_use_megabytes": 512 } } ``` diff --git a/docs/manage/reference/viam-agent/_index.md b/docs/manage/reference/viam-agent/_index.md index ffa43ff041..1611a8e767 100644 --- a/docs/manage/reference/viam-agent/_index.md +++ b/docs/manage/reference/viam-agent/_index.md @@ -12,18 +12,15 @@ aliases: # SMEs: James, Ale --- -The [`viam-agent`](https://github.com/viamrobotics/agent) is a self-updating service manager that maintains the lifecycle for itself and the following system services: - -- `viam-server`: the core of the machine -- [`agent-provisioning`](#agent-provisioning): device provisioning which can set up machine configs and manage WiFi networks. For more information see [Provisioning](/manage/fleet/provision/setup/). -- [`agent-syscfg`](#agent-syscfg): provides various operating system and system configuration tweaks +The [`viam-agent`](https://github.com/viamrobotics/agent) is a self-updating service manager that maintains the lifecycle for itself and `viam-server`. Among other things, `viam-agent`: -- Installs, runs, and monitors `viam-server` - You can also use a custom build of `viam-server`, if needed. +- Installs, runs, and monitors `viam-server` or a custom build of `viam-server`. +- Provides tooling for device provisioning and network management. - Provides automatic updates for `viam-server` and the agent itself. - Allows control of deployed software versions through the Viam app. +- Provides various operating system settings. {{< alert title="Support notice" color="note" >}} Currently, `viam-agent` is only supported on Linux, for amd64 (x86_64) and arm64 (aarch64) CPUs. @@ -97,26 +94,48 @@ Edit and fill in the attributes as applicable. ```json {class="line-numbers linkable-line-numbers"} { "agent": { - "viam-agent": { - "release_channel": "stable", - "pin_version": "", - "pin_url": "" + "version_control": { + "agent": "stable", + "viam-server": "0.52.1" }, - "viam-server": { - "release_channel": "stable", - "pin_version": "", - "pin_url": "", - "disable_subsystem": false, - "attributes": { - "fast_start": false - } + "advanced_settings": { + "debug": false, + "wait_for_update_check": false, + "viam_server_start_timeout_minutes": 10, + "disable_viam_server": false, + "disable_network_configuration": false, + "disable_system_configuration": false }, - "agent-provisioning": { - "disable_subsystem": false, - "networks": [] + "network_configuration": { + "manufacturer": "viam", + "model": "custom", + "fragment_id": "", + "hotspot_prefix": "viam-setup", + "hotspot_password": "viamsetup", + "disable_captive_portal_redirect": false, + "offline_before_starting_hotspot_minutes": 2, + "user_idle_minutes": 5, + "retry_connection_timeout_minutes": 10, + "turn_on_hotspot_if_wifi_has_no_internet": false, + "wifi_power_save": null + }, + "additional_networks": { + { + "type": "", + "interface": "", + "ssid": "", + "psk": "", + "priority": 0, + "ipv4_address": "", + "ipv4_gateway": "", + "ipv4_dns": [], + "ipv4_route_metric": 0 + } }, - "agent-syscfg": { - "disable_subsystem": false + "system_configuration": { + "logging_journald_system_max_use_megabytes": 512, + "logging_journald_runtime_max_use_megabytes": 512, + "os_auto_upgrade_type": "security" } } } @@ -128,44 +147,59 @@ Edit and fill in the attributes as applicable. ```json {class="line-numbers linkable-line-numbers"} { "agent": { - "viam-agent": { - "pin_version": "1.2.3" + "version_control": { + "agent": "stable", + "viam-server": "0.52.1" }, - "viam-server": { - "attributes": { - "fast_start": true - } + "advanced_settings": { + "debug": false, + "wait_for_update_check": false, + "viam_server_start_timeout_minutes": 10, + "disable_viam_server": false, + "disable_network_configuration": false, + "disable_system_configuration": false }, - "agent-provisioning": { - "attributes": { - "hotspot_password": "acme123", - "networks": [ - { - "type": "wifi", - "ssid": "fallbackNetOne", - "psk": "myFirstPassword", - "priority": 30 - }, - { - "type": "wifi", - "ssid": "fallbackNetTwo", - "psk": "mySecondPassword", - "priority": 10 - } - ] - } + "network_configuration": { + "manufacturer": "viam", + "model": "custom", + "fragment_id": "", + "hotspot_prefix": "viam-setup", + "hotspot_password": "viamsetup", + "disable_captive_portal_redirect": false, + "offline_before_starting_hotspot_minutes": 2, + "user_idle_minutes": 5, + "retry_connection_timeout_minutes": 10, + "turn_on_hotspot_if_wifi_has_no_internet": false, + "wifi_power_save": null }, - "agent-syscfg": { - "attributes": { - "logging": { - "disable": false, - "system_max_use": "128M", - "runtime_max_use": "96M" - }, - "upgrades": { - "type": "all" - } + "additional_networks": { + { + "type": "wifi", + "interface": "", + "ssid": "fallbackNetOne", + "psk": "myFirstPassword", + "priority": 30, + "ipv4_address": "", + "ipv4_gateway": "", + "ipv4_dns": [], + "ipv4_route_metric": 0 + }, + { + "type": "wifi", + "interface": "", + "ssid": "fallbackNetTwo", + "psk": "mySecondPassword", + "priority": 10, + "ipv4_address": "", + "ipv4_gateway": "", + "ipv4_dns": [], + "ipv4_route_metric": 0 } + }, + "system_configuration": { + "logging_journald_system_max_use_megabytes": 128, + "logging_journald_runtime_max_use_megabytes": 96, + "os_auto_upgrade_type": "all" } } } @@ -174,158 +208,121 @@ Edit and fill in the attributes as applicable. {{% /tab %}} {{< /tabs >}} -### `viam-agent` +## `version_control`: Version management for `viam-agent` and `viam-server` + +By default, when a new version of `viam-server` becomes available, it will automatically download. +When `viam-agent` next restarts, it installs and starts using the new version of `viam-server`. +To ensure that updates only occur when your machines are ready, configure a [maintenance window](/operate/reference/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. -| Option | Type | Required? | Description | -| ------ | ---- | --------- | ----------- | -| `release_channel` | string | Optional | `viam-agent` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default). | -| `pin_version` | string | Optional | Use a specific version for `viam-agent` (as provided by the release channel). If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. | -| `pin_url` | string | Optional | Ignore normal version selection and directly download from the specified URL. If set, no automatic upgrades will be performed until the setting is updated to a new URL (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. | +| Name | Type | Required? | Description | +| ---------- | ---- | --------- | ----------- | +| `agent` | string | true | The version of Viam agent specified as `"5.6.77"`, `"stable"` or by providing a URL such as `"http://example.com/viam-agent-test-aarch64"` or `"file://home/myuser/viam-agent-test-aarch64"`. Viam agent is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Default: `"stable"`. | +| `viam-server` | string | true | The version of `viam-server` specified as `"5.6.77"`, `"stable"` or by providing a URL such as `"http://example.com/viam-agent-test-aarch64"` or `"file://home/myuser/viam-server-test-aarch64"`. `viam-server` is semantically versioned and is tested before release. When set to `"stable"`, `viam-server` will automatically upgrade when a new stable version is released. Default: `"stable"`. | -### `viam-server` +{{< alert title="Important" color="note" >}} +`viam-agent` does not update itself. +You must [restart `viam-agent`](/manage/reference/viam-agent/manage-viam-agent/) or reboot in order to use the new version. +When you stop or restart `viam-agent`, the agent will stop or restart `viam-server` as well. - -| Option | Type | Required? | Description | -| ------ | ---- | --------- | ----------- | -| `release_channel` | string | Optional | `viam-agent` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default), `"latest"`. | -| `pin_version` | string | Optional | Use a specific version for `viam-server` (as provided by the release channel). If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. | -| `pin_url` | string | Optional | Ignore normal version selection and directly download from the specified URL. If set, no automatic upgrades will be performed until the setting is updated to a new URL (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. | -| `disable_subsystem` | boolean | Optional | When set to `true` it disables the management of `viam-server`. | -| `attributes` | object | Optional |
  • `fast_start`: If set to `true`, `viam-agent` will not wait for a network connection nor check for updates before starting `viam-server`. See [Fast start mode](#fast-start-mode).
| +When `viam-server` updates itself, you must restart `viam-server` in order to use the new version. +You can restart `viam-server` from the machine's part status dropdown to the right of your machine’s name on its page in the Viam app. -#### Version updates +{{}} -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](/operate/reference/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. +{{< /alert >}} -#### Fast start mode +For more information on managing `viam-agent` see: -You can use fast start mode to bypass `viam-agent` waiting for a network connection to be established and checking for updates during initial startup. +{{< cards >}} +{{% card link="/manage/reference/viam-agent/manage-viam-agent/" %}} +{{< /cards >}} + +## `advanced_settings` + + +| Name | Type | Required? | Description | +| ---------- | ---- | --------- | ----------- | +| `debug` | boolean | false | Sets the log level to debug for any logging from the Viam agent binary. Default: `false`. | +| `disable_network_configuration` | boolean | false | Disables the network and hotspot configuration, as well as the configuration of additional networks. Default: `false`. | +| `disable_system_configuration` | boolean | false | Disables the system configuration. Default: `false`. | +| `disable_viam_server` | boolean | false | Disable `viam-server` remotely. This option is often used by developers working on Viam agent or when manually running `viam-server`. Default: `false`. | +| `viam_server_start_timeout_minutes` | integer | false | Specify a time after which, if `viam-server` hasn't successfully started, Viam agent will kill it and restart. Default: `10`. | +| `wait_for_update_check` | boolean | false | If set to `true`, `viam-agent` will wait for a network connection and check for updates before starting `viam-server`. See [Reduce startup time](#reduce-startup-time). Default: `false`. | + +### Reduce startup time + +You can set `wait_for_update_check` to `false` to bypass `viam-agent` waiting for a network connection to be established and checking for updates during initial startup. This will result in `viam-server` executing as quickly as possible. This is useful if you have a device that often starts when offline or on a slow connection, and if having the latest version immediately after start isn't required. {{< alert title="Note" color="note" >}} -Period update checks will continue to run afterwards. -The fast start mode only affects the initial startup sequencing. +Periodic update checks will continue to run afterwards. +This setting only affects the initial startup sequencing. {{< /alert >}} You can also start `viam-agent` in fast start mode by setting `VIAM_AGENT_FAST_START=1` in your environment. -### `agent-provisioning` +## `network_configuration` -| Option | Type | Required? | Description | -| ------ | ---- | --------- | ----------- | -| `disable_subsystem` | boolean | Optional | When set to `true` it disables `agent-provisioning` management. | -| `attributes` | object | Optional | You can override all attributes from the [`viam-agent` configuration file](/manage/fleet/provision/setup/#configure-agent-provisioning) here. The [`viam-agent` configuration file](/manage/fleet/provision/setup/#configure-agent-provisioning) is generally customized by the manufacturer to provide "out of the box" settings. The attributes configured in the machine config in the Viam app can let you as the machine user override those if you wish. For security purposes, you should change the `hotspot_password`. You can also configure `roaming_mode` and add any additional networks you want to configure.
  • `hotspot_password`: Overwrite the password set for the WiFi hotspot a machine creates during provisioning.
  • `networks`: Networks a machine can automatically connect to when roaming mode is enabled. See [Networks](#networks).
  • `roaming_mode`: If enabled, lets the machine connect to additional configured networks. See [Networks](#networks).
  • `wifi_power_save`: If set, will explicitly enable or disable power save for all WiFi connections managed by NetworkManager.
| - -#### Networks - -For an already-online device, you can configure new WiFi networks in the machine's [`viam-agent` configuration](/manage/reference/viam-agent/#configuration) in the Viam app. +| Name | Type | Required? | Description | +| ---------- | ---- | --------- | ----------- | +| `device_reboot_after_offline_minutes` | integer | false | If set, `viam-agent` will reboot the device after it has been offline for the specified duration. Default: `0` (disabled). | +| `disable_captive_portal_redirect` | boolean | false | By default, ALL DNS lookups using the provisioning hotspot will redirect to the device. This causes most phones/mobile devices to automatically redirect the user to the captive portal as a "sign in" screen. When disabled, only domains ending in .setup (ex: viam.setup) will be redirected. This generally avoids displaying the portal to users and is mainly used in conjunction with a mobile provisioning application workflow. Default: `false`. | +| `fragment_id` | string | false | The `fragment_id` of the fragment to configure machines with. Required when using the Viam mobile app for provisioning. The Viam mobile app uses the fragment to configure the machine. | +| `hotspot_interface` | string | false | The interface to use for hotspot/provisioning/wifi management. Default: first discovered 802.11 device. | +| `hotspot_password` | string | false | The Wifi password for the provisioning hotspot. Default: `"viamsetup"`. | +| `hotspot_prefix` | string | false | `viam-agent` will prepend this to the hostname of the device and use the resulting string for the provisioning hotspot SSID. Default: `"viam-setup"`. | +| `manufacturer` | string | false | Purely informative. May be displayed on captive portal or provisioning app. Default: `"viam"`. | +| `model` | string | false | Purely informative. May be displayed on captive portal or provisioning app. Default: `"custom"`. | +| `offline_before_starting_hotspot_minutes` | integer | false | Will only enter provisioning mode (hotspot) after being disconnected longer than this time. Useful on flaky connections, or when part of a system where the device may start quickly, but the WiFi/router may take longer to be available. Default: `2` (2 minutes). | +| `retry_connection_timeout_minutes` | integer | Optional | Provisioning mode will exit after this time, to allow other unmanaged (for example wired) or manually configured connections to be tried. Provisioning mode will restart if the connection/online status doesn't change. Default: `10` (10 minutes). | +| `turn_on_hotspot_if_wifi_has_no_internet` | boolean | false | By default, the device will only attempt to connect to a single WiFi network (the one with the highest priority), provided during initial provisioning/setup using the provisioning mobile app or captive web portal. WiFi connection alone is enough to consider the device as "online" even if the global internet is not reachable. If the primary network configured during provisioning cannot be connected to and `turn_on_hotspot_if_wifi_has_no_internet` is enabled, the device will attempt connections to all configured networks in `networks`, and only consider the device online if the internet is reachable. Default: `false`. | +| `user_idle_minutes` | integer | false | Amount of time before considering a user (using the captive web portal or provisioning app) idle, and resuming normal behavior. Used to avoid interrupting provisioning mode (for example for network tests/retries) when a user might be busy entering details. Default: `5` (5 minutes). | +| `wifi_power_save` | boolean | false | If set, will explicitly enable or disable power save for all WiFi connections managed by NetworkManager. If not set, the system default applies. Default: `false`. | + +For more detailed instructions on what these settings do, see [Provisioning](https://docs.viam.com/manage/fleet/provision/setup/#configure-agent-provisioning). + +## `additional_networks` + +For an already-online device, you can configure new WiFi or wired networks in the machine's [`viam-agent` configuration](/manage/reference/viam-agent/#configuration) in the Viam app. It's primarily useful for a machine that moves between different networks, so the machine can automatically connect when moved between locations. + +| Name | Type | Required? | Description | +| ---------- | ---- | --------- | ----------- | +| `interface` | string | optional | Name of interface, for example: `"wlan0"`, `"eth0"`, `"enp14s0"`. Default: `""`. | +| `ipv4_address` | string | optional | IPv4 address in CIDR format, for example: `"192.168.0.1/24"`. Default: `"auto"`. | +| `ipv4_dns` | string | optional | Array of IPv4 DNS such as `["192.168.0.254", "8.8.8.8"]`. Default: `[]`. | +| `ipv4_gateway` | string | optional | IPv4 gateway. Default: `""`. | +| `ipv4_route_metric` | integer | optional | IPv4 route metric. Lower values are preferred. Default: `0` which defaults to `100` for wired networks and `600` for wireless network. | +| `priority` | integer | optional | Priority to choose the network with. Values between -999 and 999 with higher values taking precedence. Default: `0`. | +| `psk` | string | optional | The network passkey. Default: `""`. | +| `ssid` | string | optional | The WiFi network's SSID. Only needed for WiFi networks. Default: `""`. | +| `type` | string | optional | The type of the network. Required if a network is provided. Options: `"wifi"`, `"wired"`. | + To add additional networks add them using the JSON editor for your device's config in the Viam app. {{< alert title="Important" color="note" >}} -You must enable `roaming_mode` in the [`agent-provisioning` configuration](#configuration) to allow the machine to connect to the specified networks. +You must enable `turn_on_hotspot_if_wifi_has_no_internet` in the [`agent-provisioning` configuration](#configuration) to allow the machine to connect to the specified networks. Note that 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 >}} -If `roaming_mode` is enabled, `agent-provisioning` will try to connect to each specified network in order of `priority` from highest to lowest. +If `turn_on_hotspot_if_wifi_has_no_internet` is enabled, `agent-provisioning` will try to connect to each specified network in order of `priority` from highest to lowest. If the highest-priority network is not available or the machine can connect but internet is not available, `viam-agent` will then attempt to connect to the next-highest network, and so on until all configured networks have been tried. - -| Name | Type | Description | -| ---------- | ------ | ----------- | -| `type` | string | The type of the network. Options: `"wifi"`| -| `ssid` | string | The network's SSID. | -| `psk` | string | The network pass key. | -| `priority` | int | Priority to choose the network with. Values between -999 and 999. Default: `0`. | - -The following configuration defines the connection information and credentials for two WiFi networks named `fallbackNetOne` and `fallbackNetTwo`: - -```json {class="line-numbers linkable-line-numbers"} -... -"agent": { - "agent-provisioning": { - ... - "attributes": { - ... - "roaming_mode": true, - "networks": [ - { - "type": "wifi", - "ssid": "fallbackNetOne", - "psk": "myFirstPassword", - "priority": 30 - }, - { - "type": "wifi", - "ssid": "fallbackNetTwo", - "psk": "mySecondPassword", - "priority": 10 - } - ] - } - } -} -``` - -### `agent-syscfg` - -`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. +## `system-configuration` -| Option | Type | Required? | Description | -| ------ | ---- | --------- | ----------- | -| `disable_subsystem` | boolean | Optional | When set to `true` it disables `agent-syscfg`. | -| `attributes` | object | Optional |
  • `logging`: parameters for logging
    • `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`.
    • `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`.
    • `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.
  • `upgrades`: using `upgrades` installs the `unattended-upgrades` package, and replace `20auto-upgrades` and `50unattended-upgrades` in /etc/apt/apt.conf.d/, 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.
    • `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).
| - -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: - -```json {class="line-numbers linkable-line-numbers"} -"agent-syscfg": { - "release_channel": "stable", - "attributes": { - "logging": { - "disable": false, - "system_max_use": "128M", - "runtime_max_use": "96M" - }, - "upgrades": { - "type": "all" - } - } -} -``` - -## Version management for `viam-agent` and `viam-server` - -By default, `viam-agent` automatically updates both itself and `viam-server` as new updates are released. -You can configure update behavior using the [Viam app](https://app.viam.com/). -To ensure that updates only occur when your machines are ready, configure a [maintenance window](/operate/reference/viam-server/#maintenance-window). - -To use a specific version of `viam-agent` and `viam-server`, you can pin the version. +| Name | Type | Required? | Description | +| ---------- | ---- | --------- | ----------- | +| `logging_journald_runtime_max_use_megabytes` | integer | optional |Set the temporary space limit for logs. `-1` to disable. Default: `512` (512 MB). | +| `logging_journald_system_max_use_megabytes` | integer | optional | Sets the maximum disk space `journald` will use for persistent log storage. `-1` to disable. Default: `512` (512 MB). | +| `os_auto_upgrade_type` | boolean | optional | Manage OS package updates using Viam by setting this field. Installs the `unattended-upgrades` package, and replace `20auto-upgrades` and `50unattended-upgrades` in /etc/apt/apt.conf.d/, 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. Options: `"all"` (automatic upgrades are performed for all packages), `"security"` (automatic upgrades for only packages containing `"security"` in their codename (for example `bookworm-security`)), `"disable"` (disable automatic upgrades), `""` (do not change system settings). Default: `""`. | -{{< alert title="Important" color="note" >}} -When `viam-agent` updates itself, you must [restart `viam-agent`](/manage/reference/viam-agent/manage-viam-agent/) or reboot in order to use the new version. -When you stop or restart `viam-agent`, the agent will stop or restart `viam-server` as well. - -When `viam-server` updates itself, you must restart `viam-server` in order to use the new version. -You can restart `viam-server` from the machine's part status dropdown to the right of your machine’s name on its page in the Viam app. - -{{}} - -{{< /alert >}} - -For more information on managing `viam-agent` see: - -{{< cards >}} -{{% card link="/manage/reference/viam-agent/manage-viam-agent/" %}} -{{< /cards >}} +For more detailed instructions, see [Configure machine settings](https://docs.viam.com/manage/fleet/system-settings/). ## Agent logs