QuantaStor Custom Scripting / Application Extensions

From OSNEXUS Online Documentation Site
Jump to: navigation, search


Custom Scripting / Application Extensions

QuantaStor has script call-outs which you can use to extend the functionality of the system for integration with custom applications. For example, you may have an application which needs to be notified before or after a storage pool starts or stops. Or you may have need to call a script before an automated snapshot policy starts in order to quiesce applications.

Note: The QuantaStor process that runs these custom scripts has a timeout value of 300 Seconds to ensure that the process can continue and not pause for an unexpected amount of time. If your scripts when implemented take longer than 300 seconds, please review them and take steps to reduce their execution time.

Security Issues

Scripts are called from the root user account so it's important to use caution when adding custom call-out scripts to QuantaStor systems. All call-out scripts must be installed to the /var/opt/osnexus/custom directory. By default the scripts directory has permissions '755'. Scripts must be configured with file permissions using the command 'chmod 755 scriptname.sh' to prevent non-root user accounts from modifying the scripts. Additionally, if you have sensitive information like a plain text password in your custom script be sure to set the permissions to 700 rather than 755 so only the root user account can read the script.

Timeouts

Scripts must complete within 5 minutes; scripts taking longer are automatically terminated unless the script has the -async suffix. For example:

  • this version runs synchronously, must complete in 5 minutes: /var/opt/osnexus/custom/system-poststart.sh
  • this version runs async, can run for as long as required: /var/opt/osnexus/custom/system-poststart-async.sh

Where to install custom scripts

Custom script call-outs are hard-wired to specific file names and must be placed in the custom scripts directory '/var/opt/osnexus/custom' within your QuantaStor System . If you have a grid of systems you'll need to install your script onto all of the systems.

Custom Scripts Directory:

/var/opt/osnexus/custom

Storage System Custom Scripts

Scripts related to the startup / shutdown of the system.

/var/opt/osnexus/custom/system-poststart.sh

The system poststart script is only called one time when the system boots up. If the management services are restarted it will check against the timestamp in /var/opt/osnexus/quantastor/qs_lastreboot an only call the system-poststart.sh script if it has changed. If you want your poststart script to run every time the management service is restarted you can just delete the qs_lastreboot file in your script.

/var/opt/osnexus/custom/system-prestop.sh

Called when the user initiates a shutdown or a restart via the web management interface (or CLI). Note that if the admin bypasses the normal shutdown procedure and restarts the system at the console using 'reboot' or 'shutdown -P now' or similar command your script won't get called.

Storage Pool HA Failover Custom Scripts

These scripts make it possible to add custom scripting to the HA failover process for ZFS based storage pools.

Command Arguments:

--pool=POOLUUID

/var/opt/osnexus/custom/pool-prefailover.sh

This is called after the before the failover starts --pool arg containing the UUID of the pool which is being operated on.

/var/opt/osnexus/custom/pool-postfailover.sh

This is called after the failover completes (successfully or not) with the --pool arg containing the UUID of the pool which is being operated on.

Storage Pool Custom Scripts

If you have custom applications running within the system which need to attach/detach from the pool or specific directories within a given storage pool these scripts may be helpful to you.

Command Arguments:

--pool=POOLUUID

/var/opt/osnexus/custom/pool-poststart.sh

Called just after a storage pool is started. The UUID of the pool is provided as an input arguement to the script as '--pool=<POOLUUID>'. You can use 'qs pool-get <POOLUUID> --server=localhost,admin,password --xml' to get more detail about the storage pool from within your script. The --xml flag is optional, and you'll need to provide the correct admin password.

/var/opt/osnexus/custom/pool-prestop.sh

Called just before the pool is stopped.

/var/opt/osnexus/custom/pool-preexport.sh

Called before a pool is exported.

/var/opt/osnexus/custom/pool-postexport.sh

Called just after a storage pool is exported.

Snapshot & Replication Schedule Custom Scripts

These scripts provide a mechanism for administrators to customize the Remote Replication and Snapshot Schedule features available with QuantaStor with custom scripting which is invoked at various stages of the process. Starting with QuantaStor 4.0.3 additional functionality has been added to the scheduling features for remote replication and snapshots to take all of the snapshots for Network Shares and Storage Volumes at the same time in order to provide a consistent point-in-time view. We refer to the group of snapshots as a consistency group. Consistency groups are generally accurate to within 1 second across all devices in the Snapshot Schedule / Replication Schedule. For releases Prior to 4.0.3, there was no consistency group and snapshots were taken serially which creates problems for OLTP and other workloads.

/var/opt/osnexus/custom/schedule-prestart.sh

Command Arguments:

--name=SCHEDULE_NAME --id=SCHEDULE_ID

This script is called just before a snapshot or replication schedule is triggered / executed. This can provide functionality to begin a freeze of your database or application datastore or provide any other customization that your team may require related to the start of a replication or snapshot schedule.

/var/opt/osnexus/custom/schedule-presnap.sh

Command Arguments:

--name=SCHEDULE_NAME --id=SCHEDULE_ID

This script is called just before snapshots are taken in a snapshot or replication schedule. If you have multiple Storage Volumes and/or Network Shares in the Schedule, QuantaStor will do all prep work related to metadata and QuantaStor Management Objects structures for the Shares/Volumes in the schedule, then trigger your script and finally trigger the snapshots of the Network Shares or Storage Volumes as a group. This schedule-presnap.sh script can provide functionality to begin a 'freeze' of your database or application datastore or provide any other customization that your team may require for snapshotting of your data.

/var/opt/osnexus/custom/schedule-postsnap.sh

Command Arguments:

--name=SCHEDULE_NAME --id=SCHEDULE_ID

This script is called just after snapshots are taken in a snapshot or replication schedule. If you have multiple Storage Volumes and/or Network Shares in the Schedule, QuantaStor will execute this script just after the snapshots have been taken for the schedule. and then perform final task cleanup tasks and/or begin remote replication tasks to transfer the data to a QuantaStor node at a DR site. This schedule-postsnap.sh script can provide functionality to begin a 'thaw' of your database or application datastore or provide any other customization that your team may require for operations after snapshotting of your data has occurred.

/var/opt/osnexus/custom/dr-prefailover.sh

Command Arguments:

--schedule=SCHEDULE_ID

This script is called when the Activate Checkpoints task is started so that any pre DR-failover activities can be run before the checkpoints are activated.

/var/opt/osnexus/custom/dr-postfailover.sh

Command Arguments:

--schedule=SCHEDULE_ID

This script is called when the Activate Checkpoints task is completed so that any post DR-failover activities can be run after the checkpoints are activated.