Script Engine Configuration and Reference

Introduction

The Eyeglass Script Engine lets you run custom scripts before, during, or after a failover to automate tasks that fall outside of what Eyeglass manages directly on the PowerScale OneFS clusters — for example, remounting NFS exports on client hosts, starting or stopping applications, or calling APIs on third-party equipment such as load balancers.

Several other DR articles reference the Script Engine for specific scenarios, including Choosing a Failover Type and Failover Planning. This article is the configuration and reference guide for the feature itself.

Typical Script Use Cases

Many failover scenarios depend on steps performed on devices, software, and infrastructure external to the NAS cluster. The Script Engine automates these tasks and captures their output in the Eyeglass failover log. Common use cases include:

• NFS host mount and remount automation.
• Application shutdown and startup logic around a failover.
• Sending alerts or emails outside of the standard Eyeglass alarm channel.
• Running API commands on third-party equipment (load balancer, switch, router, or firewall).
• IP load-balancing and storage-layer failover coordination for web-tier and storage-tier dependencies.

Script Engine Overview

The Script Engine is available as an icon on the Eyeglass Web UI desktop and provides:

• A script library to save, create, edit, and delete scripts.
• The ability to activate or deactivate scripts per failover type.
• A test mode that simulates a failover scenario to validate script logic before enabling it for a real failover.
• Support for Bash, Node.js, and Python.
• Run-time variables that expose failover metadata to a script, so a single script can handle multiple policies or Access Zones.

Scripts can run in one of three modes:

Mode	When it runs	Typical use
Pre-failover	Before failover steps begin	Shut down applications, unmount file systems
Unified	Runs for both failover and failback, and uses run-time variables to determine which occurred	Single script handling both directions
Post-failover	After the target cluster is writable	Unmount/remount or mount-only logic, application startup

Script Engine Admin Procedures

1. In the script library, add a new script or select an existing one to edit. Numbered lines make debugging easier.
2. Use Test to run the script against a simulated failover. You must select a failover type and a SyncIQ policy — the policy is not actually failed over, but its metadata is passed into the script the same way it would be during a real failover.
3. Decide whether the script is pre-failover, unified, or post-failover, and save it to the corresponding location so it executes at the correct point in the failover sequence.
4. Enable or disable the script for each failover type (Policy, Access Zone, IP Pool, DFS) as required.

warning

All enabled scripts run for every failover that uses the selected failover type. Script logic must account for which policy or Access Zone triggered the failover — Eyeglass does not scope a script to a single policy automatically.

Config Variables

The failover script timeout defaults to 300 seconds and can be changed using the Eyeglass CLI.

Script Run-Time Variables

Scripts receive the following environment variables so a single script can handle multiple failover scenarios:

Variable	Description
SOURCE	Metadata for the source cluster of the SyncIQ policy.
TARGET	Metadata for the target cluster of the SyncIQ policy.
POLICY_DATA	Metadata about the SyncIQ policy being failed over.
FAILOVER_TYPE	SYNCIQ, DFS, or ACCESSZONE.
ZONE_DATA	Access Zone metadata, including SmartConnect zone names and aliases, useful for DNS-related post-failover logic.
FAILOVER_RAN	true/false — whether failover steps have completed. Valid only in a post-failover script.
FAILOVER_STATUS	OK, WARNING, or ERROR — lets script logic branch based on whether failover completed cleanly. Valid only in a post-failover script.
FAILOVER_SUCCESS	true/false — simplified success/failure flag, useful to skip application startup logic on a failed failover. Valid only in a post-failover script.

Sample Execution Rules

• Scripts run after all Eyeglass automation steps complete.
• More than one script can be enabled per failover type; enabled scripts for the same type run in series.
• A script should return exit code 0 for success. Any code greater than 0 is treated as an error and fails the overall failover job status.
• Return codes and all script output (use echo/print/console.log liberally) are captured in the failover log for troubleshooting.
• Scripts are independent — there is no mechanism for one script's return code to control whether a second script runs. If conditional logic across tasks is required, combine that logic into a single script.
• Superna recommends separating concerns into discrete scripts: one for host-side remount automation, one for DNS automation, one for application-specific logic.

Configuring Remote Execution to Hosts

A common pattern is to run a script locally on Eyeglass that connects out via SSH to a remote host to complete a failover-related task (for example, unmounting and remounting an NFS export). Scripts run as the sca user on the Eyeglass appliance.

SSH Passwordless Login to Remote Linux Hosts

1. SSH to the Eyeglass appliance and elevate to root (sudo -s).

2. Change to the sca user's home directory: cd /opt/superna.

3. Generate an SSH key pair without a passphrase: ssh-keygen -t rsa, using the path /opt/superna/.ssh/id_rsa.

4. Set ownership on the generated key files so they are usable by the sca user:

   cd /opt/superna/.ssh
   chown sca *
   chgrp users *

5. Switch to the sca user (su sca) and connect once to the remote host (ssh user@remotehost) to accept its host key and create known_hosts.

