aos-prov

Introduction

aos-prov is the AosEdge provisioning CLI tool. It connects to a Unit or VM via gRPC and registers it with AosCloud using your user certificate.

Use it to:

• Download AosCore image
• Use your own disk images to create a unit
• Provision a physical AosCore-powered device
• Create and provision a development VM Unit
• Expand a VM Unit by adding nodes
• Remove nodes from a VM Unit
• Manage VMs group Unit

Prerequisites

1. Installed aos-prov tool. Refer Install Aos CLI Tools.

   Checking the tool version

   To check the tool is the latest version run command:

   Windows

   ~/.aos/venv/Scripts/python -m aos_prov check-version

   macOS/Linux

   ~/.aos/venv/bin/python3 -m aos_prov check-version

   empty output means the tool is up to date.

2. AosCloud OEM User certificate — a .p12 file issued by AosCloud OEM enrollment.
   Default location: ~/.aos/security/aos-user-oem.p12

   Getting the user certificate info

   To check that you have a valid user certificate run command:

   Windows

   ~/.aos/venv/Scripts/python -m aos_keys info --oem

   macOS/Linux

   ~/.aos/venv/bin/python3 -m aos_keys info --oem

   You will see Certificate info and AosCloud user info.

   If your certificate is in a different location, pass it explicitly with -p <PATH>.

   ... aos_prov <COMMAND> -p /path/to/certificate.p12   

3. One of the following:

   • Unit reachable on the network — required for provision. The Unit must be powered on and accessible via IP.
   • Oracle VirtualBox 7+ installed and AosCore disk image — required for VM operations (vm-new, unit-new, unit-node-add). Download it with the download command or obtain it from your AosEdge administrator.

Download AosCore image

Use the download command to download AosCore VM disk images required for creating and managing development VM Units.

The downloaded images are saved to the default downloads directory:

~/.aos/downloads

The command downloads the images used by VM operations such as unit-new, vm-new, and unit-node-add.

Run the command:

Windows

~/.aos/venv/Scripts/python -m aos_prov download

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov download

Expected result: AosCore VM disk images are downloaded to ~/.aos/downloads.

After download, the directory contains the disk images used for VM Units:

• aos-vm-main-genericx86-64.vmdk — disk image for the main node.
• aos-vm-secondary-genericx86-64.vmdk — disk image for secondary nodes.

To download an image from a custom address, use the -a option:

~/.aos/venv/bin/python3 -m aos_prov download -a [DOWNLOAD_ADDRESS]

To overwrite existing downloaded images, add the -f option:

~/.aos/venv/bin/python3 -m aos_prov download -f

Use your own disk images to create a unit

If you want to create Unit from own disk images, you have to replace image files in the default folder.
Images located in ~/.aos/downloads directory.

There are two files:

• aos-vm-main-genericx86-64.vmdk - the main node of the Unit
• aos-vm-secondary-genericx86-64.vmdk - all secondary nodes

After replacing the files, create a Unit with the unit-new command.

Provision a physical AosCore-powered device

AosUnit is created from prebuilt AosCore disk images. Connect your device to the network and turn on the power. Find the device's global IP address.

Run the provision command with the -u option and the device's global IP address.

Windows

~/.aos/venv/Scripts/python -m aos_prov provision -u <IP_ADDRESS>:<PORT>

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov provision -u <IP_ADDRESS>:<PORT>

Example:

~/.aos/venv/bin/python3 -m aos_prov provision -u 192.168.1.100:8089

Expected result: The Unit is registered in AosCloud and appears in your unit list.

Create and provision a development VM Unit

To create a VM Unit, download images and run the unit-new command. This will create 2 VMs: one main node and all secondary node by default. Connects them with the NAT network and register them in AosCloud. Download the AosCore disk image with the download command.

Run command to create Unit

Windows

