I just want to say this and this is also has mentioned in the VyOS wiki that despite VyOS is based off Debian Linux, do not use apt upgrade apt dist-upgrade
There are several ways of upgrading the system. The first one is to use the direct link to the .iso file and the other two are offline where you would have to download the .iso file then upload it to the VyOS instance – bare metal or VM.
Using the online option: There are two main versions you can get the link either from LTS release and the other is from the rolling release. All you need is grab the direct iso link and as long as the “local” or the system itself has access to the Internet then you are good to go.
The offline options are:
- Uploading the .iso to the system
- Using a USB thumb drive
- Upgrading using SCP, FTP, SFTP, etc
Release models
Before we get started, there are several release models you may see. These are the models that are available LTS release, EPA release, and rolling releases. I guess if we count the building the iso from source, then that is another one. The LTS (long term support) is exactly what the name is. VyOS will maintain the LTS for at least two years. This would include security patches, bug fixes, etc.
The EPA (early production access) is the release model that are considered stable but have not received the LTS tag yet. The LTS and EPA are only available to subscribers and contributors.
The rolling release is a nightly build and these releases get the latest and greatest VyOS features.
The last one is to build from source. VyOS folks are kind enough to let the community get the LTS or EPA version by building the iso from the source. There are plenty of guides around if you are looking for some “How to”.
Upgrade the system
Upgrade via direct link
My VyOS current version is 1.2.1 LTS and it is installed on a bare-metal Supermicro MBD-A1SRi-2758F-O. I will start with the direct link upgrade. Login to VyOS via SSH the use the following command:
# Verify the current version
show version
# Upgrade the system
add system image {http-lts-link-from-vyos}.iso
# Once the upgrade has completed, reboot the system for the upgrade to take effect
reboot
# Once it booted up, check the version again to verify that system upgrade worked
show version
This is the output once the upgrade command has been executed.
Trying to fetch ISO file from {http-lts-link-from-vyos}.iso
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 183 100 183 0 0 2039 0 --:--:-- --:--:-- --:--:-- 2056
100 385M 100 385M 0 0 37.5M 0 0:00:10 0:00:10 --:--:-- 43.8M
ISO download succeeded.
Checking for digital signature file...
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 183 100 183 0 0 5213 0 --:--:-- --:--:-- --:--:-- 5382
100 836 100 836 0 0 1325 0 --:--:-- --:--:-- --:--:-- 1976
Found it. Checking digital signature...
gpg: directory `/root/.gnupg' created
gpg: new configuration file `/root/.gnupg/gpg.conf' created
gpg: WARNING: options in `/root/.gnupg/gpg.conf' are not yet active during this run
gpg: keyring `/root/.gnupg/pubring.gpg' created
gpg: assuming signed data in `/var/tmp/install-image.30658/vyos-1.2.2-amd64.iso'
gpg: Signature made Mon 15 Jul 2019 12:59:48 AM EDT using RSA key ID A0FE6D7E
gpg: /root/.gnupg/trustdb.gpg: trustdb created
gpg: Good signature from "VyOS Maintainers (VyOS Release) <maintainers@vyos.net>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 0694 A923 0F51 39BF 834B A458 FD22 0285 A0FE 6D7E
Digital signature is valid.
Checking MD5 checksums of files on the ISO image...OK.
Done!
What would you like to name this image? [1.2.2]:
OK. This image will be named: 1.2.2
Installing "1.2.2" image.
Copying new release files...
Would you like to save the current configuration
directory and config file? (Yes/No) [Yes]:
Copying current configuration...
Would you like to save the SSH host keys from your
current configuration? (Yes/No) [Yes]:
Copying SSH keys...
Running post-install script...
Setting up grub configuration...
Done.
vyos@fw01:~$
Upload the .iso to the system
Here is an offline upgrade that does not require the system to have Internet access. This will be useful if you are in an environment that doesn’t let the system itself to have Internet access. The offline method assuming that the admin has a copy of the .iso image. In this example, I would upload the .iso from my laptop to the same VyOS system from earlier via SCP. The target directory is /var/tmp/.The current version is 1.2.2 LTS. I am going to upgrade this system to 1.2.3 LTS.
# From the laptop uploading the .iso to VyOS scp Downloads/vyos-1.2.3-amd64.iso vyos@10.0.0.1:/var/tmp/
Once I uploaded the .iso to the VyOS system, I like to check the checksum and compare it with the original copy. Just to make sure that nothing got corrupted.
# On the laptop checking the checksum of the .iso sha256sum Downloads/vyos-1.2.3-amd64.iso c6a72a8d9410dde426d8349c6bddb42dc7312e2e6841cc8787b57e9231a2664d Downloads/vyos-1.2.3-amd64.iso # On the VyOS checking the checksum of the uploaded .iso sudo sha256sum /var/tmp/vyos-1.2.3-amd64.iso c6a72a8d9410dde426d8349c6bddb42dc7312e2e6841cc8787b57e9231a2664d /var/tmp/vyos-1.2.3-amd64.iso # If they matched, then we are good to continue. # Otherwise, upload the .iso again.
# Upgrade the system using the same command + the path to the .iso vyos@fw01:~$ add system image /var/tmp/vyos-1.2.3-amd64.iso Checking MD5 checksums of files on the ISO image...OK. Done! What would you like to name this image? [1.2.3]: OK. This image will be named: 1.2.3 Installing "1.2.3" image. Copying new release files... Would you like to save the current configuration directory and config file? (Yes/No) [Yes]: Copying current configuration... Would you like to save the SSH host keys from your current configuration? (Yes/No) [Yes]: Copying SSH keys... Running post-install script... Setting up grub configuration... Done. vyos@fw01:~$ # Again, reboot the system to load the new version reboot # Once the system is back, verify the version show version
Upgrading from a USB flash drive
There are some instances that we would have to use a USB flash drive to upgrade the system. Probably because transferring the file through the network is not allowed or not available. Whatever the case may be, we have to use a USB flash drive. Our version now is 1.2.3 LTS and we are going to upgrade to 1.2.4 LTS which is at the time of this writing is the latest LTS.
Make sure that the USB flash drive is formatted to FAT32. It is a good thing to keep a flash drive that is formatted to FAT32 since major vendors use the same format. Therefore, having a flash drive that is already on FAT32 is going to be helpful. If you have not done so, check this post to format your USB flash drive.
- Copy the .iso file to the USB flash drive
- Then plug the flash drive to an open USB port on the VyOS bare metal
- Login to VyOS
- Create a directory “usb” in /var/tmp
- Locate the USB drive
- Mount the USB drive to /var/tmp/usb
- Compare the checksum of the mounted .iso to the original copy (optional, but recommended)
- Upgrade the system
- Unmount the USB drive
# Step 4 mkdir /var/tmp/usb # Step 5 # The command "lsblk" and "fdisk -l" can be use to locate the USB drive vyos@fw01:~$ lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT sdb 8:16 1 57.7G 0 disk └─sdb1 8:17 1 57.7G 0 part loop0 7:0 0 347M 1 loop /lib/live/mount/rootfs/1.2.3.squashfs sda 8:0 1 119.2G 0 disk └─sda1 8:1 1 119.2G 0 part /lib/live/mount/persistence vyos@fw01:~$ fdisk -l Disk /dev/sda: 119.2 GiB, 128035676160 bytes, 250069680 sectors Units: sectors of 1 * 512 = 512 bytes Sector size (logical/physical): 512 bytes / 512 bytes I/O size (minimum/optimal): 512 bytes / 512 bytes Disklabel type: dos Disk identifier: 0x29e81ff8 Device Boot Start End Sectors Size Id Type /dev/sda1 * 2048 250068991 250066944 119.2G 83 Linux Disk /dev/loop0: 347 MiB, 363851776 bytes, 710648 sectors Units: sectors of 1 * 512 = 512 bytes Sector size (logical/physical): 512 bytes / 512 bytes I/O size (minimum/optimal): 512 bytes / 512 bytes Disk /dev/sdb: 57.7 GiB, 61958258688 bytes, 121012224 sectors Units: sectors of 1 * 512 = 512 bytes Sector size (logical/physical): 512 bytes / 512 bytes I/O size (minimum/optimal): 512 bytes / 512 bytes Disklabel type: dos Disk identifier: 0x6e460c94 Device Boot Start End Sectors Size Id Type /dev/sdb1 2048 121012223 121010176 57.7G b W95 FAT32 # Step 6 # Mount the USB drive to /var/tmp/usb vyos@fw01:~$ sudo mount /dev/sdb1 /var/tmp/usb vyos@fw01:~$ ls -l /var/tmp/usb/ total 400384 -rwxr-xr-x 1 root root 409993216 Feb 16 16:17 vyos-1.2.4-amd64.iso # now we can access the .iso file # Step 7 (optional) # From the laptop karlo@kalaptop:~$ sha256sum Downloads/vyos-1.2.4-amd64.iso 4f248acc3befe1ea1f3f1bf91f5951656bd6efef4d942b3c9bfc4422061da823 Downloads/vyos-1.2.4-amd64.iso # From the VyOS vyos@fw01:~$ sudo sha256sum /var/tmp/usb/vyos-1.2.4-amd64.iso 4f248acc3befe1ea1f3f1bf91f5951656bd6efef4d942b3c9bfc4422061da823 /var/tmp/usb/vyos-1.2.4-amd64.iso
Once everything is correct, upgrade the system then reboot.
# Step 8 # Upgrade the system vyos@fw01:~$ add system image /var/tmp/usb/vyos-1.2.4-amd64.iso Checking MD5 checksums of files on the ISO image...OK. Done! What would you like to name this image? [1.2.4]: OK. This image will be named: 1.2.4 Installing "1.2.4" image. Copying new release files... Would you like to save the current configuration directory and config file? (Yes/No) [Yes]: Copying current configuration... Would you like to save the SSH host keys from your current configuration? (Yes/No) [Yes]: Copying SSH keys... Running post-install script... Setting up grub configuration... Done. vyos@fw01:~$ # Step 9 # Unmount the USB then unplug it; otherwise, the system might boot from the USB sudo umount /var/tmp/usb # Reboot the system vyos@fw01:~$ reboot # Once back, verify the system version show version
Upgrading via the network
The last method is to upgrade via the network. However, it seems like this is not possible yet according this this enhancement request. We can use the following protocols SFTP, SCP, TFTP and some others as long as the VyOS supports it. I will be using the SCP to upgrade my VyOS 1.2.4 LTS to version 1.2.5 EPA1.
# It seems like this is not possible yet. #add system image scp://root@10.0.7.12:/mnt/user/isos/template/iso/vyos-1.2.5-epa1-amd64.iso # What we can do is the reverse of method 2 earlier. We are going to download the .iso from the local server hosting the .iso scp root@10.0.7.12:/mnt/user/isos/template/iso/vyos-1.2.5-epa1-amd64.iso /var/tmp/ # Then once downloaded, upgrade the system add system image /var/tmp/vyos-1.2.5-epa1-amd64.iso # Output Checking MD5 checksums of files on the ISO image...OK. Done! What would you like to name this image? [1.2.5-epa1]: OK. This image will be named: 1.2.5-epa1 Installing "1.2.5-epa1" image. Copying new release files... Would you like to save the current configuration directory and config file? (Yes/No) [Yes]: Copying current configuration... Would you like to save the SSH host keys from your current configuration? (Yes/No) [Yes]: Copying SSH keys... Running post-install script... Setting up grub configuration... Done. # Once done, reboot the system reboot # Once back, verify the system version show version
I think this post is getting too long now. But you got to ask yourself a question, what would happen if the upgrade fails? What if something broke after the system upgraded? What to do if something breaks after the upgrade?
We will address these in the next post. Cheers!
hi,
i’m on a 1.3.rolling version. i tried to build the lts version from source. when i add the image and boot from the new image, i got a ‘config error’. can this be done or it’s not possible?
thanks.
You should be able to install the LTS. You are probably encountering some config imcompatibility issue between the rolling releases and LTS.
If you can test this in the virtualized environment using the same rolling ISO then install the LTS that you built.
I have not tried to go from 1.3 to LTS since all I needed are all on 1.3.