QuantaStor Custom Scripting / Application Extensions
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.
/var/opt/osnexus/custom/system-ident-start.sh
Called before the Storage System Beep task is called to identify the chassis of the storage system via audible beep and/or LED blink on the storage server. There are no input args to this script.
/var/opt/osnexus/custom/system-ident-stop.sh
Called after the Storage System Beep task is complete. There are no input args to this script.
/var/opt/osnexus/custom/security-message-update.sh
Called with argument --message="SYSTEMUSE" where SYSTEMUSE is the system use notification message set in the Security Manager dialog. This enables one to set the system wide system use / security-classification message in other areas such as in 99-class-banner for gnome-shell extensions.
Network Interface Custom Scripts
Scripts related to the starting of network interfaces/ports.
/var/opt/osnexus/custom/port-prestart.sh
Called before the network port is started (eg ifup) with the --name= argument providing the port name.
/var/opt/osnexus/custom/port-poststart.sh
Called after the network port is started (eg ifup) with the --name= argument providing the port name.
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.
Storage Pool Scrub / Bit-rot Detection & Correction Scripts
/var/opt/osnexus/custom/poolscrub-prestart.sh
Called just before a storage pool scrub is started. Arguments are --name= and --id= which have the Storage Pool name and UUID respectively.
/var/opt/osnexus/custom/poolscrub-poststart.sh
Called just after a storage pool scrub is started. Arguments are --name= and --id= which have the Storage Pool name and UUID respectively.
Common arguments to the network share scripts:
- --share-path=SHAREPATH
Full path to where the share is located.
- --share-name=SHARENAME
Name of the share.
- --share-id=SHAREUUID
UUID of the share in the QuantaStor grid database.
- --pool=POOLUUID
UUID of the storage pool in the QuantaStor grid database.
Called just after a new Network Share has been created. This can be used to customize the share permissions and extended attributes with defaults.
Called just after a new Network Share has been modified. This can be used to customize the share permissions and extended attributes with defaults.
Software Adapter Custom Scripts
QuantaStor has a built-in software adapter feature for connecting to other systems via iSCSI and NVMe-oF (TCP and RDMA). These scripts get called pre and post connection to the storage in case any additional operations need to be orchestrated at the same time.
/var/opt/osnexus/custom/swadapter-preconnect.sh
Called before connecting to the target devices. This script is called with arguments indicating the adapter that is connecting and the IP address of the remote SAN or NVMeoF appliance it is connecting to.
Arguments:
- --adapter=ADAPTERNAME
- --id=ADAPTERUUID
- --ip-address=IPADDRESS
/var/opt/osnexus/custom/swadapter-postconnect.sh
Called after connecting to the target devices. This script is called with arguments indicating the adapter that is connecting and the IP address of the remote SAN or NVMeoF appliance it is connecting to.
Arguments:
- --adapter=ADAPTERNAME
- --id=ADAPTERUUID
- --ip-address=IPADDRESS
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.
Example bash scripts
Below are some simple sample bash scripts that you can use to get started.
Custom Scripts requiring POOLID
#!/usr/bin/env bash
while [ $# -gt 0 ]; do
case "$1" in
--pool*|-p*)
if [[ "$1" != *=* ]]; then shift; fi # Value is next arg if no `=`
POOLID="${1#*=}"
;;
--help|-h)
printf "# Help message\n"
printf "--pool or -p # Pass in pool id.\n"
printf "*******************************\n"
exit 0
exit 0
;;
*)
>&2 printf "Error: Invalid argument\n"
exit 1
;;
esac
shift
done
# print out POOLID variable for script testing
echo "pool-id: $POOLID"
## execute other custom scripting
## exit cleanly when done
exit 0
Custom Scripts requiring SCHEDULE_NAME or SCHEDULE_ID
#!/usr/bin/env bash
while [ $# -gt 0 ]; do
case "$1" in
--name*)
if [[ "$1" != *=* ]]; then shift; fi
SCHEDULE_NAME="${1#*=}"
;;
--id*|--schedule*)
if [[ "$1" != *=* ]]; then shift; fi
SCHEDULE_ID="${1#*=}"
;;
--help|-h)
printf "# Help message\n"
printf "--name # Pass in schedule name.\n"
printf "--id or --schedule # Pass in schedule id.\n"
printf "*******************************\n"
exit 0
;;
*)
>&2 printf "Error: Invalid argument\n"
exit 1
;;
esac
shift
done
# print out SCHEDULE_ID and SCHEDULE_NAME variables for script testing
echo "name: $SCHEDULE_NAME"
echo "schedule: $SCHEDULE_ID"
echo "id: $SCHEDULE_ID"
## execute other custom scripting
## exit cleanly when done
exit 0