QuantaStor Local Update Mirror: Difference between revisions

From OSNEXUS Online Documentation Site
Jump to navigation Jump to search
← Older editNewer edit →
VisualWikitext
mNo edit summary
Rewrite: three mirror options (nginx on port 80, qs_rsync_mirror.sh, removable drive), QuantaStor VM notes, sizes and ports, checks, apt and DNS methods. Verified against QuantaStor 6.8.6.
Line 1: Line 1:
This page describes how to upgrade QuantaStor systems that have no internet access, using a local copy of the QuantaStor package repository. It covers where to host the copy, how to download and check it, and how to point the QuantaStor systems at it.
# [[#Choose where to host the mirror|Choose where to host the mirror]].
# [[#Download the QuantaStor repository|Download the QuantaStor repository]] with rsync.
# [[#Check the mirror before an upgrade|Check the mirror]] holds the release you plan to install.
# [[#Allow the QuantaStor systems to reach the mirror|Make the mirror reachable]] from the QuantaStor systems.
# [[#Point the QuantaStor systems at the mirror|Point the QuantaStor systems at the mirror]] and disable the Ubuntu package sources they cannot reach.
# [[#Upgrade as normal|Upgrade as normal]].
== Overview ==
== Overview ==


QuantaStor systems are sometimes deployed in sites where there's no public internet access.  On these deployments the QuantaStor systems are unable to directly access packages.osnexus.com and will need a local package mirror repository to run QuantaStor upgrades.  
QuantaStor systems at sites with no public internet access cannot reach packages.osnexus.com, so they need a local mirror of the repository to run upgrades. The mirror is a server or VM that holds a copy of the QuantaStor repository and serves it over HTTP. The QuantaStor systems reach it through their apt configuration, or through your internal DNS resolving packages.osnexus.com to the mirror.
 
Update the mirror before each upgrade, and check it again before the upgrade window. The mirror holds whichever release is current when you sync it.


The local package mirror is usually a VM, which has a copy of the QuantaStor repository, and other package files from packages.osnexus.com, so that the local DNS server can be configured to resolve packages.osnexus.com to the local mirror within the data center.
== Choose where to host the mirror ==


Below is our supported method of creating a local repository.
Pick the option that fits how your site connects to the internet.


