Difference between revisions of "QuantaStor Upgrade Guide"

From OSNEXUS Online Documentation Site
Jump to: navigation, search
m
m (qstorservice)
(20 intermediate revisions by the same user 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  
 +
[http://wiki.osnexus.com/mediawiki/index.php/Storage_System_Upgrade_Manager_Dialog Upgrade Manager] 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.   
  
On occasion we'll update the QuantaStor configuration file /etc/quantastor.conf and 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 fileThis is to prevent the installer from overwriting your 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.  Why? Well, for default settings that are not in the quantastor.conf file the service will automatically use it's stored defaults which are fine for 99% of all configurations.  The one exception that comes to mind 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.
+
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.  
  
In rare instances we make changes to our embedded Apache Tomcat server, and you can upgrade it like so:
+
==== Web UI Blank Screen ====
  
<pre>
+
'''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. 
sudo apt-get update
+
 
sudo apt-get install qstortarget
+
==== Custom Configuration File Changes ====
</pre>
+
 
 +
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 ==
 
== Package Details ==
  
=== 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.
 
 
=== qstorservice ===
 
=== 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:
+
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 /etc/init.d/quantastor stop
+
"sudo service quantastor stop" and
sudo /etc/init.d/quantastor start
+
"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.  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.  
+
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 ===
 
=== 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 systemFortunately we do not modify the qstortarget very often.
+
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>
 +
service iscsi-target restart
 +
service quantastor restart
 +
</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.
 +
 
 +
== Upgrading QuantaStor v2 ==
 +
The package repository for QuantaStor v2 has changed so in order to upgrade your system or add new packages you'll need to run a short script from the QuantaStor consoleThis will allow you to upgrade to the latest version of v2 which as of this writing is v2.9.2.  Upgrading to v3 requires installing from ISO, but the pools, volumes and shares will automatically be re-imported and you can use the 'Recovery Manager' to recover you v2 configuration settings.
 +
 
 +
<pre>
 +
wget http://www.osnexus.com/storage/scripts/sources.list
 +
cp /etc/apt/sources.list /etc/apt/sources.list.preup
 +
chmod 644 sources.list
 +
cp sources.list /etc/apt/sources.list
 +
apt-get update
 +
apt-get install qstorservice qstormanager qstortomcat qstortarget
 +
</pre>
 +
 
 +
- or -
 +
 
 +
<pre>
 +
wget http://www.osnexus.com/storage/scripts/aptpatch.sh
 +
chmod 755 aptpatch.sh
 +
sudo ./aptpatch.sh
 +
apt-get update
 +
apt-get install qstorservice qstormanager qstortomcat qstortarget
 +
</pre>

Revision as of 11:52, 26 March 2019

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 Upgrade Manager 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.

Upgrading QuantaStor v2

The package repository for QuantaStor v2 has changed so in order to upgrade your system or add new packages you'll need to run a short script from the QuantaStor console. This will allow you to upgrade to the latest version of v2 which as of this writing is v2.9.2. Upgrading to v3 requires installing from ISO, but the pools, volumes and shares will automatically be re-imported and you can use the 'Recovery Manager' to recover you v2 configuration settings.

wget http://www.osnexus.com/storage/scripts/sources.list
cp /etc/apt/sources.list /etc/apt/sources.list.preup
chmod 644 sources.list
cp sources.list /etc/apt/sources.list
apt-get update
apt-get install qstorservice qstormanager qstortomcat qstortarget

- or -

wget http://www.osnexus.com/storage/scripts/aptpatch.sh
chmod 755 aptpatch.sh
sudo ./aptpatch.sh
apt-get update
apt-get install qstorservice qstormanager qstortomcat qstortarget