~/.aos/venv/Scripts/python -m aos_prov unit-new --name [NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov unit-new --name [NAME]

tip

By default the Unit will be created with 2 nodes(main and secondary). You can change the number of nodes with the --nodes option.
aos_prov unit-new --name [NAME] --nodes 3 will create a Unit with main and 2 secondary nodes.
aos_prov unit-new --name [NAME] --nodes 1 will create a Unit with only main node.

Add nodes to the existing VM Unit

To add a node to an existing VM Unit, use the unit-node-add command.

The command creates a new secondary VM node, connects it to the existing VM Unit network, and optionally starts it. Run the command:

Windows

~/.aos/venv/Scripts/python -m aos_prov unit-node-add -N [NAME] --disk ~/.aos/downloads/aos-vm-secondary-genericx86-64.vmdk

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov unit-node-add -N [NAME] --disk ~/.aos/downloads/aos-vm-secondary-genericx86-64.vmdk

Where:

• [NAME] is the name of the existing VM Unit.
• --disk is the path to the AosCore secondary node disk image.

Example:

~/.aos/venv/bin/python3 -m aos_prov unit-node-add -N aos-dev-unit --disk ~/.aos/downloads/aos-vm-secondary-genericx86-64.vmdk

Expected result: A new secondary node is added to the VM Unit and appears in VirtualBox as part of the Unit.

Remove nodes from a VM Unit

To remove a node from an existing VM Unit, use the unit-node-remove command.

Only secondary nodes can be removed. The main node cannot be removed from a VM Unit.

Before removing a node, make sure that:

• The VM Unit exists.
• The node name is known.
• The node name starts with secondary, for example secondary-1.

Run the command:

Windows

~/.aos/venv/Scripts/python -m aos_prov unit-node-remove -N [NAME] --node [NODE_NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov unit-node-remove -N [NAME] --node [NODE_NAME]

Where:

• [NAME] is the name of the existing VM Unit.
• [NODE_NAME] is the name of the secondary node to remove.

Example:

~/.aos/venv/bin/python3 -m aos_prov unit-node-remove -N aos-dev-unit --node secondary-1

Expected result: The selected secondary node is removed from the VM Unit.

Manage VMs Unit

Use aos-prov commands vm-new, vm-start, vm-remove when you need to create, start, or delete a local VirtualBox VM Unit without provisioning it in AosCloud. These commands are useful for preparing a VM Unit manually or testing the Unit locally before running provisioning.

Create a Unit VMs group

To create a local Unit , use the vm-new command.

The command creates a VirtualBox VM group with one main node and one or more secondary nodes. By default, it creates 2 nodes: one main node and one secondary node.

Run the command:

Windows

~/.aos/venv/Scripts/python -m aos_prov vm-new -N [NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov vm-new -N [NAME]

Where:

• [NAME] is the name of the VM group Unit.

Example:

~/.aos/venv/bin/python3 -m aos_prov vm-new -N aos-dev-unit

To create a VM group with a custom number of nodes, use the --nodes option:

~/.aos/venv/bin/python3 -m aos_prov vm-new -N aos-dev-unit --nodes 3

This creates one main node and two secondary nodes.

If the disk image is stored outside the default download directory, specify it with the -D option:

~/.aos/venv/bin/python3 -m aos_prov vm-new -N aos-dev-unit -D /path/to/aos-vm-main-genericx86-64.vmdk

Expected result: A new VirtualBox VM group is created with the specified name.

Delete Unit VMs group

To delete a local Unit VM group, use the vm-remove command.

The command removes the VirtualBox VM group created by aos-prov. It is important to delete with this command because it also removes network interfaces.

warning

This operation deletes the local VM group. Make sure you no longer need the VM files before running the command.

Run the command:

Windows

~/.aos/venv/Scripts/python -m aos_prov vm-remove -N [NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov vm-remove -N [NAME]

Where:

• [NAME] is the name of the VM group Unit to delete.

Example:

~/.aos/venv/bin/python3 -m aos_prov vm-remove -N aos-dev-unit

Expected result: The selected VirtualBox VM group is removed.

Start Unit VMs group

To start an existing local Unit VM group, use the vm-start command.

Run the command:

Windows

~/.aos/venv/Scripts/python -m aos_prov vm-start -N [NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov vm-start -N [NAME]

Where:

• [NAME] is the name of the VM group Unit to start.

Example:

~/.aos/venv/bin/python3 -m aos_prov vm-start -N aos-dev-unit

To start the VM group without opening VirtualBox windows, add the -H option:

~/.aos/venv/bin/python3 -m aos_prov vm-start -N aos-dev-unit -H

Expected result: All nodes in the VM group are started.

Commands reference

sub-command, option	description
-V, --version	Shows installed version.
-h, --help	Shows general help or help for a selected command.
provision	Provisions a Unit.
vm-new	Creates a new VMs group Unit.
vm-remove	Removes the VMs group Unit.
vm-start	Starts the VMs group Unit.
unit-new	Creates and provisions a new VMs group Unit.
unit-node-add	Adds dynamical node to the already presented VMs group Unit.
unit-node-remove	Removes dynamical node from the already presented VMs group Unit. Only "secondary-N" nodes can be removed.
download	Downloads image.
check-version	Checks current version and latest available version.

-V, --version

Shows installed version.

Windows

~/.aos/venv/Scripts/python -m aos_prov -V

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov -V

-h, --help

Shows general help or help for a selected command.

Windows

~/.aos/venv/Scripts/python -m aos_prov -h

~/.aos/venv/Scripts/python -m aos_prov provision -h

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov -h

~/.aos/venv/bin/python3 -m aos_prov provision -h

provision

Provision a Unit.

provision [-h] [-u UNIT] [-p PKCS] [--register-port REGISTER_PORT] [-w N] [--nodes NODES] [--skip-check-version] [--retry-count RETRY_COUNT] [--retry-delay RETRY_DELAY] [--check-software]

Options	Required	Description	Default
-u, --unit		Unit address in format IP_ADDRESS or IP_ADDRESS:PORT (e.g., "localhost:8089")
-p, --pkcs12		Path to user certificate in pkcs12 format	~/.aos/security/aos-user-oem.p12
--register-port		Cloud port	10000
-w, --wait-unit		Wait for unit to respond for the first time in seconds	0
--nodes		Count of nodes for the VMs group Unit	2
--retry-count		Number of retries for Cloud operations	5
--retry-delay		Delay between retries in seconds	5.0
--check-software		Checking for current software version support	False
--skip-check-version		Skip checking for newest version of the package

Windows

~/.aos/venv/Scripts/python -m aos_prov provision

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov provision

vm-new

Create a new VMs group Unit.

vm-new [-h] -N NAME [-D DISK] [--nodes NODES] [--skip-check-version]

Options	Required	Description	Default
-N, --name	+	Name of the VMs group Unit
-D, --disk		Full path to the AosCore-powered disk
--nodes		Count of nodes for the VMs group Unit	2
--skip-check-version		Skip checking for newest version of the package

Windows

~/.aos/venv/Scripts/python -m aos_prov vm-new -N [NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov vm-new -N [NAME]

vm-remove

Remove the VMs group Unit.

vm-remove [-h] -N NAME [--skip-check-version]

Options	Required	Description	Default
-N, --name	+	Name of the VMs group Unit
--skip-check-version		Skip checking for newest version of the package

Windows

~/.aos/venv/Scripts/python -m aos_prov vm-remove -N [NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov vm-remove -N [NAME]

vm-start

Start the VMs group Unit.

vm-start [-h] -N NAME [-H] [--skip-check-version]

Options	Required	Description	Default
-N, --name	+	Name of the VMs group Unit
-H, --headless		Start the VMs group Unit in headless mode
--skip-check-version		Skip checking for newest version of the package

Windows

~/.aos/venv/Scripts/python -m aos_prov vm-start -N [NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov vm-start -N [NAME]

unit-new

Create and provision a new VMs group Unit.

unit-new [-h] -N NAME [--disk DISK] [--nodes NODES] [-H] [-w N] [-p PKCS] [--skip-check-version] [--retry-count RETRY_COUNT] [--retry-delay RETRY_DELAY] [--check-software]

Options	Required	Description	Default
-N, --name	+	Name of the VMs group Unit
--disk		Full path to the AosCore-powered disk
--nodes		Count of nodes for the Unit	2
-H, --headless		Start created VMs group Unit in headless mode
-w, --wait-unit		Wait for the Unit to respond in seconds	300
-p, --pkcs12		Path to user certificate in pkcs12 format	~/.aos/security/aos-user-oem.p12
--retry-count		Number of retries for Cloud operations	5
--retry-delay		Delay between retries in seconds	5.0
--check-software		Checking for current software version support	False
--skip-check-version		Skip checking for newest version of the package

Windows

~/.aos/venv/Scripts/python -m aos_prov unit-new -N [NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov unit-new -N [NAME]

unit-node-add

Add dynamical node to the already presented VMs group Unit.

unit-node-add [-h] -N NAME --disk DISK [-S [START]] [-H] [--skip-check-version]

Options	Required	Description	Default
-N, --name	+	Name of the VMs group Unit
--disk	+	Full path to the AosCore-powered dynamical disk
-S, --start		Start Node of the VMs group Unit	True
-H, --headless		Start Node of the VMs group Unit in headless mode
--skip-check-version		Skip checking for newest version of the package

Windows

~/.aos/venv/Scripts/python -m aos_prov unit-node-add -N [NAME] --disk [DISK_PATH]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov unit-node-add -N [NAME] --disk [DISK_PATH]

unit-node-remove

Remove dynamical node from the already presented VMs group Unit. Only "secondary-N" nodes can be removed.

unit-node-remove [-h] -N NAME --node NODE [-r [REBOOT]] [--skip-check-version]

Options	Required	Description	Default
-N, --name	+	Name of the VMs group Unit
--node	+	Node of the VMs group Unit (starts with "secondary")
-r, --reboot		Reboot all nodes into VM Group	True
--skip-check-version		Skip checking for newest version of the package

Windows

~/.aos/venv/Scripts/python -m aos_prov unit-node-remove -N [NAME] --node [NODE_NAME]

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov unit-node-remove -N [NAME] --node [NODE_NAME]

download

Download image.

download [-h] [-a DOWNLOAD_ADDRESS] [-f] [--skip-check-version]

Options	Required	Description	Default
-a, --address		Address to download image
-f, --force		Force overwrite existing file
--skip-check-version		Skip checking for newest version of the package

Windows

~/.aos/venv/Scripts/python -m aos_prov download

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov download

check-version

Check current version and latest available version.

check-version [-h]

Windows

~/.aos/venv/Scripts/python -m aos_prov check-version

macOS/Linux

~/.aos/venv/bin/python3 -m aos_prov check-version