diff --git a/docs/fleet/provision.md b/docs/fleet/provision.md index 1569bf429b0..d5079c325da 100644 --- a/docs/fleet/provision.md +++ b/docs/fleet/provision.md @@ -12,141 +12,6 @@ aliases: - "/build/provision/" --- -{{}} - -You can use Viam's software provisioning manager, the _Viam Agent_, to provision a machine as it first comes online with a pre-defined configuration. -This is useful when deploying a fleet of machines directly from the factory to a customer, or when bundling proprietary software on your Viam machine. -You can install the Viam Agent on your machines as part of your build process, and then have the Viam Agent perform the rest of the first-time setup for your machine once deployed to a customer, or to the field. - -The Viam Agent: - -- Automatically connects to a pre-configured WiFi network, or creates its own wireless hotspot if no pre-configured WiFi network is detected. -- Installs `viam-server` as a static binary, removing the need to perform any library linking or dependency installation during first-time setup. - You can also use a custom build of `viam-server`, if needed. -- Provides automatic updates for `viam-server`, the agent itself, and any configured subsystems (such as the Agent Provisioning subsystem). -- Allows control of deployed software versions through the Viam app. - -Consider a company that sells machines that monitor weather conditions on a maritime craft and provide navigation advice based on those readings. -Such a machine might use Viam to interface between a [sensor component](/components/sensor/) that takes weather measurements, and the [data management service](/services/data/) to regularly upload a stream of readings, for example. -However, to then parse the readings and provide tailored guidance to a ship's captain, the company has written their own proprietary application which includes live analytics and speech generation for conveying advice to the captain. - -Using the Viam Agent, this company could ship their machines directly to customers and have each machine provision `viam-server` as it comes online for each user, eliminating factory setup time and allowing for tailored configurations per customer as needed. - -{{% alert title="Note" color="note" %}} -The example video above shows using the [Viam mobile application](/fleet/#the-viam-mobile-app) to connect to the Viam Agent on a newly-deployed machine and completing network setup. -{{% /alert %}} - -The Viam Agent is open source, and available on [GitHub](https://github.com/viamrobotics/agent). - -## Install the Viam Agent - -You can install the Viam Agent using either an existing machine's part ID and API key, or using an existing /etc/viam.json configuration file. - -{{< alert title="Important" color="note" >}} -The Viam Agent supports the Linux `x86_64` and `aarch64` architectures only. -Your machine must have `curl` available in order to install the Viam Agent. -{{< /alert >}} - -{{< tabs >}} -{{% tab name="Install using a part ID" %}} - -If you want to install the Viam Agent on a machine that you have already configured in the Viam app, follow these steps: - -1. Determine your machine {{< glossary_tooltip term_id="part" text="part's" >}} ID. - To copy the ID of your machine part, select the part status dropdown to the right of your machine's location and name on the top of its page and click the copy icon next to **Part ID**. - For an example, see [Find part ID](/appendix/apis/data-client/#find-part-id) -1. Determine your machine's [API key and API key ID](/sdks/#authentication). - If you haven't already, you can [use the CLI to create a new API key and API key ID](/cli/#create-an-organization-api-key). -1. Run the following command, replacing ``, ``, and `` with your machine's values as determined from the steps above: - - ```sh {class="command-line" data-prompt="$"} - sudo /bin/sh -c "VIAM_API_KEY_ID= VIAM_API_KEY= VIAM_PART_ID=; $(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" - ``` - -{{% /tab %}} -{{% tab name="Install using a configuration file" %}} - -If you want to install the Viam Agent on a machine that you have not yet created in the Viam app, follow these steps: - -1. Create a configuration file with the desired configuration for your machine. You can: - - - You can [create a new machine in the Viam app](/cloud/machines/#add-a-new-machine) and configure it as desired, then switch to **Raw JSON** mode and copy the configuration shown into a new file on your machine. - - You can base your configuration on the [example configuration file](/internals/local-configuration-file/#example-json-configuration-file), and adjust as needed. - - You can use an existing configuration file from a deployed machine, or adapt such a file as needed to fit the specifications of your new machine. - -1. Place this file in the following location on the machine you wish to install the Viam Agent to: /etc/viam.json - -1. Run the following command to install the Viam Agent on your machine: - - ```sh {class="command-line" data-prompt="$"} - sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" - ``` - -{{% /tab %}} -{{< /tabs >}} - -### Update the Viam Agent and `viam-server` - -The Viam Agent automatically updates both itself and `viam-server` as new updates are released. -You can also configure update behavior for the Agent and `viam-server` using the [Viam app](https://app.viam.com/). - -{{< alert title="Important" color="note" >}} -When the Viam Agent updates either itself or `viam-server`, you must restart these services in order to use the new version. -When you stop or restart the Viam Agent, the agent will stop or restart `viam-server` as well. -{{< /alert >}} - -### Manage the Viam Agent - -The Viam Agent is installed as a `systemd` service named `viam-agent`. - -- To start the Viam Agent: - - ```sh {class="command-line" data-prompt="$"} - sudo systemctl start viam-agent - ``` - -- To stop the Viam Agent: - - {{< alert title="Alert" color="note" >}} - When you stop the Viam Agent, the agent will stop `viam-server` as well. - {{< /alert >}} - - ```sh {class="command-line" data-prompt="$"} - sudo systemctl stop viam-agent - ``` - -- To restart the Viam Agent: - - {{< alert title="Alert" color="note" >}} - When you restart the Viam Agent, the agent will restart `viam-server` as well. - {{< /alert >}} - - ```sh {class="command-line" data-prompt="$"} - sudo systemctl restart viam-agent - ``` - -- To completely uninstall the Viam Agent and `viam-server`, run the following command: - - ```sh {class="command-line" data-prompt="$"} - sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/uninstall.sh)" - ``` - - This command uninstalls Viam Agent, `viam-server`, the machine configuration file (/etc/viam.json), and the provisioning configuration file (/etc/viam-provisioning.json). - - For more information, see [Viam Agent management](https://github.com/viamrobotics/agent#management). - -### View Viam Agent logs - -The Viam Agent writes log messages to the [Viam app](https://app.viam.com/). -You can find these messages on the [**LOGS** tab](/cloud/machines/#logs) of your machine's page. - -Viam Agent only sends messages when your machine is online and connected to the internet. -If your machine is offline, log messages are queued, and are sent to the Viam app once your machine reconnects to the internet. - -These log messages include when `viam-server` is stopped and started, the status of agent subsystems, and any errors or warnings encountered during operation. - -## Provision a new machine - With the Viam Agent installed, your machine will either connect to a local WiFi network or will create its own WiFi hotspot, depending on your configuration. - If you include a `viam-server` configuration file on your machine, located at /etc/viam.json, which includes a WiFi network and password to connect to, the Viam Agent will connect to the network automatically when in range. @@ -160,104 +25,6 @@ With the Viam Agent installed, your machine will either connect to a local WiFi This provisioning functionality is provided by the [Viam Agent provisioning subsystem](https://github.com/viamrobotics/agent-provisioning). -### Connect to an existing network - -When you provision machines using the Viam app or the Viam mobile app, you provide network information that a machine will use to connect as the primary network. - -If you provide a primary network using the Viam app or the Viam mobile app, the Viam Agent will -connect to that network, even if that network does not have internet access. -The Viam agent **will not** consider other networks provided in the `agent` configuration in this case. - -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 the Viam Agent to require that a WiFi network be connected to the internet in order to connect to it, use [roaming mode](#use-roaming-mode). - -If the configured WiFi network could not be connected to, the Viam Agent will instead [create its own WiFi hotspot](#create-a-wifi-hotspot). - -You can configure how long the Agent waits for connections and the timeout before it creates a hotspot in the [provisioning configuration file](#use-a-provisioning-configuration-file). - -#### Use roaming mode - -Roaming mode allows you to specify multiple WiFi networks, each with their own priority, and the Viam Agent will try to connect to each specified network in order of priority from highest to lowest. - -**Note that if the primary network is available and the machine can connect to it, the Viam agent will always connect to that network, even if the network does not have internet access. -** - -If the Viam Agent configuration enables roaming and no primary network is provided or a machine cannot connect to the primary network, the Viam Agent will attempt to connect to any additional WiFi networks specified in your Viam Agent configuration file in order of highest `priority`. - -For example, 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": { - ... - "networks": [ - { - "type": "wifi", - "ssid": "fallbackNetOne", - "psk": "myFirstPassword", - "priority": 30 - }, - { - "type": "wifi", - "ssid": "fallbackNetTwo", - "psk": "mySecondPassword", - "priority": 10 - } - ] - } - } -} -``` - -| 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 100. Default: `0`. | - -If the highest-priority network is not available or the machine can connect but internet is not available, the Viam Agent will then attempt to connect to the next-highest `priority` network, and so on until all configured networks have been tried. - -You can add this configuration to the /etc/viam.json configuration file you deploy to your machine, or from the **CONFIGURE** tab in the [Viam app](https://app.viam.com/) for your machine, using **Raw JSON** mode. - -### Create a WiFi hotspot - -If you did not include a `viam-server` configuration file on your machine, or none of the configured WiFi networks are available when your machine comes online, the Viam Agent will create its own WiFi hotspot that you can connect to in order to complete provisioning. - -By default, the hotspot network is named `viam-setup-HOSTNAME`, where `HOSTNAME` is replaced with the hostname of your machine. -The WiFi password for this network is `viamsetup` by default. - -You can customize these values in the `agent` configuration object in your `viam-server` configuration file. -For example, to set the hotspot password to `acme123`, you can use the following configuration: - -```json {class="line-numbers linkable-line-numbers"} -... -"agent": { - "agent-provisioning": { - ... - "attributes": { - "hotspot_password": "acme123" - ... - } - } -} -``` - -You can add this configuration to your machine's configuration in the **CONFIGURE** tab in the [Viam app](https://app.viam.com/), using **JSON** mode, or directly to the /etc/viam.json configuration file you deploy to your machine. - -If you did not initially provide a `viam-server` app configuration in either of these methods, you will be prompted to paste one in when you connect to the WiFi hotspot. -This is the JSON which contains your machine part secret key and cloud app address, which your machine's `viam-server` instance needs to connect to the Viam app. - -To copy a machine's `viam-server` app configuration: - -- Navigate to your machine's page on [the Viam app](https://app.viam.com) and select the **CONFIGURE** tab. -- Select the part status dropdown to the right of your machine's name on the top of the page: {{}} -- Click the copy icon underneath **Viam server configuration** to copy the `viam-server` app JSON configuration. -- Paste the `viam-server` app config into your terminal when prompted. - ## Use a pre-install script When you install the Viam Agent, either manually using the commands above or automatically as part of your fleet's build and deploy process, you can choose to run a pre-install script to perform provisioning steps before deployment to the target machine. diff --git a/docs/installation/agent.md b/docs/installation/agent.md new file mode 100644 index 00000000000..ba07d17005c --- /dev/null +++ b/docs/installation/agent.md @@ -0,0 +1,288 @@ +--- +title: "Viam Agent" +linkTitle: "Viam Agent" +weight: 50 +no_list: true +type: docs +description: "TODO" +# SMEs: James, Ale +aliases: + - "/build/provision/" + - "/fleet/provision/" +--- + +The [Viam Agent](https://github.com/viamrobotics/agent) is a self-updating service manager that maintains the lifecycle for `viam-server` and other Viam provided system services [TODO: clarify which ones]. + +The Viam Agent: + +- Automatically connects to a pre-configured WiFi network, or creates its own wireless hotspot if no pre-configured WiFi network is detected. +- Installs `viam-server` as a static binary, removing the need to perform any library linking or dependency installation during first-time setup. + You can also use a custom build of `viam-server`, if needed. +- Provides automatic updates for `viam-server`, the agent itself, and any configured subsystems (such as the Agent Provisioning subsystem). +- Allows control of deployed software versions through the Viam app. + +{{< alert title="Support notice" color="info" >}} +Currently, viam-agent is only supported on Linux, for amd64 (x86_64) and arm64 (aarch64) CPUs. +{{< /alert >}} + +## Installation + +You can install the Viam Agent using either an existing machine's part ID and API key, or using an existing /etc/viam.json configuration file. + +{{< alert title="Important" color="note" >}} +The Viam Agent supports the Linux `x86_64` and `aarch64` architectures only. +Your machine must have `curl` available in order to install the Viam Agent. +{{< /alert >}} + +{{< tabs >}} +{{% tab name="Install using a part ID" %}} + +If you want to install the Viam Agent on a machine that you have already configured in the Viam app, follow these steps: + +1. Determine your machine {{< glossary_tooltip term_id="part" text="part's" >}} ID. + To copy the ID of your machine part, select the part status dropdown to the right of your machine's location and name on the top of its page and click the copy icon next to **Part ID**. + For an example, see [Find part ID](/appendix/apis/data-client/#find-part-id) +1. Determine your machine's [API key and API key ID](/sdks/#authentication). + If you haven't already, you can [use the CLI to create a new API key and API key ID](/cli/#create-an-organization-api-key). +1. Run the following command, replacing ``, ``, and `` with your machine's values as determined from the steps above: + + ```sh {class="command-line" data-prompt="$"} + sudo /bin/sh -c "VIAM_API_KEY_ID= VIAM_API_KEY= VIAM_PART_ID=; $(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" + ``` + +{{% /tab %}} +{{% tab name="Install using a configuration file" %}} + +If you want to install the Viam Agent on a machine that you have not yet created in the Viam app, follow these steps: + +1. Create a configuration file with the desired configuration for your machine. You can: + + - You can [create a new machine in the Viam app](/cloud/machines/#add-a-new-machine) and configure it as desired, then switch to **Raw JSON** mode and copy the configuration shown into a new file on your machine. + - You can base your configuration on the [example configuration file](/internals/local-configuration-file/#example-json-configuration-file), and adjust as needed. + - You can use an existing configuration file from a deployed machine, or adapt such a file as needed to fit the specifications of your new machine. + +1. Place this file in the following location on the machine you wish to install the Viam Agent to: /etc/viam.json + +1. Run the following command to install the Viam Agent on your machine: + + ```sh {class="command-line" data-prompt="$"} + sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" + ``` + +{{% /tab %}} +{{< /tabs >}} + +To see how to provision machines using the Viam Agent, see + +{{< cards >}} + {{% card link="/fleet/provisioning/" %}} +{{< /cards >}} + +## Configuration + +{{< tabs >}} +{{% tab name="Template" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "manufacturer": "Skywalker", + "model": "C-3PO", + "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663", + "hotspot_prefix": "skywalker-setup", + "disable_dns_redirect": true, + "hotspot_password": "skywalker123", + "roaming_mode": false, + "offline_timeout": "3m30s", + "user_timeout": "2m30s", + "fallback_timeout": "15m" +} +``` + +{{% /tab %}} +{{% tab name="Example" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "manufacturer": "Skywalker", + "model": "C-3PO", + "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663", + "hotspot_prefix": "skywalker-setup", + "disable_dns_redirect": true, + "hotspot_password": "skywalker123", + "roaming_mode": false, + "offline_timeout": "3m30s", + "user_timeout": "2m30s", + "fallback_timeout": "15m" +} +``` + +{{% /tab %}} +{{< /tabs >}} + +### Attributes + + +| Name | Type | Required? | Description | +| ---------- | ------ | --------- | ----------- | +| `manufacturer` | string | Optional | Purely informative. May be displayed on captive portal and/or mobile app. Default: `"viam"`. | +| `model` | string | Optional | Purely informative. May be displayed on captive portal and/or mobile app. Default: `"custom"`. | +| `fragment_id` | string | Optional | The `fragment_id` of the fragment to configure machines with. If present, the Viam mobile app can pre-configure a robot for a user by using this [TODO: and otherwise it can't??]. | +| `hotspot_prefix` | string | Optional | Viam agent will prepend this to the hostname of the device append and use the resulting string for the provisioning hotspot SSID. Default: `"viam-setup"`. | +| `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`. | +| `hotspot_password` | string | Optional | The Wifi password for provisioning hotspot. Default: `"viamsetup"`. | +| `roaming_mode` | boolean | Optional | By default, the device will only attempt to connect to a single wifi network (the one with the highest priority), usually provided during initial provisioning/setup using the Viam app or the Viam mobile app. Wifi connection alone is enough to consider the device as "online" even if the global internet is not reachable. When enabled, the device will attempt connections to all configured networks, and only considers the device online if the internet is reachable. See [Roaming Mode](#roaming-mode). 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 provisioning portal using web or mobile 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` | boolean | Optional | The type of the network. See [Networks](#networks). Default: `[]`. | + +### Networks + +When you provision machines using the Viam app or the Viam mobile app, you provide network information that a machine will use to connect as the primary network. + +If you provide a primary network using the Viam app or the Viam mobile app, the Viam Agent will +connect to that network, even if that network does not have internet access. +The Viam agent **will not** consider other networks provided in the `agent` configuration in this case. + +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 the Viam Agent to require that a WiFi network be connected to the internet in order to connect to it, use [roaming mode](#use-roaming-mode). + +If the configured WiFi network could not be connected to, the Viam Agent will instead [create its own WiFi hotspot](#create-a-wifi-hotspot). + +You can configure how long the Agent waits for connections and the timeout before it creates a hotspot in the [provisioning configuration file](#use-a-provisioning-configuration-file). + +#### Roaming mode + +Roaming mode allows you to specify multiple WiFi networks, each with their own priority, and the Viam Agent will try to connect to each specified network in order of priority from highest to lowest. + +You must enable `roaming_mode` in the Viam Agent configuration to use roaming mode. + +{{< alert title="Important" color="important" >}} +Note that if the primary network is available and the machine can connect to it, the Viam agent will always connect to that network, even if the network does not have internet access. +{{< /alert >}} + +If the Viam Agent configuration enables roaming and no primary network is provided or a machine cannot connect to the primary network, the Viam Agent will attempt to connect to any additional WiFi networks specified in your Viam Agent configuration file in order of highest `priority`. + +For example, 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": { + ... + "networks": [ + { + "type": "wifi", + "ssid": "fallbackNetOne", + "psk": "myFirstPassword", + "priority": 30 + }, + { + "type": "wifi", + "ssid": "fallbackNetTwo", + "psk": "mySecondPassword", + "priority": 10 + } + ] + } + } +} +``` + +| 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 100. Default: `0`. | + +If the highest-priority network is not available or the machine can connect but internet is not available, the Viam Agent will then attempt to connect to the next-highest `priority` network, and so on until all configured networks have been tried. + +You can add this configuration to the /etc/viam.json configuration file you deploy to your machine, or from the **CONFIGURE** tab in the [Viam app](https://app.viam.com/) for your machine, using **Raw JSON** mode. + +### Create a WiFi hotspot + +If you did not include a `viam-server` configuration file on your machine, or none of the configured WiFi networks are available when your machine comes online, the Viam Agent will create its own WiFi hotspot that you can connect to in order to complete provisioning. + +By default, the hotspot network is named `viam-setup-HOSTNAME`, where `HOSTNAME` is replaced with the hostname of your machine. +The WiFi password for this network is `viamsetup` by default. + +You can customize these values in the `agent` configuration object in your `viam-server` configuration file. +For example, to set the hotspot password to `acme123`, you can use the following configuration: + +```json {class="line-numbers linkable-line-numbers"} +... +"agent": { + "agent-provisioning": { + ... + "attributes": { + "hotspot_password": "acme123" + ... + } + } +} +``` + +You can add this configuration to your machine's configuration in the **CONFIGURE** tab in the [Viam app](https://app.viam.com/), using **JSON** mode, or directly to the /etc/viam.json configuration file you deploy to your machine. + +If you did not initially provide a `viam-server` app configuration in either of these methods, you will be prompted to paste one in when you connect to the WiFi hotspot. +This is the JSON which contains your machine part secret key and cloud app address, which your machine's `viam-server` instance needs to connect to the Viam app. + +To copy a machine's `viam-server` app configuration: + +- Navigate to your machine's page on [the Viam app](https://app.viam.com) and select the **CONFIGURE** tab. +- Select the part status dropdown to the right of your machine's name on the top of the page: {{}} +- Click the copy icon underneath **Viam server configuration** to copy the `viam-server` app JSON configuration. +- Paste the `viam-server` app config into your terminal when prompted. + +## Agent logs + +The Viam Agent writes log messages to the [Viam app](https://app.viam.com/). +You can find these messages on the [**LOGS** tab](/cloud/machines/#logs) of your machine's page. + +Viam Agent only sends messages when your machine is online and connected to the internet. +If your machine is offline, log messages are queued, and are sent to the Viam app once your machine reconnects to the internet. + +These log messages include when `viam-server` is stopped and started, the status of agent subsystems, and any errors or warnings encountered during operation. + +## Provisioning + +{{}} + +You can use Viam's software provisioning manager, the _Viam Agent_, to provision a machine as it first comes online with a pre-defined configuration. +This is useful when deploying a fleet of machines directly from the factory to a customer, or when bundling proprietary software on your Viam machine. +You can install the Viam Agent on your machines as part of your build process, and then have the Viam Agent perform the rest of the first-time setup for your machine once deployed to a customer, or to the field. + +Consider a company that sells machines that monitor weather conditions on a maritime craft and provide navigation advice based on those readings. +Such a machine might use Viam to interface between a [sensor component](/components/sensor/) that takes weather measurements, and the [data management service](/services/data/) to regularly upload a stream of readings, for example. +However, to then parse the readings and provide tailored guidance to a ship's captain, the company has written their own proprietary application which includes live analytics and speech generation for conveying advice to the captain. + +Using the Viam Agent, this company could ship their machines directly to customers and have each machine provision `viam-server` as it comes online for each user, eliminating factory setup time and allowing for tailored configurations per customer as needed. + +{{% alert title="Note" color="note" %}} +The example video above shows using the [Viam mobile application](/fleet/#the-viam-mobile-app) to connect to the Viam Agent on a newly-deployed machine and completing network setup. +{{% /alert %}} + +{{< cards >}} + {{% card link="/fleet/provision/" %}} +{{< /cards >}} + +## System management + +### Update the Viam Agent and `viam-server` + +The Viam Agent automatically updates both itself and `viam-server` as new updates are released. +You can configure update behavior for the Agent and `viam-server` using the [Viam app](https://app.viam.com/). + +{{< alert title="Important" color="note" >}} +When the Viam Agent updates either itself or `viam-server`, you must restart these services in order to use the new version. +When you stop or restart the Viam Agent, the agent will stop or restart `viam-server` as well. +{{< /alert >}} + +For more information on managing Viam Agent see: + +{{< cards >}} + {{% card link="/installation/manage-viam-agent/" %}} +{{< /cards >}} \ No newline at end of file diff --git a/docs/installation/manage-viam-agent.md b/docs/installation/manage-viam-agent.md new file mode 100644 index 00000000000..c523fc93e7f --- /dev/null +++ b/docs/installation/manage-viam-agent.md @@ -0,0 +1,55 @@ +--- +title: "Manage Viam Agent" +linkTitle: "Manage Viam Agent" +weight: 30 +no_list: true +type: docs +draft: false +images: ["/installation/thumbnails/manage.png"] +imageAlt: "Manage Viam Agent" +description: "Control and troubleshoot viam-agent." +--- + +### Manage the Viam Agent + +The Viam Agent is installed as a `systemd` service named `viam-agent`. + +- To start the Viam Agent: + + ```sh {class="command-line" data-prompt="$"} + sudo systemctl start viam-agent + ``` + +- To stop the Viam Agent: + + {{< alert title="Alert" color="note" >}} + When you stop the Viam Agent, the agent will stop `viam-server` as well. + {{< /alert >}} + + ```sh {class="command-line" data-prompt="$"} + sudo systemctl stop viam-agent + ``` + +- To restart the Viam Agent: + + {{< alert title="Alert" color="note" >}} + When you restart the Viam Agent, the agent will restart `viam-server` as well. + {{< /alert >}} + + ```sh {class="command-line" data-prompt="$"} + sudo systemctl restart viam-agent + ``` + +- To completely uninstall the Viam Agent and `viam-server`, run the following command: + + ```sh {class="command-line" data-prompt="$"} + sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/uninstall.sh)" + ``` + + This command uninstalls Viam Agent, `viam-server`, the machine configuration file (/etc/viam.json), and the provisioning configuration file (/etc/viam-provisioning.json). + + For more information, see [Viam Agent management](https://github.com/viamrobotics/agent#management). + +## Troubleshooting + +You can find additional assistance in the [Troubleshooting section](/appendix/troubleshooting/). diff --git a/docs/installation/manage/_index.md b/docs/installation/manage-viam-server.md similarity index 100% rename from docs/installation/manage/_index.md rename to docs/installation/manage-viam-server.md