In-Place Software Release Updates on Deployed VMs
To support life cycle management of the Apstra VM, we provide a set of utilities designed to
simplify and streamline the process. Use os‑ wrappers to run these utilities
on a read‑only system.
Wrappers
The wrappers follow the original tools’ behavior. For example, to change your own password you don’t need sudo, and the wrapper behaves the same way. Wrappers don’t escalate privileges—if the original command requires root, the wrapper does too. You can use wrappers to keep local user management on a read‑only system.
Here's a list of wrappers that allow the utilities to function correctly in a read-only environment:
| Original utility | Wrapper |
| /usr/bin/passwd | /usr/bin/os-passwd |
| /usr/bin/adduser | /usr/bin/os-adduser |
| /usr/bin/change | /usr/bin/os-change |
| /usr/bin/chgpasswd | /usr/bin/os-chgpasswd |
| /usr/bin/chpasswd | /usr/bin/os-chpasswd |
| /usr/bin/gpasswd | /usr/bin/os-gpasswd |
| /usr/bin/groupadd | /usr/bin/os-groupadd |
| /usr/bin/groupdel | /usr/bin/os-groupdel |
| /usr/bin/groupmems | /usr/bin/os-groupmems |
| /usr/bin/groupmod | /usr/bin/os-groupmod |
| /usr/bin/grpck | /usr/bin/os-grpck |
| /usr/bin/grpconv | /usr/bin/os-grpconv |
| /usr/bin/grpunconv | /usr/bin/os-grpunconv |
| /usr/bin/newgrp | /usr/bin/os-newgrp |
| /usr/bin/newusers | /usr/bin/os-newusers |
| /usr/bin/prober | /usr/bin/os-prober |
| /usr/bin/pwck | /usr/bin/os-pwck |
| /usr/bin/pwconv | /usr/bin/os-pwconv |
| /usr/bin/pwunconv | /usr/bin/os-pwunconv |
| /usr/bin/update-ca-certificates | /usr/bin/os-update-ca-certificates |
| /usr/bin/useradd | /usr/bin/os-useradd |
| /usr/bin/userdel | /usr/bin/os-userdel |
| /usr/bin/usermod | /usr/bin/os-usermod |
| /usr/bin/vigr | /usr/bin/os-vigr |
| /usr/bin/vipw | /usr/bin/os-vipw |
Utilities
Use the corresponding os‑ wrapper for each utility:
os-edit
If you need to edit a configuration file on a read-only (RO) file system and can’t use other methods, use the os-edit utility. The utility starts the editor set in the EDITOR environment variable; if EDITOR isn’t set, it falls back to vim.
The utility tracks the files you modify and records them in
/etc/changed_files. The os-update utility uses this list of files in
/etc/changed_files to collect the modified files and create a tarball.
os-update
os-update is the primary tool for managing update files. Use it to
display update details, apply an update, optionally switch the boot partition, and reboot
the system.
Here’s a quick walkthrough. Suppose you have an update file named
aos.up. First, inspect the file.
admin@aos-server:~$ os-update show aos.up Update file version: 1 Update ID: f84592b7eb8071ab64ca785150e026f6b78fe550 Image root.img.zstd: sha256 checksum = 6d153c8e49695df6d6b1780075be9ec7dc818477cf8853e543fe56871d865131 Image docker.img.zstd: sha256 checksum = 59e0803c2c479f47b4c82f751f0de37d9a46340af25442f67426c317ed384fdc Metadata: api_version = 6.1.0 Metadata: branch = master Metadata: build_id = AOS_latest_OB.7366 Metadata: commit = 49d4d4d1615cf185ec26ce6b94d331993fa43ffc Metadata: created_at = 2025-11-19T01:27:21+00:00 Metadata: version = 99.0.0-7366
The output shows the update file version, a unique update ID, and associated metadata.
You can also validate integrity. ZIP archives include built‑in integrity checks (such as CRC64), but you might also need to validate additional aspects—for example, compliance with a specific JSON schema.
Use this command:
admin@aos-server:~$ sudo os-update validate aos.up Update ID is fine Metadata is fine Image root.img.zstd is valid Image docker.img.zstd is valid Update file is fine
Before you upgrade, review the options:
admin@aos-server:~$ os-update apply -h
usage: os-update apply [-h] [-s] [-n UPGRADE_SUBNET] [--upgrade-port-80 UPGRADE_PORT_80]
[--upgrade-port-443 UPGRADE_PORT_443] [--nameserver NAMESERVER]
[--auto-approve-device-config-changes] [--switch-boot-partition {y,n}] [--reboot {y,n}]
[--skip-resource-validation] [--skip-connectivity-validation] [--dry-run-precondition]
file
Apply update.
positional arguments:
file Path to the update file
options:
-h, --help show this help message and exit
-s, --skip-validation
Skip update validation (default: False)
-n UPGRADE_SUBNET, --upgrade-subnet UPGRADE_SUBNET
Subnet for upgrade interfaces. (default: 10.254.254.0/24)
--upgrade-port-80 UPGRADE_PORT_80
Host port that will be used for network namespace port 80 (default: 8080)
--upgrade-port-443 UPGRADE_PORT_443
Host port that will be used for network namespace port 443 (default: 8443)
--nameserver NAMESERVER
Nameserver that will be used within upgrade environment (default: 192.168.76.3)
--auto-approve-device-config-changes
Skip interactive upgrade summary confirmation. (default: False)
--switch-boot-partition {y,n}
Switch boot partition after successful update (y/n), ask user if not specified (default:
None)
--reboot {y,n} Reboot after successful update (y/n), ask user if not specified (default: None)
--skip-resource-validation
Skip validating that AOS has required memory and disk usages (default: False)
--skip-connectivity-validation
Skip validating that system-agent and cluster-nodes has required credentials, connectivity
and privileges (default: False)
--dry-run-precondition
Execute only precondition checks and skip upgrade (default: False)We’ll cover most options later. For now, remember that:
-
You can skip the
os-update validatestep. -
You can skip the reboot after the update (so you can reboot into the new partition when it’s convenient).
-
You can skip switching the boot partition (which also skips the reboot).
-
Advanced options let you set ports, subnets, and DNS settings.
All options are optional. If you run os-update apply without options, it
will:
-
Validate the update file.
-
Unpack images into the secondary partition set.
-
Move important changes from one partition to another.
-
Switch the boot partition.
-
Reboot the system.
Let’s see how to perform an upgrade. Then review the options:
admin@aos-server:~$ sudo os-update apply aos.up [sudo] password for admin: Update ID is fine Metadata is fine Image root.img.zstd is valid Image docker.img.zstd is valid Update file is fine Start to rollout upgrade images. During this step all signals are muted Write root.img.zstd to /dev/vda6 Write docker.img.zstd to /dev/vda7 Partition /dev/vda6 has been updated Partition /dev/vda7 has been updated Partitions are rolled out. FIPS status is retained New upgrade partition has retained current runtime settings This upgrade does not require data translation. client_loop: send disconnect: Broken pipe
The last line is from SSH and indicates that the connection was dropped because of the reboot. You can skip the reboot after the update (so you can reboot into the new partition when it’s convenient).
os-lv-extend
os-lv-extend is a wrapper that simplifies common LVM operations—most
notably partition extension. It’s similar to its counterpart in the previous layout,
aos_extend_disk.
For example, let’s say you want to extend the log partition.
admin@aos-server:~$ sudo os-lv-extend list /dev/vdb /dev/vdc
/dev/vdb and /dev/vdc are eligible for LVM
extension.
The utility can distribute space across multiple logical volumes. If you aren’t satisfied with the default allocation, customize it by adjusting these weights.
admin@aos-server:~$ cat weights /dev/mapper/user-var+log=1 /dev/mapper/user-var+lib+aos+db=0 /dev/mapper/user-user=0 /dev/mapper/user-var=0
There are four logical volumes. I’ve set the weights of all volumes to zero except for the logs, which means all available space will be allocated to logs.
Now run the utility:
admin@aos-server:~$ sudo os-lv-extend extend -w weights /dev/vdb Disk to be used: /dev/vdb Logical volumes will be extended as follows: ---------------------------------------- /dev/mapper/user-var+log by 40956 MiB ---------------------------------------- Proceed with changes? (y/n) y All done.
For /dev/vdc, distribute space as follows: sysdb gets 3
shares; log and user get two shares each;
var gets one share, userget two shares each;
var gets one share:
admin@aos-server:~$ cat weights /dev/mapper/user-var+log=2 /dev/mapper/user-var+lib+aos+db=3 /dev/mapper/user-user=2 /dev/mapper/user-var=1
Run the utility:
admin@aos-server:~$ sudo os-lv-extend extend -w weights /dev/vdc Disk to be used: /dev/vdc Logical volumes will be extended as follows: ---------------------------------------- /dev/mapper/user-user by 10236 MiB /dev/mapper/user-var by 5116 MiB /dev/mapper/user-var+lib+aos+db by 15356 MiB /dev/mapper/user-var+log by 10236 MiB ---------------------------------------- Proceed with changes? (y/n) y All done.
If the proposed changes don’t look right, don’t confirm.
This utility is designed for this use case. It doesn’t support shrinking volumes, creating new logical volumes, or similar operations.
For those tasks, use the standard LVM tool set.