Resetting/Clearing a Gateway

Blog Post created by kazvi01 Employee on Nov 22, 2017

When I talk about the lifecycle of gateway policies and services one of the things I'm trying to really push is to always start from scratch when deploying updated policies and services to gateways. In the ideal case this means bringing up a new gateway, applying the environment configuration and updated policies and services to that gateway. Then switching your load balancer to point to your new gateway and tearing down your old one.

However, setting up a new gateway everytime policy and service updates need to be deployed requires infrastructure and processes to be setup. Another approach to get you close to "starting from scratch" when deploying updates would be to clear or reset your Gateways using a script.


You can use the following script to delete all encapsulated assertions, policies, services and folders from a gateway. 

Disclaimer: I make no guarantees on this script, use at your own risk. All credit goes to Jay MacDonald


# This is a script that will attempt to clear all encapsulated assertions, policies, services and folders
# It takes a single parameter, the location of the connection properties file. For example this is a
# connection properties file (you don't need all those properties though):
#               host=localhost
#               port=8443
#               restman=restman
#               username=admin
#               password=RaMOzHRnr2Y.Tjo_p0l0Zo28a_c9UFfB4w
#               encryptionPassphrase=HtdJaeXIZOI.zadhEbg7Y0QTyKp4RTRDfA
# Determine the password and encryptionPassphrase values using 'GatewayMigrationUtility.sh encodePassword' command.
# The script should be placed in the same folder as the GatewayMigrationUtility.sh file. It only works on linux (or cygwin).
# It will create a directory with the files needed to restore the gateway to its previous state

function check_OK() {
     if [ -z "$2" ] ; then

     if [ -z "$3" ] ; then

     if [ $1 -eq 0 ] ; then
          echo "$OK"
          echo "$FAIL"
          exit 1

if [ -z "$1" ]; then
    echo "Need to specify a connection properties file containing the connection properties of the gateway to connect to."
    exit 1
elif [ ! -e "$1" ]; then
    echo "Connection properties file does not exist: $1"
    exit 1   
elif [ ! -r "$1" ]; then
    echo "Cannot read file connection properties file $1"
    exit 1

. $1     # load in the connection variables

DATE=$(date +%Y%m%d%H%M%S)
scriptDir=$(dirname $0)

# Create the working directory
echo -n "==> Creating working directory ($workingDir): "
mkdir -p $workingDir
check_OK $?

# Export out the current full gateway
echo "==> Exporting $host to $workingFile:"
$GMU migrateOut --trustCertificate --trustHostname -z $hostProperties --all -d $workingFile --format singleFile
check_OK $? '===> OK' '===> FAIL'

echo -n "==> Copying $workingFile to $restoreFile: "
cp $workingFile $restoreFile
check_OK $?

# Number the start line of the mappings section
echo -n "==> Determining starting line of mapping section: "
mappingStart=$((`grep -n "<l7:Mappings>" $workingFile | tail -n 1 | cut -f1 -d:`+1))
check_OK $? $mappingStart

# Get the total lines in the file
echo -n "==> Determining total lines: "
totalLines=$((`cat $workingFile | wc -l`))
check_OK $? $totalLines

# Reverse mappings and remove ignored mappings
echo -n "==> Reversing mappings: "
reverseMappings=$(cat $workingFile | tail -n+$mappingStart | head -n-2 |
    awk '   BEGIN {ignore=1; reverseMappings=""} 
            /<l7:Mapping.*action=\"Ignore\".*\/>/ { next }
            /<l7:Mapping.*\/>/ { reverseMappings=$0 "\n" reverseMappings; next }
            /<\/l7:Mapping>/ { if ( ignore == 1) { reverseMappings=mapping "\n" $0 "\n" reverseMappings; } mapping=""; ignore=1; next }
            /.*action=\"Ignore\".*/ {ignore=0; next}
            /.*/ {mapping=mapping "\n" $0}
            END { print reverseMappings}')
check_OK $?

# Delete the original mappings
echo -n "==> Deleting original mappings from $workingFile: "
sed -i -e "${mappingStart},${totalLines}d" $workingFile
check_OK $?

# Replace the original mappings with the reversed mappings
echo -n "==> Appending reversed mappings to $workingFile: "
echo $reverseMappings >> $workingFile
check_OK $?

# Add the line file ending
echo -n "==> Appending closing XML to $workingFile: "
echo "</l7:Mappings></l7:Bundle>" >> $workingFile
check_OK $?

# Change all actions to Ignore
echo -n "==> Changing all actions to Ignore in $workingFile: "
sed -i -e "s/action=\"NewOrExisting\"/action=\"Ignore\"/g" $workingFile
sed -i -e "s/action=\"NewOrUpdate\"/action=\"Ignore\"/g" $workingFile
check_OK $?

# Delete the encapsulated assertions
echo -n "==> Remapping to delete encapsulated assertions: "
$GMU manageMappings -b $workingFile -f $mappingsOverride -t ENCAPSULATED_ASSERTION -a Delete > /dev/null
check_OK $?

# Delete the policies
echo -n "==> Remapping to delete policies: "
$GMU manageMappings -b $workingFile -f $mappingsOverride -t POLICY -a Delete > /dev/null
check_OK $?

# Delete the services
echo -n "==> Remapping to delete services: "
$GMU manageMappings -b $workingFile -f $mappingsOverride -t SERVICE -a Delete > /dev/null
check_OK $?

# Delete the folders
echo -n "==> Remapping to delete folders: "
$GMU manageMappings -b $workingFile -f $mappingsOverride -t FOLDER -a Delete > /dev/null
check_OK $?

# Ignore the root folder
echo -n "==> Remapping to ignore root folder: "
$GMU manageMappings -b $workingFile -f $mappingsOverride -t FOLDER -a Ignore -i 0000000000000000ffffffffffffec76 > /dev/null
check_OK $?

# Import the bundle to delete encapsulated assertions, policies, services and folders
echo "==> Importing bundle to delete encapsulated assertions, policies, services and folders:"
$GMU migrateIn --trustCertificate --trustHostname -z $hostProperties -b $workingFile -r $deleteResultsFile --map $mappingsOverride
check_OK $? '===> OK' '===> FAIL'

echo ""
echo "Note: You can immediately restore the exported gateway using the following command:"
echo ""
echo "# $GMU migrateIn --trustCertificate --trustHostname -z $hostProperties -b $restoreFile -r $restoreResultsFile"


Using the Script

This script would be used in this general process:

  1. Start with a bundle needed to be imported to a Gateway. It should contain all service, policies and encapsulated assertions required on the Gateway.
    • Preferably this bundle comes from an artifact repository but it can also come from a recent migrate out of a source Gateway. Using an artifact repository is preferable since it allows you to roll back to previous versions.
  2. Run the above clear/reset script on the target gateway. This removes all service, policies and encapsulated assertions. But leaves environment configurations like cluster properties, listen ports, connections, etc...
  3. Import the bundle from step #1 into the target gateway.