Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/stage'
Browse files Browse the repository at this point in the history
  • Loading branch information
Cumulus Docs Auto Merge committed Jan 9, 2025
2 parents 7539fd5 + aea1fab commit cfaeb16
Show file tree
Hide file tree
Showing 6 changed files with 104 additions and 93 deletions.
9 changes: 3 additions & 6 deletions content/cumulus-linux-511/Installation-Management/Upgrading-Cumulus-Linux.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -237,14 +237,12 @@ tmpfs 7.7G 0 7.7G 0% /sys/fs/cgroup
tmpfs 7.7G 16K 7.7G 1% /tmp
overlay 28G 7.9G 18G 31%
```
<!--
#### Upgrade from Cumulus Linux 5.9 to Cumulus Linux 5.10
To upgrade to Cumulus Linux 5.10.1 from Cumulus Linux 5.9.2, you must install the Cumulus Linux 5.10.1 image. You *cannot* upgrade packages with package upgrade.
#### Upgrade from Cumulus Linux 5.9
If you are running Cumulus Linux 5.9.x (the current extended-support release), the default switch configuration allows you to upgrade to the latest Cumulus 5.9.x release only.
If you are running Cumulus Linux 5.9 (the current extended-support release), the default switch configuration allows you to upgrade to the latest Cumulus 5.9 maintenance release only.
To upgrade from Cumulus Linux 5.9.0 or 5.9.1 to Cumulus Linux 5.10.1, perform the following procedure before you start the package upgrade:
To upgrade from Cumulus Linux 5.9 to the latest Cumulus Linux 5 release, perform the following procedure before you start the package upgrade:
1. Edit the `/etc/apt/sources.list` file to include the following lines at the top of the file.
Expand All @@ -260,7 +258,6 @@ To upgrade from Cumulus Linux 5.9.0 or 5.9.1 to Cumulus Linux 5.10.1, perform th
deb https://apt.cumulusnetworks.com/repo CumulusLinux-5.9-latest cumulus upstream netq
deb-src https://apt.cumulusnetworks.com/repo CumulusLinux-5.9-latest cumulus upstream netq
```
-->
#### Upgrade the Switch
Expand Down
57 changes: 31 additions & 26 deletions content/cumulus-linux-512/Installation-Management/Adding-and-Updating-Packages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -160,14 +160,14 @@ In some cases, installing a new package also upgrades additional existing packag

## Configure Additional Repositories

As shipped, Cumulus Linux searches the Cumulus Linux repository for available packages. You can add additional repositories to search by adding them to the list of sources that Cumulus Linux consults.
As shipped, Cumulus Linux searches the Cumulus Linux repository for available packages. You can configure additional repositories to search by adding them to the list of sources that Cumulus Linux consults.

{{%notice note%}}
- NVIDIA adds features or makes bug fixes to certain packages; do not replace these packages with versions from other repositories.
- NVIDIA does not test and Cumulus Linux Technical Support does not support packages that are not part of the Cumulus Linux repository.
{{%/notice%}}

To add an additional repository:
To configure an additional repository:
- Provide the repository location, distribution, and pool.
- Either set the repository to trusted or provide the secure key.
- Enable repository source to add source files from the repository (optional).
Expand All @@ -176,7 +176,7 @@ To add an additional repository:
{{< tabs "TabID176 ">}}
{{< tab "NVUE Commands ">}}

The following example adds the repository located at `http://test.myrepo.com` with distribution `mydist` and pool `mypool`, enables source files from the repository, and sets the repository to trusted. The example also sets the VRF to `default`.
The following example configures the repository located at `http://test.myrepo.com` with distribution `mydist` and pool `mypool`, enables source files from the repository, and sets the repository to trusted. The example also sets the VRF to `default`.

```
cumulus@switch:~$ nv set system packages use-vrf default
Expand All @@ -185,7 +185,7 @@ cumulus@switch:~$ nv set system packages repository http://test.myrepo.com sourc
cumulus@switch:~$ nv set system packages repository http://test.myrepo.com insecure enabled
```

The following example adds the repository located at `http://test.myrepo.com` with distribution `mydist` and pool `mypool`, enables source files from the repository, and provides the secure key `thekey.asc`.
The following example configures the repository located at `http://test.myrepo.com` with distribution `mydist` and pool `mypool`, enables source files from the repository, and provides the secure key `thekey.asc`.

