Upgrading VyOS

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 or apt dist-upgrade; otherwise, you will break your VyOS instance.

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.

  1. Copy the .iso file to the USB flash drive
  2. Then plug the flash drive to an open USB port on the VyOS bare metal
  3. Login to VyOS
  4. Create a directory “usb” in /var/tmp
  5. Locate the USB drive
  6. Mount the USB drive to /var/tmp/usb
  7. Compare the checksum of the mounted .iso to the original copy (optional, but recommended)
  8. Upgrade the system
  9. 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!

Leave a Comment

Your email address will not be published. Required fields are marked *

× 5 = 15

WordPress Appliance - Powered by TurnKey Linux