6. Exit back to root, and create the .ssh directory on the remote host if it does not already exist:

   ssh user@remotehost mkdir -p .ssh

7. Copy the Eyeglass public key into the remote user's authorized keys:

   cat /opt/superna/.ssh/id_rsa.pub | ssh user@remotehost 'cat >> .ssh/authorized_keys'

8. As the sca user, confirm passwordless login now works: su sca then ssh user@remotehost — no password prompt indicates success.

Enabling SSH on a Windows Server for Remote PowerShell Execution

Tested on Windows Server 2012 R2. This allows the Script Engine to run PowerShell commands remotely over SSH against a Windows host.

1. From an elevated PowerShell prompt on the Windows server, set the security protocol to TLS 1.2 and download the OpenSSH for Windows release:

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Invoke-WebRequest -Uri "https://github.com/PowerShell/Win32-OpenSSH/releases/download/v7.7.2.0p1-Beta/OpenSSH-Win64.zip" -OutFile "powershell.zip"

2. Extract the archive (older Windows builds lack Expand-Archive, so use .NET directly) and install the service:

   Add-Type -assembly "system.io.compression.filesystem"
   [io.compression.zipfile]::ExtractToDirectory('C:\myfolder\powershell.zip','C:\myfolder')
   cd .\OpenSSH-Win64
   .\install-sshd.ps1

3. Start and, optionally, set the services to start automatically:

   Start-Service sshd
   Start-Service ssh-agent
   Set-Service -Name sshd -StartupType "Automatic"
   Set-Service -Name ssh-agent -StartupType "Automatic"

4. Open the firewall port for SSH if required:

   netsh advfirewall firewall add rule name=SSHPort dir=in action=allow protocol=TCP localport=22

5. From the Eyeglass appliance, confirm the connection: ssh <user>@<windows-server-ip>, then run a PowerShell command such as powershell.exe get-content env:computername to validate remote execution.

Keyless SSH Login for Script Engine to Windows/PowerShell

Follow the same key-generation and authorized_keys copy pattern described above for Linux hosts — generate the key pair as the sca user under /opt/superna/.ssh, then copy the contents of id_rsa.pub into the Windows host's .ssh/authorized_keys file — to allow the Script Engine to execute PowerShell commands on the Windows host without a password prompt.

Example Scripts

Access Zone Remount Script (Bash, Remote Execution over SSH)

This example targets Access Zone failovers where the SmartConnect Zone name is preserved across failover, so the same unmount/remount logic applies to both failover and failback.

Remote host script (for example remount.sh, placed in the home directory of the SSH automation user on the remote host):

#remount script
echo "remounting filesystem post failover"
umount -fl /mnt/data
mount -a
mount | grep "/mnt/data"

Eyeglass-side post-failover script that checks ZONE_DATA for the Access Zone name before remotely invoking the remount script:

#!/bin/bash
# Purpose: unmount/remount fstab-persisted mounts post failover; depends on a
# remote script on the target host to perform the actual remount.
echo starting unmount remount remotely called script on remote hosts
echo source-cluster: $SOURCE
echo zone data: $ZONE_DATA

if (echo "$ZONE_DATA" | grep -q '"source":{"name":"data"'); then
   echo found zonename
   # Requires SSH key-based auth configured per the steps above
   rc=$(ssh root@linux ./remount.sh)
   echo result of host script was: $rc
else
   echo did not find zonename to process
fi

tip

Use the Script Engine Test function against your real clusters and Access Zones first, to confirm the exact ZONE_DATA string to grep for before enabling a script like this for production failovers.

Bash Example — Printing Run-Time Variables

#!/bin/bash
echo these are the environment variables
echo source: $SOURCE
echo target: $TARGET
echo failover type: $FAILOVER_TYPE
echo zone data: $ZONE_DATA
echo policy data: $POLICY_DATA

Python Example — Printing Run-Time Variables

#!/usr/bin/env python
import os
print(os.environ['SOURCE'])
print(os.environ['TARGET'])
print(os.environ['FAILOVER_TYPE'])
print(os.environ['ZONE_DATA'])
print(os.environ['POLICY_DATA'])

Node.js Example — Printing Run-Time Variables

#!/usr/bin/env node
console.log("source", process.env.SOURCE);
console.log("target", process.env.TARGET);
console.log("type", process.env.FAILOVER_TYPE);
console.log("zone data", process.env.ZONE_DATA);
console.log("policy data", process.env.POLICY_DATA);

note

Node.js support is not installed by default on the appliance. It can be added over SSH as root using zypper install npm (requires internet access from the appliance). Bash and Python are pre-installed.

Automating with the REST API and CURL

Failovers can also be triggered from external automation (for example VMware SRM, a script, or a web page) using the Eyeglass REST API, which runs any enabled Script Engine logic at the end of the failover just as a UI-initiated failover would. See the API Guide for endpoint details.

If you are scripting against the API with curl directly:

• Add -k to skip certificate validation, since the Eyeglass API uses a self-signed certificate by default.
• Add -d "" to avoid a 411 (missing content-length) response on requests with no body.