The basic process:
{| class="wikitable"
! Option !! Where the mirror runs !! How the QuantaStor systems reach it
|-
| [[#Option 1: Ubuntu server with nginx on port 80|Option 1]] || An Ubuntu server or VM inside your network that can also reach the internet, such as a jump host || Port 80, by apt configuration or internal DNS
|-
| [[#Option 2: qs_rsync_mirror.sh|Option 2]] || An Ubuntu server or VM inside your network that can also reach the internet, such as a jump host, set up by a script || Port 9999, by apt configuration
|-
| [[#Option 3: Removable drive|Option 3]] || Downloaded on a machine with internet access and carried in on a removable drive, then copied to a mirror server inside your network or served straight from the drive || Port 80 or 9999, as for the mirror server, or 9999 from the drive
|}


# Setup the offline mirror VM which will run a web server to serve the packages to QuantaStor (nginx example below).
A QuantaStor VM can also host the mirror. See [[#Hosting the mirror on a QuantaStor VM|Hosting the mirror on a QuantaStor VM]].
# Download the QuantaStor repository (rsync example below, wget, ...)
# Either move the downloaded QuantaStor repository to the location where your QuantaStor servers live or setup networking to allow your QuantaStor servers to see your offline QuantaStor repository.
# Modify DNS so that the QuantaStor systems resolve packages.osnexus.com to point to your local QuantaStor repository OR modify certain /etc/apt files on each QuantaStor host to point to your QuantaStor repository (instead of packages.osnexus.com)
# Perform upgrade as normal


The offline QuantaStor repository will need to be updated before each upgrade.  This could be done with a cron job as shown below.
=== Option 1: Ubuntu server with nginx on port 80 ===


=== Setup the offline mirror VM and web server ===
Install nginx and rsync:
Any web server can be used to serve the offline QuantaStor repository to QuantaStor hosts for upgrading.  Below Nginx is used.  This ships with the QuantaStor software so a simple community edition licensed QuantaStor VM could be used to host the offline QuantaStor repository.  Any web server can be used.
<pre style="font-size: smaller">
apt-get install -y nginx rsync
</pre>


==== Setting up nginx on Ubuntu 18.04 or newer: ====
Create the file {{Code|1=/etc/nginx/sites-enabled/osnexus-mirror}} with the contents below. Replace "yourserver.example.net" with the mirror server's DNS name. The packages.osnexus.com entry lets the mirror answer when your internal DNS points that name at it. '''The file location may differ with other nginx versions or Linux distributions.'''
Edit the /etc/nginx/sites-enabled/osnexus-mirror file. '''Please note. The file may be different depending on your nginx version or Linux OS. '''
Replace "yourserver.example.net" with your web server DNS FQDN.<pre>


<pre style="font-size: smaller">
#
#
# A virtual host entry for an OSNEXUS QuantaStor mirror
# A virtual host entry for an OSNEXUS QuantaStor mirror
Line 29: Line 45:


server {
server {
     listen      80;
     listen      80 default_server;
     server_name  yourserver.example.net packages;
     server_name  yourserver.example.net packages packages.osnexus.com;
     location / {
     location / {
         root /var/lib/www/packages-root;
         root /var/lib/www/packages-root;
Line 36: Line 52:
     }
     }
}
}
</pre>Now restart nginx and ensure it is enabled to startup automatically.<pre>
</pre>
 
Ubuntu's nginx package enables a default site that answers requests made by IP address or by any name not listed above, so the mirror returns "404 Not Found" until it is removed. Remove it, check the configuration and restart nginx:
<pre style="font-size: smaller">
rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl enable nginx
systemctl enable nginx
systemctl restart nginx
systemctl restart nginx
</pre>
</pre>


==== Alternative (less robust) Method of Serving the Offline QuantaStor Repository ====
Then download the repository as described in [[#Download the QuantaStor repository|Download the QuantaStor repository]].
Python has an internal web server that can be easily used to serve the offline QuantaStor repository files to the QuantaStor servers being upgraded. This is a CLI process that runs the server when started and if ^C stopped stops the web server. This is not a robust permanent solution but can be used for upgrades.
 
=== Option 2: qs_rsync_mirror.sh ===
 
The {{Code|1=qs_rsync_mirror.sh}} script downloads the repository with rsync into {{Code|1=/var/lib/www/packages-root}} and, with the {{Code|1=-n}} option, adds an nginx site on port 9999. By default it skips the RHEL repositories and the older Ubuntu releases.
 
On the Ubuntu server, install nginx and rsync, download the script and run it. The script checks that nginx is installed before it does anything, including when it only downloads.
<pre style="font-size: smaller">
apt-get install -y nginx rsync
curl -O http://packages.osnexus.com/packages/quantastor-jammy/scripts/qs_rsync_mirror.sh
bash qs_rsync_mirror.sh -n
</pre>
<div class="mw-collapsible mw-collapsed">
'''Example output'''
<div class="mw-collapsible-content">
<pre style="font-size: smaller">
Creating credentials file in /tmp: /tmp/qs_rsync_mirror.credentials
Using existing exclude file: /var/lib/www/packages-root/exclude.list
Exclusions in /var/lib/www/packages-root/exclude.list:
index.html
precise/
trusty/
packages-redhat/
quantastor-rhel/
quantastor-redhat/
quantastor-xenial/
quantastor-bionic/
quantastor-focal-optional/
Bandwidth limit set to 50 Mbps.
Starting rsync process with options: -a --quiet
Mirror sync completed successfully.
Setting up Nginx configuration at /etc/nginx/sites-enabled/osnexus-mirror
Reloading Nginx...
Nginx is running and configuration was successfully reloaded.
 
Please update your apt configuration on any quantastor systems to point to the new local mirror: http://<ip>:9999/packages
Example: /etc/apt/sources.list.d/osnexus.list with the following content:


Note on this command the server will listen on port 9999 not the normal port 80 (or 443).  This means that the /etc/apt/sources* files will have to be changed to something like "http://<IP of offline QuantaStor repository>:9999/..."
deb http://<ip>:9999/packages/ quantastor-focal main
python3 -m http.server 9999
</pre>
That command should be run in the top level repository directory (ie the location where the repository was downloaded to). 
</div>
</div>


=== Download the QuantaStor repository ===
Use {{Code|1=-d}} to download to a different directory, for example on a larger data disk, and {{Code|1=-b}} to change the download bandwidth limit from the default of 50 Mbps. At the default limit the first download takes around two hours. Run the script with {{Code|1=-h}} for all options.
The official online QuantaStor repository is accessible via http/s as well as the rsync protocol. In the example below, rsync is used to mirror.  Rsync is useful because once your initial download has completed, future updates of your offline QuantaStor repository will only need to download new changes. (rsync can be used via the rsync protocol or rsync over ssh).


As the online QuantaStor repository is also accessible via http/s, other tools such as wget, aptly, or other mirroring tools can be used to download the QuantaStor repository.
When it finishes, the script prints an example apt line that names the {{Code|1=quantastor-focal}} suite. Use the line for your platform from [[#apt method|apt method]] instead. With this option the QuantaStor systems' apt source is {{Code|1=<nowiki>http://yourserver.example.net:9999/packages</nowiki>}}, and the [[#DNS method|DNS method]] does not apply.


==== Run an initial rsync to synchronize the QuantaStor update repository. ====
=== Option 3: Removable drive ===
<pre>
 
In an air-gapped environment, stage the repository with a removable drive. Download it to the drive on a machine with internet access, carry the drive in, and copy the repository onto a mirror server inside your network, which then serves it like any other mirror.
 
Format the drive as ext4. The download keeps Linux ownership and permissions on every file, which filesystems such as exFAT and NTFS cannot store. The examples below mount the drive at {{Code|1=/mnt/qsmirror}}.
 
On the machine with internet access, with the drive mounted, install nginx and rsync, download the script and run it with {{Code|1=-d}} pointing at the drive. The script needs nginx installed even though it does not serve anything here.
<pre style="font-size: smaller">
apt-get install -y nginx rsync
curl -O http://packages.osnexus.com/packages/quantastor-jammy/scripts/qs_rsync_mirror.sh
bash qs_rsync_mirror.sh -d /mnt/qsmirror/packages-root
</pre>
 
==== Stage the repository on a mirror server ====
 
Unmount the drive, carry it in, and mount it at {{Code|1=/mnt/qsmirror}} on the mirror server inside your network. Copy the repository to the directory the mirror serves:
<pre style="font-size: smaller">
rsync -a /mnt/qsmirror/packages-root/ /var/lib/www/packages-root/
</pre>
 
Then serve it on port 80 with the [[#Option 1: Ubuntu server with nginx on port 80|Option 1]] nginx configuration, or on port 9999 with {{Code|1=qs_rsync_mirror.sh}}, skipping the download:
<pre style="font-size: smaller">
bash qs_rsync_mirror.sh -s -n
</pre>
 
As in Option 2, the script ends with an example apt line for {{Code|1=quantastor-focal}}. Use the line for your platform from [[#apt method|apt method]] instead.
 
To refresh the mirror before a later upgrade, sync the drive again on the machine with internet access and repeat the copy. rsync copies only what has changed.
 
==== Serve directly from the drive ====
 
You can also serve the repository straight from the drive, without a mirror server, using the web server built into Python. It needs nothing installed and runs as an ordinary user:
<pre style="font-size: smaller">
cd /mnt/qsmirror/packages-root
python3 -m http.server 9999
</pre>
 
The Python web server runs only while the command runs, and stops when you press Ctrl+C. Leave it running until the upgrade is complete on every QuantaStor system, including any later Ceph cluster upgrade. The QuantaStor systems' apt source is {{Code|1=<nowiki>http://yourserver.example.net:9999/packages</nowiki>}}.
 
The same Python command can serve a repository downloaded by any of the other options, from the top level of the download, {{Code|1=/var/lib/www/packages-root}} by default.
 
=== Hosting the mirror on a QuantaStor VM ===
 
A QuantaStor VM can host the mirror, using {{Code|1=qs_rsync_mirror.sh}}, which ships on QuantaStor systems. On a QuantaStor VM:
 
* A QuantaStor VM used as the mirror needs its own license key. See [[License Management]].
* The script serves the mirror on port 9999 and leaves the web interface on ports 80 and 443 as it is.
* Do not use the Option 1 configuration. nginx on a QuantaStor system already serves the web interface on ports 80 and 443, so the DNS method is not available either.
* Check the free space before the first download. The repository needs about 48 GB, which can be more than the root volume of a QuantaStor VM has free. Add {{Code|1=-d}} followed by a directory on a larger disk to put it there.
* Keep the mirror off the QuantaStor systems you are upgrading. Each one restarts its services and reboots during its upgrade, and the mirror would be unavailable to the others while it does.
 
To download the repository and serve it on port 9999:
<pre style="font-size: smaller">
/opt/osnexus/quantastor/bin/qs_rsync_mirror.sh -n
</pre>
 
To serve a repository staged from a removable drive as in [[#Option 3: Removable drive|Option 3]], copy it into place and run the script without the download:
<pre style="font-size: smaller">
rsync -a /mnt/qsmirror/packages-root/ /var/lib/www/packages-root/
/opt/osnexus/quantastor/bin/qs_rsync_mirror.sh -s -n
</pre>
 
== Download the QuantaStor repository ==
 
OSNEXUS provides an rsync copy of the QuantaStor repository at pkgmirror.osnexus.com, and rsync is the supported way to download it. After the first download, rsync only fetches what has changed. The online repository at packages.osnexus.com does not allow directory listing, so recursive download tools such as wget cannot mirror it.
 
The full repository is about 84 GB. Excluding the RHEL repositories and the older Ubuntu releases brings it to about 48 GB. Both grow with each release. {{Code|1=qs_rsync_mirror.sh}} applies similar exclusions by default, and so does the command below. Remove its {{Code|1=--exclude}} options to download everything.
 
=== Run an initial rsync ===
<pre style="font-size: smaller">
mkdir -p /var/lib/www/packages-root/
mkdir -p /var/lib/www/packages-root/
RSYNC_PASSWORD=guest rsync -aPv rsync://guest@pkgmirror.osnexus.com/packages /var/lib/www/packages-root/
RSYNC_PASSWORD=guest rsync -aPv --exclude=packages-redhat/ --exclude=quantastor-rhel/ --exclude=quantastor-xenial/ --exclude=quantastor-bionic/ --exclude=precise/ --exclude=trusty/ rsync://guest@pkgmirror.osnexus.com/packages /var/lib/www/packages-root/
</pre>
</pre>


==== Update an already rsync'd QuantaStor repository ====
=== Update an existing mirror ===
For periodic automatic updates, add a cron entry that will run to synchronize your local mirror with the QuantaStor repository.  The example below runs daily. Just running the rsync part of this command will do a one time update.<pre>
To update the mirror on a schedule, create the file {{Code|1=/etc/cron.d/osnexus-mirror-sync}} with the line below, which runs daily at 02:00. Running the rsync command on its own does a one-time update.
edit the /etc/cron.d/osnexus-mirror-sync file and add the below contents:
<pre style="font-size: smaller">
0 02 * * * root RSYNC_PASSWORD=guest /usr/bin/rsync -aPv rsync://guest@pkgmirror.osnexus.com/packages /var/lib/www/packages-root/
0 02 * * * root RSYNC_PASSWORD=guest /usr/bin/rsync -aPv --exclude=packages-redhat/ --exclude=quantastor-rhel/ --exclude=quantastor-xenial/ --exclude=quantastor-bionic/ --exclude=precise/ --exclude=trusty/ rsync://guest@pkgmirror.osnexus.com/packages /var/lib/www/packages-root/
</pre>
</pre>


=== Allow Offline QuantaStor Servers to See the Downloaded QuantaStor Repository ===
'''Note.''' The mirror decides which versions an upgrade installs. The QuantaStor upgrade installs the newest QuantaStor packages on the mirror, and the Ceph cluster upgrade targets the Ceph version named in the mirror's {{Code|1=upgrade.conf}}. If you plan to upgrade QuantaStor first and Ceph in a later maintenance window, disable the scheduled sync between the two unless you intend to move to a newer release.
Each site will have different requirements for this process.  In some cases, the downloaded QuantaStor repository server would be isolated from the protected network via a firewall change, opened up to the internet for the download or update of the repository, then isolated from the internet and opened to the internal QuantaStor servers.
 
== Check the mirror before an upgrade ==
On the mirror server, after the sync, compare the mirror's release date and newest QuantaStor version with the online repository. This example is for QuantaStor systems based on Ubuntu 22.04, jammy. Replace {{Code|1=quantastor-jammy}} with {{Code|1=quantastor-focal}} or {{Code|1=quantastor-noble}} for those platforms, and {{Code|1=/var/lib/www/packages-root}} with the download directory if you changed it.
<pre style="font-size: smaller">
grep '^Date:' /var/lib/www/packages-root/packages/dists/quantastor-jammy/Release
zcat /var/lib/www/packages-root/packages/dists/quantastor-jammy/main/binary-amd64/Packages.gz | awk '/^Package: qstorservice$/{p=1} p && /^Version:/{print $2; p=0}' | sort -V | tail -1
curl -s http://packages.osnexus.com/packages/dists/quantastor-jammy/Release | grep '^Date:'
</pre>
<div class="mw-collapsible mw-collapsed">
'''Example output'''
<div class="mw-collapsible-content">
<pre style="font-size: smaller">
Date: Mon, 14 Sep 2026 12:08:50 GMT
6.8.6.015+454592a831-1
Date: Mon, 14 Sep 2026 12:08:50 GMT
</pre>
</div>
</div>


In another case, it may be download, scan, and physically move the offline QuantaStor repository to the location where the QuantaStor servers can see it.
The first and third dates should match, and the version should be the release you plan to install. See the [[QuantaStor Version ChangeLog]] for the current release. If the mirror is behind the online repository, contact OSNEXUS Support before the upgrade window.


Site policies will determine how you handle this step.
After you point a QuantaStor system at the mirror as described below, you can confirm on that system which QuantaStor version the upgrade will install and which Ceph version a Ceph cluster upgrade will target:
<pre style="font-size: smaller">
apt-get update
apt-cache policy qstorservice
curl -s http://yourserver.example.net/packages/quantastor-jammy/scripts/upgrade.conf | grep CEPH_VER
</pre>
<div class="mw-collapsible mw-collapsed">
'''Example output'''
<div class="mw-collapsible-content">
<pre style="font-size: smaller">
qstorservice:
  Installed: 6.7.2.003+ad12621f62-1
  Candidate: 6.8.6.015+454592a831-1
  Version table:
(version table omitted)
CEPH_VER=20.2.2
</pre>
</div>
</div>


=== Modify DNS or /etc/apt Prior to Upgrades ===
The "Candidate" line shows the QuantaStor version. With a mirror on port 9999, add :9999 after the server name in the curl command.
On the QuantaStor systems to be upgraded, the /etc/apt/sources* files point to "packages.osnexus.com".  Since they are offline, this cannot be accessed.


One method to make offline QuantaStor systems upgradable from the offline QuantaStor repository server would be to edit all /etc/apt/sources* files (including sources.list.d sub-directory files) to change packages.osnexus.com to point to the DNS name or IP of the offline QuantaStor repository server you setup.  NOTE other hostnames found in those files *.unbuntu.com do NOT need to be changed.  The QuantaStor qs_upgrade.py does NOT use those.
== Allow the QuantaStor systems to reach the mirror ==
The machine that downloads the repository needs outbound access to pkgmirror.osnexus.com on TCP port 873 for rsync. The QuantaStor systems need to reach the mirror on TCP port 80 or 9999, depending on how it is served.


Another method would be to change your internal DNS server to point "packages.quantastor.com" to your downloaded offline QuantaStor repository server.
Each site has different requirements beyond that. In some cases the mirror server sits behind a firewall that is opened to the internet for the download, then closed to the internet and opened to the internal QuantaStor systems. In others the repository is downloaded, scanned, and carried in as in Option 3. Site policies determine how you handle this step.


The example below should only be referenced for a method to change these files. NOTE it references a specific version of QuantaStor (focal) which may not be installed (ie jammy). Do NOT use this command without understanding how you should modify it.
== Point the QuantaStor systems at the mirror ==
On the QuantaStor systems, {{Code|1=/etc/apt/sources.list.d/osnexus.list}} points at packages.osnexus.com, which they cannot reach. Use one of the two methods below.


Add your new local repository mirror to your QuantaStor systems for all updates:
=== DNS method ===
Point packages.osnexus.com at the mirror server in your internal DNS. The Option 1 nginx configuration answers for that name. This method does not work with a mirror on port 9999.


Replace "yourserver.example.net" with your web server DNS FQDN.
=== apt method ===
Replace the contents of {{Code|1=/etc/apt/sources.list.d/osnexus.list}} on each QuantaStor system with a single line for your platform. Replace "yourserver.example.net" with the mirror server's DNS name or IP address, and add :9999 after it for a mirror on port 9999.


<pre>
<pre style="font-size: smaller">
# for focal based quantastor deployments
# focal, Ubuntu 20.04 based QuantaStor systems
echo 'deb http://yourserver.example.net/packages quantastor-focal main' > /etc/apt/sources.list.d/osnexus.list
echo 'deb http://yourserver.example.net/packages quantastor-focal main' > /etc/apt/sources.list.d/osnexus.list


# for bionic based QuantaStor deployments
# jammy, Ubuntu 22.04 based QuantaStor systems
echo 'deb http://yourserver.example.net/packages quantastor-bionic main' > /etc/apt/sources.list.d/osnexus.list
echo 'deb http://yourserver.example.net/packages quantastor-jammy main' > /etc/apt/sources.list.d/osnexus.list
 
# noble, Ubuntu 24.04 based QuantaStor systems
echo 'deb http://yourserver.example.net/packages quantastor-noble main' > /etc/apt/sources.list.d/osnexus.list
</pre>
</pre>


=== Perform upgrade as normal ===
Keep {{Code|1=osnexus.list}} to a single deb line in this form. The Ceph cluster upgrade reads the repository address and suite from this file.
After the above steps, QuantaStor hosts can be upgrade using all normal QuantaStor upgrade methods (Web UI, CLI)
 
=== Disable the Ubuntu package sources ===
The upgrade runs {{Code|1=apt-get update}} and {{Code|1=apt-get upgrade}}, which read every package source on the system, including the Ubuntu sources in {{Code|1=/etc/apt/sources.list}}. An unreachable source does not stop the upgrade, but it slows down every {{Code|1=apt-get update}} while the lookups fail. Disable these sources on each QuantaStor system before the upgrade:
<pre style="font-size: smaller">
sed -i -E 's/^(deb(-src)? .*ubuntu\.com.*)/# \1/' /etc/apt/sources.list /etc/apt/sources.list.d/*.list
</pre>
 
If the system has {{Code|1=/etc/apt/sources.list.d/ubuntu.sources}}, which uses the deb822 format, disable it as well:
<pre style="font-size: smaller">
sed -i '/^Types:/i Enabled: no' /etc/apt/sources.list.d/ubuntu.sources
</pre>
 
The Ubuntu packages that OSNEXUS publishes in the QuantaStor repository, such as security updates, still install from the mirror.
 
== Upgrade as normal ==
Upgrade the QuantaStor systems with the [[Upgrade Manager]] in the web interface or with the CLI, as you would with internet access.
 
OSNEXUS Support supports this process for licensed QuantaStor deployments. For further assistance, see https://www.osnexus.com for support options.
 
== Related pages ==
* [[Upgrade Manager]]
* [[QuantaStor Version ChangeLog]]


=== Summary ===
----
OSNEXUS Support will provide support for this process for licensed QuantaStor deployments. If you need any further assistance, please see https://www.osnexus.com for support options.
<small>''Verified against QuantaStor 6.8.6.''</small>

Revision as of 15:58, 13 October 2026

This page describes how to upgrade QuantaStor systems that have no internet access, using a local copy of the QuantaStor package repository. It covers where to host the copy, how to download and check it, and how to point the QuantaStor systems at it.

  1. Choose where to host the mirror.
  2. Download the QuantaStor repository with rsync.
  3. Check the mirror holds the release you plan to install.
  4. Make the mirror reachable from the QuantaStor systems.
  5. Point the QuantaStor systems at the mirror and disable the Ubuntu package sources they cannot reach.
  6. Upgrade as normal.

Overview

QuantaStor systems at sites with no public internet access cannot reach packages.osnexus.com, so they need a local mirror of the repository to run upgrades. The mirror is a server or VM that holds a copy of the QuantaStor repository and serves it over HTTP. The QuantaStor systems reach it through their apt configuration, or through your internal DNS resolving packages.osnexus.com to the mirror.

Update the mirror before each upgrade, and check it again before the upgrade window. The mirror holds whichever release is current when you sync it.

Choose where to host the mirror

Pick the option that fits how your site connects to the internet.

Option Where the mirror runs How the QuantaStor systems reach it
Option 1 An Ubuntu server or VM inside your network that can also reach the internet, such as a jump host Port 80, by apt configuration or internal DNS
Option 2 An Ubuntu server or VM inside your network that can also reach the internet, such as a jump host, set up by a script Port 9999, by apt configuration
Option 3 Downloaded on a machine with internet access and carried in on a removable drive, then copied to a mirror server inside your network or served straight from the drive Port 80 or 9999, as for the mirror server, or 9999 from the drive

A QuantaStor VM can also host the mirror. See Hosting the mirror on a QuantaStor VM.

Option 1: Ubuntu server with nginx on port 80

Install nginx and rsync: 

apt-get install -y nginx rsync

Create the file /etc/nginx/sites-enabled/osnexus-mirror with the contents below. Replace "yourserver.example.net" with the mirror server's DNS name. The packages.osnexus.com entry lets the mirror answer when your internal DNS points that name at it. The file location may differ with other nginx versions or Linux distributions. 

#
# A virtual host entry for an OSNEXUS QuantaStor mirror
#

server {
    listen       80 default_server;
    server_name  yourserver.example.net packages packages.osnexus.com;
    location / {
        root /var/lib/www/packages-root;
        autoindex on;
    }
}

Ubuntu's nginx package enables a default site that answers requests made by IP address or by any name not listed above, so the mirror returns "404 Not Found" until it is removed. Remove it, check the configuration and restart nginx: 

rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl enable nginx
systemctl restart nginx

Then download the repository as described in Download the QuantaStor repository.

Option 2: qs_rsync_mirror.sh

The qs_rsync_mirror.sh script downloads the repository with rsync into /var/lib/www/packages-root and, with the -n option, adds an nginx site on port 9999. By default it skips the RHEL repositories and the older Ubuntu releases.

On the Ubuntu server, install nginx and rsync, download the script and run it. The script checks that nginx is installed before it does anything, including when it only downloads. 

apt-get install -y nginx rsync
curl -O http://packages.osnexus.com/packages/quantastor-jammy/scripts/qs_rsync_mirror.sh
bash qs_rsync_mirror.sh -n

Example output 

Creating credentials file in /tmp: /tmp/qs_rsync_mirror.credentials
Using existing exclude file: /var/lib/www/packages-root/exclude.list
Exclusions in /var/lib/www/packages-root/exclude.list:
index.html
precise/
trusty/
packages-redhat/
quantastor-rhel/
quantastor-redhat/
quantastor-xenial/
quantastor-bionic/
quantastor-focal-optional/
Bandwidth limit set to 50 Mbps.
Starting rsync process with options: -a --quiet
Mirror sync completed successfully.
Setting up Nginx configuration at /etc/nginx/sites-enabled/osnexus-mirror
Reloading Nginx...
Nginx is running and configuration was successfully reloaded.

Please update your apt configuration on any quantastor systems to point to the new local mirror: http://<ip>:9999/packages
Example: /etc/apt/sources.list.d/osnexus.list with the following content:

deb http://<ip>:9999/packages/ quantastor-focal main

Use -d to download to a different directory, for example on a larger data disk, and -b to change the download bandwidth limit from the default of 50 Mbps. At the default limit the first download takes around two hours. Run the script with -h for all options.

When it finishes, the script prints an example apt line that names the quantastor-focal suite. Use the line for your platform from apt method instead. With this option the QuantaStor systems' apt source is http://yourserver.example.net:9999/packages, and the DNS method does not apply.

Option 3: Removable drive

In an air-gapped environment, stage the repository with a removable drive. Download it to the drive on a machine with internet access, carry the drive in, and copy the repository onto a mirror server inside your network, which then serves it like any other mirror.

Format the drive as ext4. The download keeps Linux ownership and permissions on every file, which filesystems such as exFAT and NTFS cannot store. The examples below mount the drive at /mnt/qsmirror.

On the machine with internet access, with the drive mounted, install nginx and rsync, download the script and run it with -d pointing at the drive. The script needs nginx installed even though it does not serve anything here. 

apt-get install -y nginx rsync
curl -O http://packages.osnexus.com/packages/quantastor-jammy/scripts/qs_rsync_mirror.sh
bash qs_rsync_mirror.sh -d /mnt/qsmirror/packages-root

Stage the repository on a mirror server

Unmount the drive, carry it in, and mount it at /mnt/qsmirror on the mirror server inside your network. Copy the repository to the directory the mirror serves: 

rsync -a /mnt/qsmirror/packages-root/ /var/lib/www/packages-root/

Then serve it on port 80 with the Option 1 nginx configuration, or on port 9999 with qs_rsync_mirror.sh, skipping the download: 

bash qs_rsync_mirror.sh -s -n

As in Option 2, the script ends with an example apt line for quantastor-focal. Use the line for your platform from apt method instead.

To refresh the mirror before a later upgrade, sync the drive again on the machine with internet access and repeat the copy. rsync copies only what has changed.

Serve directly from the drive

You can also serve the repository straight from the drive, without a mirror server, using the web server built into Python. It needs nothing installed and runs as an ordinary user: 

cd /mnt/qsmirror/packages-root
python3 -m http.server 9999

The Python web server runs only while the command runs, and stops when you press Ctrl+C. Leave it running until the upgrade is complete on every QuantaStor system, including any later Ceph cluster upgrade. The QuantaStor systems' apt source is http://yourserver.example.net:9999/packages.

The same Python command can serve a repository downloaded by any of the other options, from the top level of the download, /var/lib/www/packages-root by default.

Hosting the mirror on a QuantaStor VM

A QuantaStor VM can host the mirror, using qs_rsync_mirror.sh, which ships on QuantaStor systems. On a QuantaStor VM:

  • A QuantaStor VM used as the mirror needs its own license key. See License Management.
  • The script serves the mirror on port 9999 and leaves the web interface on ports 80 and 443 as it is.
  • Do not use the Option 1 configuration. nginx on a QuantaStor system already serves the web interface on ports 80 and 443, so the DNS method is not available either.
  • Check the free space before the first download. The repository needs about 48 GB, which can be more than the root volume of a QuantaStor VM has free. Add -d followed by a directory on a larger disk to put it there.
  • Keep the mirror off the QuantaStor systems you are upgrading. Each one restarts its services and reboots during its upgrade, and the mirror would be unavailable to the others while it does.

To download the repository and serve it on port 9999: 

/opt/osnexus/quantastor/bin/qs_rsync_mirror.sh -n

To serve a repository staged from a removable drive as in Option 3, copy it into place and run the script without the download: 

rsync -a /mnt/qsmirror/packages-root/ /var/lib/www/packages-root/
/opt/osnexus/quantastor/bin/qs_rsync_mirror.sh -s -n

Download the QuantaStor repository

OSNEXUS provides an rsync copy of the QuantaStor repository at pkgmirror.osnexus.com, and rsync is the supported way to download it. After the first download, rsync only fetches what has changed. The online repository at packages.osnexus.com does not allow directory listing, so recursive download tools such as wget cannot mirror it.

The full repository is about 84 GB. Excluding the RHEL repositories and the older Ubuntu releases brings it to about 48 GB. Both grow with each release. qs_rsync_mirror.sh applies similar exclusions by default, and so does the command below. Remove its --exclude options to download everything.

Run an initial rsync

mkdir -p /var/lib/www/packages-root/
RSYNC_PASSWORD=guest rsync -aPv --exclude=packages-redhat/ --exclude=quantastor-rhel/ --exclude=quantastor-xenial/ --exclude=quantastor-bionic/ --exclude=precise/ --exclude=trusty/ rsync://guest@pkgmirror.osnexus.com/packages /var/lib/www/packages-root/

Update an existing mirror

To update the mirror on a schedule, create the file /etc/cron.d/osnexus-mirror-sync with the line below, which runs daily at 02:00. Running the rsync command on its own does a one-time update. 

0 02 * * * root RSYNC_PASSWORD=guest /usr/bin/rsync -aPv --exclude=packages-redhat/ --exclude=quantastor-rhel/ --exclude=quantastor-xenial/ --exclude=quantastor-bionic/ --exclude=precise/ --exclude=trusty/ rsync://guest@pkgmirror.osnexus.com/packages /var/lib/www/packages-root/

Note. The mirror decides which versions an upgrade installs. The QuantaStor upgrade installs the newest QuantaStor packages on the mirror, and the Ceph cluster upgrade targets the Ceph version named in the mirror's upgrade.conf. If you plan to upgrade QuantaStor first and Ceph in a later maintenance window, disable the scheduled sync between the two unless you intend to move to a newer release.

Check the mirror before an upgrade

On the mirror server, after the sync, compare the mirror's release date and newest QuantaStor version with the online repository. This example is for QuantaStor systems based on Ubuntu 22.04, jammy. Replace quantastor-jammy with quantastor-focal or quantastor-noble for those platforms, and /var/lib/www/packages-root with the download directory if you changed it. 

grep '^Date:' /var/lib/www/packages-root/packages/dists/quantastor-jammy/Release
zcat /var/lib/www/packages-root/packages/dists/quantastor-jammy/main/binary-amd64/Packages.gz | awk '/^Package: qstorservice$/{p=1} p && /^Version:/{print $2; p=0}' | sort -V | tail -1
curl -s http://packages.osnexus.com/packages/dists/quantastor-jammy/Release | grep '^Date:'

Example output 

Date: Mon, 14 Sep 2026 12:08:50 GMT
6.8.6.015+454592a831-1
Date: Mon, 14 Sep 2026 12:08:50 GMT

The first and third dates should match, and the version should be the release you plan to install. See the QuantaStor Version ChangeLog for the current release. If the mirror is behind the online repository, contact OSNEXUS Support before the upgrade window.

After you point a QuantaStor system at the mirror as described below, you can confirm on that system which QuantaStor version the upgrade will install and which Ceph version a Ceph cluster upgrade will target: 

apt-get update
apt-cache policy qstorservice
curl -s http://yourserver.example.net/packages/quantastor-jammy/scripts/upgrade.conf | grep CEPH_VER

Example output 

qstorservice:
  Installed: 6.7.2.003+ad12621f62-1
  Candidate: 6.8.6.015+454592a831-1
  Version table:
(version table omitted)
CEPH_VER=20.2.2

The "Candidate" line shows the QuantaStor version. With a mirror on port 9999, add :9999 after the server name in the curl command.

Allow the QuantaStor systems to reach the mirror

The machine that downloads the repository needs outbound access to pkgmirror.osnexus.com on TCP port 873 for rsync. The QuantaStor systems need to reach the mirror on TCP port 80 or 9999, depending on how it is served.

Each site has different requirements beyond that. In some cases the mirror server sits behind a firewall that is opened to the internet for the download, then closed to the internet and opened to the internal QuantaStor systems. In others the repository is downloaded, scanned, and carried in as in Option 3. Site policies determine how you handle this step.

Point the QuantaStor systems at the mirror

On the QuantaStor systems, /etc/apt/sources.list.d/osnexus.list points at packages.osnexus.com, which they cannot reach. Use one of the two methods below.

DNS method

Point packages.osnexus.com at the mirror server in your internal DNS. The Option 1 nginx configuration answers for that name. This method does not work with a mirror on port 9999.

apt method

Replace the contents of /etc/apt/sources.list.d/osnexus.list on each QuantaStor system with a single line for your platform. Replace "yourserver.example.net" with the mirror server's DNS name or IP address, and add :9999 after it for a mirror on port 9999. 

# focal, Ubuntu 20.04 based QuantaStor systems
echo 'deb http://yourserver.example.net/packages quantastor-focal main' > /etc/apt/sources.list.d/osnexus.list

# jammy, Ubuntu 22.04 based QuantaStor systems
echo 'deb http://yourserver.example.net/packages quantastor-jammy main' > /etc/apt/sources.list.d/osnexus.list

# noble, Ubuntu 24.04 based QuantaStor systems
echo 'deb http://yourserver.example.net/packages quantastor-noble main' > /etc/apt/sources.list.d/osnexus.list

Keep osnexus.list to a single deb line in this form. The Ceph cluster upgrade reads the repository address and suite from this file.

Disable the Ubuntu package sources

The upgrade runs apt-get update and apt-get upgrade, which read every package source on the system, including the Ubuntu sources in /etc/apt/sources.list. An unreachable source does not stop the upgrade, but it slows down every apt-get update while the lookups fail. Disable these sources on each QuantaStor system before the upgrade: 

sed -i -E 's/^(deb(-src)? .*ubuntu\.com.*)/# \1/' /etc/apt/sources.list /etc/apt/sources.list.d/*.list

If the system has /etc/apt/sources.list.d/ubuntu.sources, which uses the deb822 format, disable it as well: 

sed -i '/^Types:/i Enabled: no' /etc/apt/sources.list.d/ubuntu.sources

The Ubuntu packages that OSNEXUS publishes in the QuantaStor repository, such as security updates, still install from the mirror.

Upgrade as normal

Upgrade the QuantaStor systems with the Upgrade Manager in the web interface or with the CLI, as you would with internet access.

OSNEXUS Support supports this process for licensed QuantaStor deployments. For further assistance, see https://www.osnexus.com for support options.

Related pages

Verified against QuantaStor 6.8.6.

Retrieved from "https://wiki.osnexus.com/index.php?title=QuantaStor_Local_Update_Mirror&oldid=28257"