Difference between revisions of "QuantaStor Upgrade Guide"

From OSNEXUS Online Documentation Site
Jump to: navigation, search
m (Upgrading QuantaStor v2)
m (Upgrading QuantaStor v3.x to v3.5 or newer)
(4 intermediate revisions by the same user not shown)
Line 4: Line 4:
  
 
Upgrading QuantaStor to the latest version is made easy using the  
 
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 script to upgrade your system at the console or via an SSH session:
+
[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 ==
 
== Console Based Upgrade Procedure ==
  
 
<pre>
 
<pre>
sudo qs_upgrade.sh
+
sudo qs-upgrade
 
</pre>
 
</pre>
  
For older versions of Quantastor that do not include the qs_upgrade.sh script you can use the following commands to upgrade:
+
=== Upgrading Specific Components ===
  
 
<pre>
 
<pre>
Line 19: Line 19:
 
</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, most of the time you'll only need to upgrade the first two packages as it's rare that we upgrade the iSCSI target driver.  Since upgrading the iSCSI target driver can interrupt iSCSI access to your volumes we are taking a policy of noting in the ChangeLog which version releases have an update to the iSCSI target driver with an asterisk (*) so you know when upgrading it is recommended or required. Here's how to do the upgrade of just the service and management interface w/o the 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
+
</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. 
  
'''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:
 
 
<pre>
 
sudo apt-get update
 
sudo apt-get install qstortomcat
 
</pre>
 
 
This will interrupt any active web management sessions you have running, so it's best to restart your browser.
 
  
 
== Package Details ==
 
== Package Details ==
  
 
=== 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 service quantastor stop
 
sudo service quantastor stop
 
sudo service 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 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:
 
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:
Line 82: Line 77:
 
apt-get install qstorservice qstormanager qstortomcat qstortarget
 
apt-get install qstorservice qstormanager qstortomcat qstortarget
 
</pre>
 
</pre>
 
== Upgrading QuantaStor v3.x to v3.5 or newer ==
 
 
We did a major kernel upgrade with the v3.5 release which corrected problems found with the btrfs filesystem.  QuantaStor upgrades which are handled via the web management interface are non-disruptive but given the full distro upgrade included with the new kernel the easiest way to upgrade is to just install from ISO.  That said, you can do a manual upgrade by following these steps which will install the new kernel and the associated iSCSI packages plus some new samba and security packages introduced with v3.5.
 
<pre>
 
apt-get update
 
apt-get install linux-headers-3.8.0-8 linux-headers-3.8.0-8-quantastor linux-image-3.8.0-8-quantastor
 
apt-get install krb5-config krb5-user samba qstortarget qstorservice qstormanager qstortomcat
 
</pre>
 
 
At this point you must reboot the system and you'll be running QuantaStor v3 with the v3.8 kernel.
 

Revision as of 12:35, 12 February 2016

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 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