From 8f7f11de8f073b540a1d40d4157a8d1decca6626 Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 16 Oct 2026 15:38:27 -0400 Subject: [PATCH 1/3] clarifying use of qcow2 --- docs/deploy_vmware_conductor.mdx | 7 ++++++- docs/deploy_vmware_hub_router_overview.mdx | 7 ++++++- docs/install_qcow2_deployment.md | 4 ++++ docs/install_vmware_config.mdx | 12 ++++++++---- docs/intro_installation_image.md | 2 +- 5 files changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/deploy_vmware_conductor.mdx b/docs/deploy_vmware_conductor.mdx index 005766446bd..37ccc7e5c36 100644 --- a/docs/deploy_vmware_conductor.mdx +++ b/docs/deploy_vmware_conductor.mdx @@ -59,7 +59,12 @@ Before beginning, ensure the following are available: - **VMware ESXi 7.0 or later** — administrative access to an ESXi host. - **Juniper software access credentials** — Artifactory username and password for software downloads and token provisioning. -- **SSR 7.1.4-3r2 Universal ISO** — downloaded from [software.128technology.com](https://software.128technology.com/artifactory/list/generic-128t-isos-release-local/) using your Juniper software access credentials. +- **SSR 7.1.4-3r2 Universal ISO** — downloaded from [software.128technology.com](https://software.128technology.com/artifactory/list/generic-128t-isos-release-local/) using your Juniper software access credentials. This guide only provides instructions for deployment using the SSR Universal ISo. + + :::note + It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a QCOW2 file (identified by the `.qcow2` file extension), it must be converted to a `vmdk` before installing. Refer to your VMWare documentation for more information. + ::: + - **Management network** — a VMware portgroup providing internet access for software downloads, with a static IP assignment available for the conductor VM. - **Static IP assignment for the conductor** — the IP address assigned to the conductor must be reachable from each branch router's WAN interface (directly or via routing). This guide uses `192.168.100.10`. diff --git a/docs/deploy_vmware_hub_router_overview.mdx b/docs/deploy_vmware_hub_router_overview.mdx index 7ff17fd4778..6001e8efcf5 100644 --- a/docs/deploy_vmware_hub_router_overview.mdx +++ b/docs/deploy_vmware_hub_router_overview.mdx @@ -47,7 +47,12 @@ Before beginning, ensure the following are available: - **VMware ESXi 7.0 or later** — administrative access to an ESXi host. - **Juniper software access credentials** — Artifactory username and password for software downloads and token provisioning. -- **SSR 7.1.4-3r2 Universal ISO** — downloaded from [software.128technology.com](https://software.128technology.com/artifactory/list/generic-128t-install-images-release-local/) using your Juniper software access credentials. +- **SSR 7.1.4-3r2 Universal ISO** — downloaded from [software.128technology.com](https://software.128technology.com/artifactory/list/generic-128t-isos-release-local/) using your Juniper software access credentials. This guide only provides instructions for deployment using the SSR Universal ISo. + + :::note + It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a QCOW2 file (identified by the `.qcow2` file extension), it must be converted to a `vmdk` before installing. Refer to your VMWare documentation for more information. + ::: + - **Pre-existing conductor** — running SSR 7.1.4-3.r2 at a static IP reachable from the router WAN. This guide uses `192.168.100.10`. - **WAN portgroup** — a VMware portgroup with an ISP Ethernet link that provides DHCP. - **LAN portgroup** — a VMware portgroup connected to your branch LAN switch. diff --git a/docs/install_qcow2_deployment.md b/docs/install_qcow2_deployment.md index 07019117623..0bd2ed3fdfe 100644 --- a/docs/install_qcow2_deployment.md +++ b/docs/install_qcow2_deployment.md @@ -7,6 +7,10 @@ The SSR software can now be downloaded as a qcow2 image. Qcow2 is a storage form For successful SSR qcow2 deployment, a cloud-init (or nocloud) configuration **must** provide persistent network interface bindings on first boot of the VM; otherwise the SSR will not correlate virtual machine NICs to router interfaces, and the NIC assignments may change across VM reboots. Operation of SSR qcow2 without persistent NIC bindings is not supported at this time. +:::note +If you are installing on a VMWare ESXi environment, the QCOW2 file must be converted to a `vmdk`. Refer to your VMWare documentation for more information. +::: + Download the 128T package-based qcow2 image using the link below: https://software.128technology.com/artifactory/list/generic-128t-images-release-local/ diff --git a/docs/install_vmware_config.mdx b/docs/install_vmware_config.mdx index b3bdaac6c32..71840b929e6 100644 --- a/docs/install_vmware_config.mdx +++ b/docs/install_vmware_config.mdx @@ -5,10 +5,14 @@ sidebar_label: Installing in VMWare This guide describes the process for deploying a Session Smart Conductor or a Session Smart Router (SSR) in VMWare ESXi. The process consists of the following steps: -- Download the SSR package-based ISO. Refer to [Downloading ISOs](intro_downloading_iso.md) -- Log into VMware ESXi with Administrative rights -- Create a new Virtual Machine and configure -- Boot Virtual Machine to run the Juniper SSR ISO and install software +- Download the latest SSR ISO. Refer to [Downloading ISOs](intro_downloading_iso.md). +- Log into VMware ESXi with Administrative rights. +- Create a new Virtual Machine and configure. +- Boot Virtual Machine to run the Juniper SSR ISO and install software. + +:::note +It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a QCOW2 file (identified by the `.qcow2` extension), it must be converted to a `vmdk` before installing. Refer to your VMWare documentation for more information. +::: ## VMWare Configuration diff --git a/docs/intro_installation_image.md b/docs/intro_installation_image.md index 81445256819..38dcf3d5d81 100644 --- a/docs/intro_installation_image.md +++ b/docs/intro_installation_image.md @@ -36,7 +36,7 @@ Files available for download are: - `*.iso` - This file is used for installing/staging bare metal platforms. **Use this file to perform an image-based install.** - `*.tar` - This file is used by Mist or the SSR conductor for image-based upgrades, and is accessed directly by the system during the upgrade. User download is not necessary or advised. -- `*.qcow` - This file is used for virtual environments such as KVM or ESXi. **Do not** use this file to perform an image-based install on a Mist-managed device or system. For more information see [Deployment Using QCOW2](install_qcow2_deployment.md). +- `*.qcow2` - This file can be used for virtual environments such as KVM or ESXi, and must be converted to `vmdk` for use on ESXi. **Do not** use this file to perform an image-based install on a Mist-managed device or system. For more information see [Deployment Using QCOW2](install_qcow2_deployment.md). - `*.ztp.raw.gz` - This file is used by manufacturing, and is not applicable for customer use. You will be prompted for your username and token to access the web page listing the software versions. Download is done directly from the page. From 1160d219e8f553c0271962e05c8ff6c7ebc01c3c Mon Sep 17 00:00:00 2001 From: Chris Date: Mon, 19 Oct 2026 11:41:11 -0400 Subject: [PATCH 2/3] Updates per Iain's review --- docs/deploy_vmware_conductor.mdx | 4 +- docs/deploy_vmware_hub_router_overview.mdx | 2 +- docs/install_qcow2_deployment.md | 44 +++++++++++++++------- docs/install_vmware_config.mdx | 2 +- docs/intro_installation_image.md | 5 ++- 5 files changed, 37 insertions(+), 20 deletions(-) diff --git a/docs/deploy_vmware_conductor.mdx b/docs/deploy_vmware_conductor.mdx index 37ccc7e5c36..c5d9f0e0f00 100644 --- a/docs/deploy_vmware_conductor.mdx +++ b/docs/deploy_vmware_conductor.mdx @@ -59,10 +59,10 @@ Before beginning, ensure the following are available: - **VMware ESXi 7.0 or later** — administrative access to an ESXi host. - **Juniper software access credentials** — Artifactory username and password for software downloads and token provisioning. -- **SSR 7.1.4-3r2 Universal ISO** — downloaded from [software.128technology.com](https://software.128technology.com/artifactory/list/generic-128t-isos-release-local/) using your Juniper software access credentials. This guide only provides instructions for deployment using the SSR Universal ISo. +- **SSR 7.1.4-3r2 Image-based ISO** — downloaded from [software.128technology.com](https://software.128technology.com/artifactory/list/generic-128t-isos-release-local/) using your Juniper software access credentials. This guide only provides instructions for deployment using the SSR Image-based ISO. :::note - It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a QCOW2 file (identified by the `.qcow2` file extension), it must be converted to a `vmdk` before installing. Refer to your VMWare documentation for more information. + It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a QCOW2 file (identified by the `.qcow2` file extension), it must be converted to a `vmdk` before installing. Refer to **[Deployment Using QCOW2](install_qcow2_deployment.md)** for more information. ::: - **Management network** — a VMware portgroup providing internet access for software downloads, with a static IP assignment available for the conductor VM. diff --git a/docs/deploy_vmware_hub_router_overview.mdx b/docs/deploy_vmware_hub_router_overview.mdx index 6001e8efcf5..1f6392f763f 100644 --- a/docs/deploy_vmware_hub_router_overview.mdx +++ b/docs/deploy_vmware_hub_router_overview.mdx @@ -50,7 +50,7 @@ Before beginning, ensure the following are available: - **SSR 7.1.4-3r2 Universal ISO** — downloaded from [software.128technology.com](https://software.128technology.com/artifactory/list/generic-128t-isos-release-local/) using your Juniper software access credentials. This guide only provides instructions for deployment using the SSR Universal ISo. :::note - It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a QCOW2 file (identified by the `.qcow2` file extension), it must be converted to a `vmdk` before installing. Refer to your VMWare documentation for more information. + It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a `qcow2` file (identified by the `.qcow2` file extension), it must be converted to a `vmdk` before installing. For more information on installation and conversion, see **[Deployment Using QCOW2](install_qcow2_deployment.md)**. ::: - **Pre-existing conductor** — running SSR 7.1.4-3.r2 at a static IP reachable from the router WAN. This guide uses `192.168.100.10`. diff --git a/docs/install_qcow2_deployment.md b/docs/install_qcow2_deployment.md index 0bd2ed3fdfe..fb544e8ddfd 100644 --- a/docs/install_qcow2_deployment.md +++ b/docs/install_qcow2_deployment.md @@ -3,29 +3,45 @@ title: Deployment Using QCOW2 sidebar_label: Deployment Using QCOW2 --- -The SSR software can now be downloaded as a qcow2 image. Qcow2 is a storage format for virtual disks. The SSR qcow2 is a virtual hard disk image pre-installed with the SSR ISO. It includes cloud-init packages which can be used to automate instance deployment. Cloud-init can be used for Linux network provisioning and for disk volume dynamic expansion on first boot. +The SSR software can now be downloaded as a `qcow2` image. `qcow2` is a storage format for virtual disks. The SSR `qcow2` is a virtual hard disk image pre-installed with the SSR ISO. It includes cloud-init packages which can be used to automate instance deployment. Cloud-init can be used for Linux network provisioning and for disk volume dynamic expansion on first boot. -For successful SSR qcow2 deployment, a cloud-init (or nocloud) configuration **must** provide persistent network interface bindings on first boot of the VM; otherwise the SSR will not correlate virtual machine NICs to router interfaces, and the NIC assignments may change across VM reboots. Operation of SSR qcow2 without persistent NIC bindings is not supported at this time. +For successful SSR `qcow2` deployment, a cloud-init (or nocloud) configuration **must** provide persistent network interface bindings on first boot of the VM; otherwise the SSR will not correlate virtual machine NICs to router interfaces, and the NIC assignments may change across VM reboots. Operation of SSR qcow2 without persistent NIC bindings is not supported at this time. -:::note -If you are installing on a VMWare ESXi environment, the QCOW2 file must be converted to a `vmdk`. Refer to your VMWare documentation for more information. +It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a QCOW2 file (identified by the `.qcow2` file extension), **it must be converted to a `vmdk` before installing**. + +### Converting a `qcow2` Image + +:::important +If you are installing a `qcow2` image on a VMWare ESXi environment, the `qcow2` image must first be converted to a `vmdk`. ::: -Download the 128T package-based qcow2 image using the link below: +1. Download the SSR image-based install `qcow2` using the link below: -https://software.128technology.com/artifactory/list/generic-128t-images-release-local/ + https://software.128technology.com/artifactory/list/generic-128t-install-images-release-local/ -Beginning with version 6.0, an image-based ISO installation process has been implemented. This installation and upgrade process is only available for SSR version 6.0 and higher. Conductors with version 6.3.0 installed are able to manage routers installed with image-based and package-based software versions. For more information, see [Image-Based Installation](intro_installation_image.md). + :::note + Access to the URL above requires authentication. Log in to https://software.128technology.com using the username and token supplied with your SSR license. + ::: -Download the SSR image-based install qcow2 using the link below: +2. Install the qemu tools on a Linux staging host. Qemu is available natively for Linux distributions, and via third parties for other architectures such as [Windows](https://qemu.weilnetz.de/w64/) and [MacOS](https://formulae.brew.sh/formula/qemu). -https://software.128technology.com/artifactory/list/generic-128t-install-images-release-local/ +3. Download the `qcow2` file. -:::note -Access to the URLs above requires authentication. Log in to https://software.128technology.com using the username and token supplied with your SSR license. -::: +4. Use the `qemu-img` example code below to run the conversion on the Linux host: +``` +$ file SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.qcow2 +SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.qcow2: QEMU QCOW2 Image (v3), 10173284352 bytes + +$ qemu-img convert -f qcow2 -O vmdk SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.qcow2 SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.vmdk + +$ file SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.vmdk +SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.vmdk: VMware4 disk image + +$ ls -lh SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.vmdk +-rw-r--r-- 1 user group 6.5G Oct 16 12:36 SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.vmdk +``` -## Using cloud-init to bootstrap SSR connection to Conductor +## Using `cloud-init` to Connect to the Conductor The simplest method for onboarding a new SSR to an existing conductor is to initialize the system as a router node and provide the addresses for any conductor nodes. The manual initialization process can be automated by providing an [initializer preferences](initializer_preferences.md) file. This can be automated through `cloud-init cloud-config` by providing a user-data to a cloud-init capable hypervisor similar to what is shown below. @@ -46,7 +62,7 @@ This causes the device's salt-minion to attempt to connect to the Conductor at I The example above assumes that the system will be able obtain an IP address via DHCP on the first network interface, which provides connectivity to the Conductor. If this is not the case, additional configuration can be provided to cloud-init to assist in provisioning network interfaces. However, these details are beyond the scope of this document. Please consult the official cloud-init documentation and the documentation for your particular hypervisor for further guidance. ::: -## Using NoCloud to provide cloud-init meta-data, user-data, and network-config +## Using NoCloud to Provide Data to `cloud-init` Even when using a hypervisor that does not directly provide a cloud-init metadata service, it is possible to use NoCloud to seed the required data to cloud-init. On first boot, if the cloud-init process finds an attached disk with the volume label `cidata`, it looks on this disk for configuration data that is typically provided by a hypervisor's metadata service. diff --git a/docs/install_vmware_config.mdx b/docs/install_vmware_config.mdx index 71840b929e6..b8ccb44fee6 100644 --- a/docs/install_vmware_config.mdx +++ b/docs/install_vmware_config.mdx @@ -11,7 +11,7 @@ This guide describes the process for deploying a Session Smart Conductor or a Se - Boot Virtual Machine to run the Juniper SSR ISO and install software. :::note -It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a QCOW2 file (identified by the `.qcow2` extension), it must be converted to a `vmdk` before installing. Refer to your VMWare documentation for more information. +It is highly recommended that VMWare installations use an image-based ISO (identified by the SSR prefix on the image file) when performing a new installation. However, if you are installing on a VMWare ESXi environment and choose to use a `qcow2` file (identified by the `.qcow2` extension), it must be converted to a `vmdk` before installing. For more information on installation and conversion, see **[Deployment Using QCOW2](install_qcow2_deployment.md)**. ::: ## VMWare Configuration diff --git a/docs/intro_installation_image.md b/docs/intro_installation_image.md index 38dcf3d5d81..ed2017ee06a 100644 --- a/docs/intro_installation_image.md +++ b/docs/intro_installation_image.md @@ -36,8 +36,9 @@ Files available for download are: - `*.iso` - This file is used for installing/staging bare metal platforms. **Use this file to perform an image-based install.** - `*.tar` - This file is used by Mist or the SSR conductor for image-based upgrades, and is accessed directly by the system during the upgrade. User download is not necessary or advised. -- `*.qcow2` - This file can be used for virtual environments such as KVM or ESXi, and must be converted to `vmdk` for use on ESXi. **Do not** use this file to perform an image-based install on a Mist-managed device or system. For more information see [Deployment Using QCOW2](install_qcow2_deployment.md). -- `*.ztp.raw.gz` - This file is used by manufacturing, and is not applicable for customer use. +- `*.qcow2` - This file can be used for virtual environments such as KVM or ESXi, and must be converted to `vmdk` for use on ESXi. + + **Do not** use this file to perform an image-based install on a Mist-managed device or system. For more information on installation and conversion, see [Deployment Using QCOW2](install_qcow2_deployment.md). You will be prompted for your username and token to access the web page listing the software versions. Download is done directly from the page. From 6b0c92493fa0adc33e4a1f4d064ccc564e110b97 Mon Sep 17 00:00:00 2001 From: Chris Date: Mon, 19 Oct 2026 13:03:06 -0400 Subject: [PATCH 3/3] removing extra download step. --- docs/install_qcow2_deployment.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/install_qcow2_deployment.md b/docs/install_qcow2_deployment.md index fb544e8ddfd..d46d4cad540 100644 --- a/docs/install_qcow2_deployment.md +++ b/docs/install_qcow2_deployment.md @@ -25,9 +25,8 @@ If you are installing a `qcow2` image on a VMWare ESXi environment, the `qcow2` 2. Install the qemu tools on a Linux staging host. Qemu is available natively for Linux distributions, and via third parties for other architectures such as [Windows](https://qemu.weilnetz.de/w64/) and [MacOS](https://formulae.brew.sh/formula/qemu). -3. Download the `qcow2` file. +3. Use the `qemu-img` example code below to run the conversion on the Linux host: -4. Use the `qemu-img` example code below to run the conversion on the Linux host: ``` $ file SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.qcow2 SSR-7.2.4-4.r2.el9.x86_64.ibu-v1.qcow2: QEMU QCOW2 Image (v3), 10173284352 bytes