Update machine settings information #3772
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,195 @@ | ||
| --- | ||
| 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) | ||
|
|
||
| ## Configure OS package updates | ||
|
|
||
| By default, the configuration in <FILE>/etc/apt/apt.conf.d/</FILE> determines the behavior for updating operating system packages. | ||
| 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). | ||
|
|
||
| ### Automatically upgrade all packages | ||
|
|
||
| When set, `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. | ||
|
|
||
| To set automatic upgrades for all packages, add the `upgrades` field to the `agent-syscfg`'s `attributes` object as following. | ||
| You may need to add the `agent-syscfg` object to the `agent` object if it doesn't already exist. | ||
|
|
||
|
|
||
| ```json | ||
| "agent": { | ||
| "agent-syscfg": { | ||
| "release_channel": "stable", | ||
| "attributes": { | ||
| "upgrades": { | ||
| "type": "all" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Automatically upgrade security packages | ||
|
|
||
| When set, `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. | ||
|
|
||
| To set automatic upgrades for packages containing `"security"` in their codename (for example `bookworm-security`), add the `upgrades` field to the `agent-syscfg`'s `attributes` object as following. | ||
| You may need to add the `agent-syscfg` object to the `agent` object if it doesn't already exist. | ||
|
There was a problem hiding this comment. Why is this explanation repeated for every option here? Wouldn't it make more sense to just explain the overall purpose once at the top? |
||
|
|
||
| ```json | ||
| "agent": { | ||
| "agent-syscfg": { | ||
| "release_channel": "stable", | ||
| "attributes": { | ||
| "upgrades": { | ||
| "type": "security" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Disable automatic upgrades | ||
|
|
||
| When set, `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. | ||
|
|
||
| To set automatic upgrades, add the `upgrades` 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. | ||
|
|
||
| ```json | ||
| "agent": { | ||
| "agent-syscfg": { | ||
| "release_channel": "stable", | ||
| "attributes": { | ||
| "upgrades": { | ||
| "type": "disabled" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## 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 operating system defaults determine the disk space that `journald` uses to persist logs. | ||
| 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). | ||
npentrel marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
|
There was a problem hiding this comment. This should probably link to the docs for journald, which better explain what exactly these two fields mean. https://www.freedesktop.org/software/systemd/man/latest/journald.conf.html#SystemMaxUse= There was a problem hiding this comment. Should mention that if NOT set, both of these fields are set to 512MB by default (unless disable is set.) There was a problem hiding this comment. Does that mean this sentence is wrong or that the moment we set a logging value even if it is empty the value 512 is used? There was a problem hiding this comment. Correct. We enforce 512MB by default (per request from Eliot) when this is not set, which is typically smaller than most OS defaults. That's why I added the "disable" option to avoid this for people that don't want it changed. |
||
| ### 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 will be used: | ||
|
|
||
| ```json | ||
| "agent": { | ||
| "agent-syscfg": { | ||
| "release_channel": "stable", | ||
| "attributes": { | ||
| "logging": { | ||
| "disable": true | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm unclear why a single field is explained in full three different times, with full json examples for each, when all that changes is one word. Wouldn't it be a lot easier to understand if the field was explained, and then just state that there are three options for "type"?