```
cumulus@switch:~$ nv set system packages repository http://test.myrepo.com distribution mydist pool mypool
Expand All @@ -196,15 +196,15 @@ cumulus@switch:~$ nv set system packages repository http://test.myrepo.com key t
{{< /tab >}}
{{< tab "Linux Command ">}}

Edit the `/etc/apt/sources.list` file and add the repository.
Edit the `/etc/apt/sources.list` file to configure the repository.

The following example adds the repository located at `http://test.myrepo.com` with distribution `mydist` and pool `mypool`, enables source files from the repository, and sets the repository to trusted. The example also sets the VRF to `default`.
The following example configures the repository located at `http://test.myrepo.com` with distribution `mydist` and pool `mypool`, enables source files from the repository, and sets the repository to trusted. The example also sets the VRF to `default`.

```
debdeb-src http://test.myrepo.com mydist mypool
```

The following example adds the repository located at `http://test.myrepo.com` with distribution `mydist` and pool `mypool`, enables source files from the repository, and provides the secure key `thekey.asc`.
The following example configures the repository located at `http://test.myrepo.com` with distribution `mydist` and pool `mypool`, enables source files from the repository, and provides the secure key `thekey.asc`.

```
deb-src [signed-by=/etc/apt/keyrings/thekey.asc] http://test.myrepo.com mydist mypool
Expand All @@ -216,13 +216,14 @@ deb-src [signed-by=/etc/apt/keyrings/thekey.asc] http://test.myrepo.com mydist m
### Manage Repository Keys

Cumulus Linux provides commands to:
- Fetch a repository key from a remote location and save it on the switch.
- Fetch a repository key and save it on the switch.
- Delete a repository key.

{{< tabs "TabID218 ">}}
{{< tab "NVUE Commands ">}}

To fetch a repository key from a remote location, run the `nv action fetch system packages key <key>` command. By default, Cumulus Linux saves the key in the directory based on the scope value you provide; `global` or `repository`. The default scope is `global`, where the key is saved in the `/etc/apt/trusted.gpg.d` directory. If you set the scope to `repository`, the key is saved in the `/etc/apt/keyrings` directory.
- To fetch and save a key globally, run the `nv action fetch system packages key <key>` command. Cumulus Linux fetches the key and saves it globally in the `/etc/apt/trusted.gpg.d/` directory. This is the default setting.
- To fetch and save a key for a specific repository, run the `nv action fetch system packages key <key> scope repository` command. Cumulus Linux fetches the key and saves it in the `/etc/apt/keyrings/` directory.

The following example fetches the repository key `http://deb.opera.com/archive.key` and saves it in the `/etc/apt/trusted.gpg.d` directory:

Expand All @@ -249,27 +250,27 @@ To fetch and save a repository key globally:
- If the key already exists on the filesystem, copy it to the `/etc/apt/trusted.gpg.d/` directory.
- If the key is at a remote URL, fetch it with `wget` or another utility, then copy it to the `/etc/apt/trusted.gpg.d/` directory.

The following example fetches the key `http://deb.opera.com/archive.key` from the remote URL and saves it in the `/etc/apt/trusted.gpg.d/` directory:
The following example fetches the key `http://your-url.com/name.key` from the remote URL and copies it to the `/etc/apt/trusted.gpg.d/` directory:

```
cumulus@switch:~$ wget -qO - http://deb.opera.com/archive.key
cumulus@switch:~$ sudo apt-key add /etc/apt/trusted.gpg.d/archive.key
cumulus@switch:~$ wget -qO - http://your-url.com/name.key
cumulus@switch:~$ sudo cp name.key /etc/apt/trusted.gpg.d
```

To fetch and save a key for a specific repository:
- If your key already exists on the filesystem, copy it to the `/etc/apt/keyrings/` directory.
- If the key is at a remote URL, fetch it with `wget` or another utility, then copy it to the `/etc/apt/keyrings/` directory.

The following example copies the key `archive.key` for the repository `deb.opera.com` to the `/etc/apt/keyrings/` directory.
The following example copies the key `name.key` located on the filesystem to the `/etc/apt/keyrings/` directory.

```
cumulus@switch:~$ sudo apt-key add /etc/apt/keyrings/archive.key
cumulus@switch:~$ sudo cp name.key /etc/apt/keyrings/
```

To delete a key, remove the key from the `/etc/apt/keyrings` or `/etc/apt/trusted.gpg.d` directory.

```
cumulus@switch:~$ sudo rm /etc/apt/keyrings/archive.key
cumulus@switch:~$ sudo rm /etc/apt/keyrings/name.key
```

{{< /tab >}}
Expand All @@ -280,19 +281,27 @@ cumulus@switch:~$ sudo rm /etc/apt/keyrings/archive.key
To show the list of repositories and their details:

