QuantaStor Upgrade Guide: Difference between revisions

From OSNEXUS Online Documentation Site
Jump to navigation Jump to search
← Older edit
Visual
mNo edit summary
 
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
QuantaStor is regularly evolving to make it more robust and better performing.  As such we release minor updates to QuantaStor on a regular basis and you can view the [http://www.osnexus.com/news News] section or review the [[QuantaStor Version ChangeLog|Change Log]] to get all the details about what has changed since the build that you're running.  
QuantaStor is regularly evolving to add new features, make it more robust, and better performing.  As such we release minor updates to QuantaStor on a regular basis and you can view the [http://www.osnexus.com/news News] section or review the [[QuantaStor Version ChangeLog|Change Log]] to get all the details about what has changed since the build that you're running.  


Upgrading QuantaStor to the latest version is relatively simple and amounts to running the following commands while logged into the system console account as qadmin:
== Web Based Upgrade Procedure ==
 
Upgrading QuantaStor to the latest version is made easy using the  
[https://wiki.osnexus.com/index.php?title=Storage_System_Upgrade_Manager Storage System Upgrade Manager Dialog] that's integrated into the web management interface.  Alternatively you can run this command to upgrade your system at the console or via an SSH session:
 
== Console Based Upgrade Procedure ==
 
<pre>
sudo qs-upgrade
</pre>
 
=== Upgrading Specific Components ===


<pre>
<pre>
sudo apt-get update
sudo apt-get update
sudo apt-get install qstormanager qstorservice qstortarget
sudo apt-get install qstormanager qstorservice qstortarget qstortomcat
</pre>
</pre>


The qstormanager qstorservice qstortarget components are 'user-mode' and have no impact on workloads.  The qstortarget package includes device drivers and should only be upgraded when you can take a maintenance window to reboot the appliance.
==== Details ====
The first part of the update process 'apt-get update' tells the system to update it's information about what packages are available from the OS NEXUS package server (http://packages.osnexus.com/packages).  The second part tells the system to install the latest versions of the qstormanager, qstorservice, and qstortarget packages.   
The first part of the update process 'apt-get update' tells the system to update it's information about what packages are available from the OS NEXUS package server (http://packages.osnexus.com/packages).  The second part tells the system to install the latest versions of the qstormanager, qstorservice, and qstortarget packages.   


Generally speaking, 95% of the time you'll only need to upgrade the first two packages like so as it's rare that we upgrade the iSCSI target driver:
Often times an upgrade will only apply new qstormanager and qstorservice packages as it's fairly rare that we upgrade the driver package (qstortarget).  Since upgrading drivers including the iSCSI target driver can interrupt iSCSI access to your volumes we always note in the ChangeLog which releases have driver and or kernel packages available.


<pre>
==== Web UI Blank Screen ====
sudo apt-get update
 
sudo apt-get install qstormanager qstorservice
'''Important!''' After upgrading, be sure to clear the cache of any web browsers that were running the QuantaStor Manager web UI.  If you don't clear the browser cache you'll end up using the cached copy of the UI which may not be compatible with the new version of the service. 
</pre>


'''Important!''' After upgrading, be sure to restart any web browsers that were running the QuantaStor Manager web UI.  If you don't restart the browser or hit the re-load page button you'll end up using the cached copy of the UI which may not be compatible with the new version of the service.  So always hit that 'Reload current page' button after upgrading or restart the browser.
==== Custom Configuration File Changes ====


On occasion we'll update the QuantaStor configuration file /etc/quantastor.conf and in such cases you'll get a message from the installer asking whether or not it's OK to overwrite the installed file with the package maintainers configuration file.  This is to prevent the installer from overwriting your custom changes to the /etc/quantastor.conf file.  If you've made changes to the /etc/quantastor.conf file then choose 'N' otherwise choose 'Y'.  If you haven't made any changes, then it doesn't really matter, either choice is fine.  The service has default settings built-in so the quantastor.conf configuration file is not required.  If the file is missing or a new configuration setting is missing the QuantaStor service automatically uses it's own stored default which is fine for 99% of all configurations.   
On occasion we'll update the QuantaStor configuration file /etc/quantastor.conf and in such cases you'll get a message from the installer asking whether or not it's OK to overwrite the installed file with the package maintainers configuration file.  This is to prevent the installer from overwriting your custom changes to the /etc/quantastor.conf file.  If you've made changes to the /etc/quantastor.conf file then choose 'N' otherwise choose 'Y'.  If you haven't made any changes, then it doesn't really matter, either choice is fine.  The service has default settings built-in so the quantastor.conf configuration file is not required.  If the file is missing or a new configuration setting is missing the QuantaStor service automatically uses it's own stored default which is fine for 99% of all configurations.   
==== XenServer Virtual Appliance Upgrades ====
The one exception is the configuration file for the XenServer PV Virtual Appliance / VM. It requires that unidentifiable devices be usable, so it requires the 'allow_unident=1' setting which defaults to 'allow_unident=0'.  So if you're upgrading a QuantaStor XenServer PV VM be sure to '''not''' overwrite the config file, and if you do, be sure to edit /etc/quantastor.conf to set the allow_unident configuration setting back to 1 otherwise your Physical Disks will not be discovered.
The one exception is the configuration file for the XenServer PV Virtual Appliance / VM. It requires that unidentifiable devices be usable, so it requires the 'allow_unident=1' setting which defaults to 'allow_unident=0'.  So if you're upgrading a QuantaStor XenServer PV VM be sure to '''not''' overwrite the config file, and if you do, be sure to edit /etc/quantastor.conf to set the allow_unident configuration setting back to 1 otherwise your Physical Disks will not be discovered.


In very rare instances we make changes to our embedded Apache Tomcat server, and you can upgrade it like so:
== Package Details ==
 
=== qstorservice ===
The QuantaStor core services package is called qstorservice.  It contains the service, database, and all the surrounding components that are required for the storage system to run.  You can start and stop the QuantaStor service manually with these following commands respectively:
"sudo service quantastor stop" and
"sudo service quantastor start".
As part of the installation process the QuantaStor service is restarted and while it is starting up you will not have access to login to the storage system via the Web Management interface for about 60 seconds.  Starting and stopping the QuantaStor service will in no way interrupt access to you iSCSI disks / storage volumes.


=== qstortarget ===
The QuantaStor iSCSI target is a customized version of the open source SCST driver and includes support for iSCSI, FC, and Infiniband.  If you upgrade the target mode driver your system will continue to function normally but your new drivers will not become active until after you reboot.  You can manually restart the driver like so:
<pre>
<pre>
sudo apt-get update
service iscsi-target restart
sudo apt-get install qstortomcat
service quantastor restart
</pre>
</pre>
=== qstortomcat ===
QuantaStor's web management interface is served by the Apache Tomcat web server.  The Tomcat package is just an embedded packaging of the Tomcat web server plus our iptables configuration script.  The web management interface packages are included in the qstormanager package.
=== qstormanager ===
The qstormanager package contains the QuantaStor Manager web management interface and it depends on the qstortomcat package.  It depends on qstortomcat as it contains a specially configured version of Apache Tomcat which is installed to /opt/osnexus/quantastor/tomcat.  The QuantaStor Manager package brings the Java servlet backend component that runs under Apache Tomcat as well as all the front-end QuantaStor Manager JavaScript that runs in the browser.
== Recommended Distribution Upgrade Method for Scale-Up Systems ==
=== Pre-Upgrade Checklist ===
# It is recommended that you schedule a downtime work window, as '''a reboot will be required''' after a distro upgrade.
# For more complex upgrades we recommend scheduling time with OSNEXUS support for assistance
# Execute the distribution upgrade within a ‘screen’ session to prevent issues in case of network disconnection.
# It is advisable to stop clients from using the system, including stopping or pausing virtual machines that are consuming storage volumes presented from QuantaStor.
# Submit logs from all nodes to Support using the ‘[https://wiki.osnexus.com/index.php?title=Send_Support_Log_Files Send Support Logs]’ option in the WUI.
# Place the cluster into ‘[https://wiki.osnexus.com/index.php?title=Enter_Site_Cluster_Maintenance_Mode Maintenance Mode]’ to prevent automatic failover during the upgrade.
# For systems running 18.04 Bionic, it is required to upgrade through 20.04 Focal and then to 22.04 Jammy. To avoid any risks during the upgrade, it may be easier to make a backup of the osn.db and other relevant configuration files, and reinstall. OSNEXUS Support will best guide you on this.
=== Upgrade QuantaStor Version ===
OSNEXUS recommends that QuantaStor is upgraded to the most recent version with a full upgrade before performing a distribution upgrade. You can do this from the WUI (Web User Interface) using the ‘[[Upgrade Manager]]’ and specifying to include the kernel. A full upgrade, depending on the version you are originating from, may require a reboot. The WUI should inform you if this is the case, but it is generally a good idea to reboot the system anyway, just to ensure it can boot normally. This is good preparation for the distribution upgrade.
=== Upgrade Ubuntu OS Distribution ===
Note: This procedure upgrades the Ubuntu operating system to the next major version and updates QuantaStor to the latest release supported by that version.
To upgrade the distribution for QuantaStor Scale-Up systems, follow these steps:
'''Upgrade from 18.04 Bionic to 20.04 Focal'''
# Ensure that QuantaStor node is upgraded (including Kernel) to the most recent version using the ‘[[Upgrade Manager]]’
# Reboot to ensure that the system boots without an issue
# The site cluster HA (High Availability) between Bionic and Focal is not compatible. Site cluster VIFs must be deleted and migrated to local VIFs, along with deleting the site cluster configuration from all nodes.
# Ensure you are in a screen session as per the '''Pre-Upgrade Checklist for Scale-Up.'''
# Log in as root and execute the command '''''qs-distupgrade'''''.
# If you are not using ‘screen’, then you may be prompted "Do you want to continue without session continuation protection provided by the screen. (y/n) default: no ?", you can '''choose 'y' or 'n'. Please note that your input is taken straight away without pressing the Enter key'''.
# When asked "Do you want to proceed with the distribution upgrade for the base platform. (y/n) ?", '''type 'y'. Please note that your input is taken straight away without pressing the Enter key.'''
# When prompted "Do you wish to gather logs (y/n) Default:no ?", '''type 'y'. * Please note that your input is taken straight away without pressing the Enter key.'''
# Wait for the upgrade process to complete.
# Reboot the server. Check if the system comes online and is healthy (as confirmed with '''''qs-showlog -f''''' or in /var/log/qs/qs_service.log when the services start), then proceed to upgrade the other system.
# Repeat steps 1-10 on all nodes within the cluster.
# Once all systems are upgraded, do not recreate the cluster yet. Continue upgrading to 22.04 Jammy.
'''Upgrade from 20.04 Focal to 22.04 Jammy'''


This will interrupt any active web management sessions you have running, so it's best to restart your browser.
# If you are upgrading from 18.04 Bionic to 20.04 Focal, do not recreate the cluster yet and skip steps 3 and 4. The cluster should only be recreated once all nodes have been upgraded to the latest OS and QuantaStor version. Otherwise, follow the procedure as documented.
# Ensure you are in a screen session as per the '''Pre-Upgrade Checklist for Scale-Up.'''
# For HA (High Availability) setup, via the WUI perform a failover of the pool(s) to one system before performing a full upgrade (including reboot).
# Place the cluster into ‘[https://wiki.osnexus.com/index.php?title=Enter_Site_Cluster_Maintenance_Mode Maintenance Mode]’.
# Ensure that QuantaStor node is upgraded (including Kernel) to the most recent version using the ‘[https://wiki.osnexus.com/index.php?title=Upgrade_Manager Upgrade Manager]’
# Log in as root and execute the command '''''qs-distupgrade'''''.
# If you are not using ‘screen’, then you may be prompted "Do you want to continue without session continuation protection provided by the screen. (y/n) default: no ?", you can '''choose 'y' or 'n'. Please note that your input is taken straight away without pressing the Enter key.'''
# When asked "Do you want to proceed with the distribution upgrade for the base platform. (y/n) ?", '''type 'y'. Please note that your input is taken straight away without pressing the Enter key.'''
# When prompted "Do you wish to gather logs (y/n) Default:no ?", '''type 'y'. * Please note that your input is taken straight away without pressing the Enter key.'''
# Wait for the upgrade process to complete.
# Reboot the server. Check if the system comes online and is healthy (as confirmed with '''''qs-showlog -f''''' or in /var/log/qs/qs_service.log when the services start), then proceed to upgrade the other system.
# Repeat steps 2-11 on all nodes within the cluster.


== Package Details ==


=== qstormanager ===
''* Gathering and submitting logs to OSNexus support will better assist in resolving any encountered issues.''
The qstormanager package contains the QuantaStor Manager web management interface and it depends on the qstortomcat package.  It depends on qstortomcat as it contains a specially configured version of Apache Tomcat which is installed to /opt/osnexus/quantastor/tomcat.  The QuantaStor Manager package brings the Java servlet backend component that runs under Apache Tomcat as well as all the front-end QuantaStor Manager JavaScript that runs in the browser.
=== qstorservice ===
The QuantaStor Service is the core or 'brain' of the storage system and it is packaged in the qstorservice package.  It contains the service, database, and all the surrounding components that are required for the storage system to run.  You can start and stop the QuantaStor service manually with these following commands respectively:
sudo /etc/init.d/quantastor stop
sudo /etc/init.d/quantastor start
As part of the installation process the QuantaStor service is restarted and while it is starting up you will not have access to login to the storage system via the Web Management interface. After about 1 minute you'll be able to login again.  Starting and stopping the QuantaStor service will in no way interrupt access to you iSCSI disks / storage volumes.
=== qstortarget ===
The QuantaStor iSCSI target is a customized version of the open source IET (iSCSI Enterprise Target) driver.  If you upgrade the target mode driver you can get a momentary loss of iSCSI access to your targets and in some cases you may need to reboot the storage system.  Fortunately we do not modify the qstortarget very often.

Latest revision as of 07:39, 5 September 2025

QuantaStor is regularly evolving to add new features, make it more robust, and better performing. As such we release minor updates to QuantaStor on a regular basis and you can view the News section or review the Change Log to get all the details about what has changed since the build that you're running.

Web Based Upgrade Procedure

Upgrading QuantaStor to the latest version is made easy using the Storage System Upgrade Manager Dialog that's integrated into the web management interface. Alternatively you can run this command to upgrade your system at the console or via an SSH session:

Console Based Upgrade Procedure

sudo qs-upgrade

Upgrading Specific Components

sudo apt-get update
sudo apt-get install qstormanager qstorservice qstortarget qstortomcat


The qstormanager qstorservice qstortarget components are 'user-mode' and have no impact on workloads. The qstortarget package includes device drivers and should only be upgraded when you can take a maintenance window to reboot the appliance.

Details

The first part of the update process 'apt-get update' tells the system to update it's information about what packages are available from the OS NEXUS package server (http://packages.osnexus.com/packages). The second part tells the system to install the latest versions of the qstormanager, qstorservice, and qstortarget packages.

Often times an upgrade will only apply new qstormanager and qstorservice packages as it's fairly rare that we upgrade the driver package (qstortarget). Since upgrading drivers including the iSCSI target driver can interrupt iSCSI access to your volumes we always note in the ChangeLog which releases have driver and or kernel packages available.

Web UI Blank Screen

Important! After upgrading, be sure to clear the cache of any web browsers that were running the QuantaStor Manager web UI. If you don't clear the browser cache you'll end up using the cached copy of the UI which may not be compatible with the new version of the service.

Custom Configuration File Changes

On occasion we'll update the QuantaStor configuration file /etc/quantastor.conf and in such cases you'll get a message from the installer asking whether or not it's OK to overwrite the installed file with the package maintainers configuration file. This is to prevent the installer from overwriting your custom changes to the /etc/quantastor.conf file. If you've made changes to the /etc/quantastor.conf file then choose 'N' otherwise choose 'Y'. If you haven't made any changes, then it doesn't really matter, either choice is fine. The service has default settings built-in so the quantastor.conf configuration file is not required. If the file is missing or a new configuration setting is missing the QuantaStor service automatically uses it's own stored default which is fine for 99% of all configurations.

XenServer Virtual Appliance Upgrades

The one exception is the configuration file for the XenServer PV Virtual Appliance / VM. It requires that unidentifiable devices be usable, so it requires the 'allow_unident=1' setting which defaults to 'allow_unident=0'. So if you're upgrading a QuantaStor XenServer PV VM be sure to not overwrite the config file, and if you do, be sure to edit /etc/quantastor.conf to set the allow_unident configuration setting back to 1 otherwise your Physical Disks will not be discovered.

Package Details

qstorservice

The QuantaStor core services package is called qstorservice. It contains the service, database, and all the surrounding components that are required for the storage system to run. You can start and stop the QuantaStor service manually with these following commands respectively: "sudo service quantastor stop" and "sudo service quantastor start". As part of the installation process the QuantaStor service is restarted and while it is starting up you will not have access to login to the storage system via the Web Management interface for about 60 seconds. Starting and stopping the QuantaStor service will in no way interrupt access to you iSCSI disks / storage volumes.

qstortarget

The QuantaStor iSCSI target is a customized version of the open source SCST driver and includes support for iSCSI, FC, and Infiniband. If you upgrade the target mode driver your system will continue to function normally but your new drivers will not become active until after you reboot. You can manually restart the driver like so: 

service iscsi-target restart
service quantastor restart

qstortomcat

QuantaStor's web management interface is served by the Apache Tomcat web server. The Tomcat package is just an embedded packaging of the Tomcat web server plus our iptables configuration script. The web management interface packages are included in the qstormanager package.

qstormanager

The qstormanager package contains the QuantaStor Manager web management interface and it depends on the qstortomcat package. It depends on qstortomcat as it contains a specially configured version of Apache Tomcat which is installed to /opt/osnexus/quantastor/tomcat. The QuantaStor Manager package brings the Java servlet backend component that runs under Apache Tomcat as well as all the front-end QuantaStor Manager JavaScript that runs in the browser.

Recommended Distribution Upgrade Method for Scale-Up Systems

Pre-Upgrade Checklist

  1. It is recommended that you schedule a downtime work window, as a reboot will be required after a distro upgrade.
  2. For more complex upgrades we recommend scheduling time with OSNEXUS support for assistance
  3. Execute the distribution upgrade within a ‘screen’ session to prevent issues in case of network disconnection.
  4. It is advisable to stop clients from using the system, including stopping or pausing virtual machines that are consuming storage volumes presented from QuantaStor.
  5. Submit logs from all nodes to Support using the ‘Send Support Logs’ option in the WUI.
  6. Place the cluster into ‘Maintenance Mode’ to prevent automatic failover during the upgrade.
  7. For systems running 18.04 Bionic, it is required to upgrade through 20.04 Focal and then to 22.04 Jammy. To avoid any risks during the upgrade, it may be easier to make a backup of the osn.db and other relevant configuration files, and reinstall. OSNEXUS Support will best guide you on this.

Upgrade QuantaStor Version

OSNEXUS recommends that QuantaStor is upgraded to the most recent version with a full upgrade before performing a distribution upgrade. You can do this from the WUI (Web User Interface) using the ‘Upgrade Manager’ and specifying to include the kernel. A full upgrade, depending on the version you are originating from, may require a reboot. The WUI should inform you if this is the case, but it is generally a good idea to reboot the system anyway, just to ensure it can boot normally. This is good preparation for the distribution upgrade.

Upgrade Ubuntu OS Distribution

Note: This procedure upgrades the Ubuntu operating system to the next major version and updates QuantaStor to the latest release supported by that version.

To upgrade the distribution for QuantaStor Scale-Up systems, follow these steps:

Upgrade from 18.04 Bionic to 20.04 Focal

  1. Ensure that QuantaStor node is upgraded (including Kernel) to the most recent version using the ‘Upgrade Manager’
  2. Reboot to ensure that the system boots without an issue
  3. The site cluster HA (High Availability) between Bionic and Focal is not compatible. Site cluster VIFs must be deleted and migrated to local VIFs, along with deleting the site cluster configuration from all nodes.
  4. Ensure you are in a screen session as per the Pre-Upgrade Checklist for Scale-Up.
  5. Log in as root and execute the command qs-distupgrade.
  6. If you are not using ‘screen’, then you may be prompted "Do you want to continue without session continuation protection provided by the screen. (y/n) default: no ?", you can choose 'y' or 'n'. Please note that your input is taken straight away without pressing the Enter key.
  7. When asked "Do you want to proceed with the distribution upgrade for the base platform. (y/n) ?", type 'y'. Please note that your input is taken straight away without pressing the Enter key.
  8. When prompted "Do you wish to gather logs (y/n) Default:no ?", type 'y'. * Please note that your input is taken straight away without pressing the Enter key.
  9. Wait for the upgrade process to complete.
  10. Reboot the server. Check if the system comes online and is healthy (as confirmed with qs-showlog -f or in /var/log/qs/qs_service.log when the services start), then proceed to upgrade the other system.
  11. Repeat steps 1-10 on all nodes within the cluster.
  12. Once all systems are upgraded, do not recreate the cluster yet. Continue upgrading to 22.04 Jammy.

Upgrade from 20.04 Focal to 22.04 Jammy

  1. If you are upgrading from 18.04 Bionic to 20.04 Focal, do not recreate the cluster yet and skip steps 3 and 4. The cluster should only be recreated once all nodes have been upgraded to the latest OS and QuantaStor version. Otherwise, follow the procedure as documented.
  2. Ensure you are in a screen session as per the Pre-Upgrade Checklist for Scale-Up.
  3. For HA (High Availability) setup, via the WUI perform a failover of the pool(s) to one system before performing a full upgrade (including reboot).
  4. Place the cluster into ‘Maintenance Mode’.
  5. Ensure that QuantaStor node is upgraded (including Kernel) to the most recent version using the ‘Upgrade Manager’
  6. Log in as root and execute the command qs-distupgrade.
  7. If you are not using ‘screen’, then you may be prompted "Do you want to continue without session continuation protection provided by the screen. (y/n) default: no ?", you can choose 'y' or 'n'. Please note that your input is taken straight away without pressing the Enter key.
  8. When asked "Do you want to proceed with the distribution upgrade for the base platform. (y/n) ?", type 'y'. Please note that your input is taken straight away without pressing the Enter key.
  9. When prompted "Do you wish to gather logs (y/n) Default:no ?", type 'y'. * Please note that your input is taken straight away without pressing the Enter key.
  10. Wait for the upgrade process to complete.
  11. Reboot the server. Check if the system comes online and is healthy (as confirmed with qs-showlog -f or in /var/log/qs/qs_service.log when the services start), then proceed to upgrade the other system.
  12. Repeat steps 2-11 on all nodes within the cluster.


* Gathering and submitting logs to OSNexus support will better assist in resolving any encountered issues.

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