```
cumulus@switch:~$ nv show system packages repository https://apps3.cumulusnetworks.com/repos/deb/
operational applied
-------------- ----------------------- -------
insecure enabled enabled
source enabled enabled
[distribution] CumulusLinux-d12 CumulusLinux-d12
[distribution] CumulusLinux-d12-latest CumulusLinux-d12-latest
cumulus@switch:~$ nv show system packages repository
Repository Insecure Source Distribution Pool
-------------------------------------------- -------- ------- ----------------------- -----------
https://apps3.cumulusnetworks.com/repos/deb/ enabled enabled CumulusLinux-d12 netq-latest
CumulusLinux-d12-latest netq
upstream
https://apt.cumulusnetworks.com/repo CumulusLinux-d12-latest cumulus
netq
upstream
```

To show the details for a specific repository:

```
cumulus@switch:~$ nv show system packages repository https://apt.cumulusnetworks.com/repo
operational applied
-------------- ----------------------- -------
insecure enabled enabled
source enabled enabled
[distribution] CumulusLinux-d12 CumulusLinux-d12
[distribution] CumulusLinux-d12-latest CumulusLinux-d12-latest
```

To show the list of distributions for a repository:
Expand Down Expand Up @@ -377,13 +386,9 @@ To show the list of keys:
cumulus@switch:~$ nv show system packages keys
Key ID Path Scope
---------------------------------------------- --------------------------------------------------------------------- ------
debian-archive-bookworm-automatic.asc /etc/apt/trusted.gpg.d/debian-archive-bookworm-automatic.asc global
debian-archive-bookworm-security-automatic.asc /etc/apt/trusted.gpg.d/debian-archive-bookworm-security-automatic.asc global
debian-archive-bookworm-stable.asc /etc/apt/trusted.gpg.d/debian-archive-bookworm-stable.asc global
sample-test-key.asc /etc/apt/keyrings/sample-test-key.asc repository
```

Expand Down
40 changes: 10 additions & 30 deletions content/cumulus-linux-512/Installation-Management/Upgrading-Cumulus-Linux.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,14 @@ author: NVIDIA
weight: 50
toc: 3
---
{{%notice warning%}}
The default password for the *cumulus* user account is `cumulus`. The first time you log into Cumulus Linux, you **must** change this default password. Be sure to update any automation scripts before you upgrade. You can use ONIE command line options to change the default password automatically during the Cumulus Linux image installation process. Refer to {{<link url="Installing-a-New-Cumulus-Linux-Image-with-ONIE#onie-installation-options" text="ONIE Installation Options">}}.
{{%/notice%}}

You can upgrade Cumulus Linux in one of two ways:
- Install a new Cumulus Linux image with either {{<link url="#install-an-image" text="Optimized image upgrade">}} or <span class="a-tooltip">[ONIE](## "Open Network Install Environment")</span>.
- Upgrade only the changed packages using {{<link url="#package-upgrade" text="package upgrade">}}.

Cumulus Linux provides ISSU to upgrade an active switch with minimal disruption to the network. See {{<link url="In-Service-System-Upgrade-ISSU" text="In-Service-System-Upgrade-ISSU">}}.

{{%notice note%}}
- To upgrade to Cumulus Linux 5.12 from Cumulus Linux 4.x or 3.x, you must install a disk image of the new release. You *cannot* upgrade packages with package upgrade.
- To upgrade to Cumulus Linux 5.12 from Cumulus Linux 4.4 or earlier, you must install a disk image of the new release. You *cannot* upgrade packages with package upgrade.
- Upgrading an MLAG pair requires additional steps. If you are using MLAG to dual connect two Cumulus Linux switches in your environment, follow the steps in [Upgrade Switches in an MLAG Pair](#upgrade-switches-in-an-mlag-pair) below to ensure a smooth upgrade.
{{%/notice%}}

Expand Down Expand Up @@ -277,25 +273,25 @@ To upgrade the switch with ONIE:
Run **package upgrade** if you are upgrading from one Cumulus Linux 5.x release to a later 5.x release, and if you use third-party applications (package upgrade does not replace or remove third-party applications, unlike the Cumulus Linux image install).
*Package upgrade* always updates to the latest available release in the Cumulus Linux repository. For example, if you are currently running Cumulus Linux 5.0.0 and perform a package upgrade, the packages upgrade to the latest releases in the latest 5.x release.
*Package upgrade* always updates to the latest available release in the Cumulus Linux repository. For example, if you are currently running Cumulus Linux 5.0.0 and perform a package upgrade, the packages upgrade to the latest 5.x release.
When you use package upgrade to upgrade the switch, configuration data stays in place during the upgrade. If the new release updates a previously changed configuration file, the upgrade process prompts you to either specify the version you want to use or evaluate the differences.
{{%notice note%}}
- You cannot upgrade the switch to a new release train. For example, you **cannot** upgrade the switch from 4.x to 5.x.
- You cannot upgrade the switch to a new release train. For example, you **cannot** use package upgrade to upgrade the switch from 4.x to 5.x.
- Package upgrade only supports the current version plus two. For example, you can upgrade from Cumulus Linux 5.6 to 5.8 with package upgrade only if you installed the 5.6 binary image.
- The package upgrade command might restart or stop services as part of the upgrade process.
- The package upgrade command might disrupt core services by changing core service dependency packages.
- After you upgrade, account UIDs and GIDs created by packages might be different on different switches, depending on the configuration and package installation history.
- Cumulus Linux does not support the `sudo -E apt-get dist-upgrade` command. Be sure to use `sudo -E apt-get upgrade` when upgrading packages.
- Cumulus Linux does not support the Linux `sudo -E apt-get dist-upgrade` command. Be sure to use `sudo -E apt-get upgrade` when upgrading packages.
- To upgrade from Cumulus Linux 5.11 to Cumulus Linux 5.12, you need 0.8GB of free disk space. Before you upgrade, run the NVUE `nv show system disk usage` command or the Linux `sudo df -h` command to show how much disk space you are currently using on the switch.
{{%/notice%}}
<!--
{{%notice note%}}
If you are running Cumulus Linux 5.9.x (the current extended-support release), the default switch configuration allows you to upgrade to the latest Cumulus 5.9.x release only.
{{%notice info%}}
If you are running Cumulus Linux 5.9 (the current extended-support release), the default switch configuration allows you to upgrade to the latest Cumulus 5.9 maintenance release only.
To upgrade from Cumulus Linux 5.9.x to Cumulus Linux 5.12, perform the following procedure before you start the package upgrade:
To upgrade from Cumulus Linux 5.9 to the latest Cumulus Linux 5 release, perform the following procedure before you start the package upgrade:
1. Edit the `/etc/apt/sources.list` file to include the following lines at the top of the file.
Expand All @@ -313,7 +309,7 @@ To upgrade from Cumulus Linux 5.9.x to Cumulus Linux 5.12, perform the following
```
{{%/notice%}}
-->
To upgrade the switch with package upgrade:
{{< tabs "TabID253 ">}}
Expand Down Expand Up @@ -575,29 +571,13 @@ NVIDIA has not tested running different versions of Cumulus Linux on MLAG peer s
{{< /tab >}}
{{< /tabs >}}
## Roll Back a Cumulus Linux Installation
Even the most well planned and tested upgrades can result in unforeseen problems and sometimes the best solution is to roll back to the previous state. These main strategies require detailed planning and execution:
- Flatten and rebuild. If the OS becomes unusable, you can use orchestration tools to reinstall the previous OS release from scratch and then rebuild the configuration automatically.
- Restore to a previous state using a backup configuration captured before the upgrade.
The method you employ is specific to your deployment strategy. Providing detailed steps for each scenario is outside the scope of this document.
## Third Party Packages
If you install any third party applications on a Cumulus Linux switch, configuration data is typically installed in the `/etc` directory, but it is not guaranteed. It is your responsibility to understand the behavior and configuration file information of any third party packages installed on the switch.
After you upgrade using a full Cumulus Linux image install, you need to reinstall any third party packages or any Cumulus Linux add-on packages.
After you upgrade using a full Cumulus Linux image install, you need to reinstall any third party packages.
## Considerations
- The `/etc/os-release` and `/etc/lsb-release` files update to the currently installed Cumulus Linux release when you upgrade the switch using either *package upgrade* or *Cumulus Linux image install*. For example, if you perform a package upgrade and the latest Cumulus Linux release on the repository is 5.9.1, these two files display the release as 5.9.1 after the upgrade.
- The `/etc/image-release` file updates **only** when you run a Cumulus Linux image install. Therefore, if you run a Cumulus Linux image install of Cumulus Linux 5.9.0, followed by a package upgrade to 5.9.1, the `/etc/image-release` file continues to display Cumulus Linux 5.9.0, which is the originally installed base image.
## Related Information
- {{<exlink url="https://www.nvidia.com/en-us/networking/network-automation/" text="Automation Solutions">}}
- {{<exlink url="http://opencomputeproject.github.io/onie/design-spec/" text="ONIE Design Specification">}}
- {{<link title="Multi-Chassis Link Aggregation - MLAG">}}
- {{<link title="Zero Touch Provisioning - ZTP">}}
Loading

0 comments on commit cfaeb16

Please sign in to comment.