Automate or Script a Configuration File Backup of an ESA in Cluster

Introduction

This document describes how to use batch commands in order to save a configuration from an appliance in cluster on the Cisco Email Security Appliance (ESA). This can be used on all versions of AsyncOS for ESA.

Prior to AsyncOS Version 8.5, clustered appliances could not save a usable configuration to be used to restore a configuration on to a Cisco ESA. In order to get a usable configuration from the appliance, you had to remove the appliance from cluster and save the configuration as a standalone appliance.

Prerequisites

Note: This article is a proof-of-concept and provided as an example basis. While these steps have been successfully tested, this article is intended primarily for demonstration and illustration purposes. Custom scripts are outside of the scope and supportability of Cisco. The Cisco Technical Assistance Center will not write, update, or troubleshoot custom external scripts at any time.  Before you attempt and construct any scripts, ensure that you have scripting knowledge when you construct the final script.

Gather this information from the ESAs in cluster:

• IP addresses and/or hostname
• Cluster name
• Cluster group name (if applicable)

Consult the CLI Reference Guide for your version of AsyncOS for Email Security, as there are CLI batch changes that depend on the revision your ESA runs.

Read and understand these TechNotes:

• How Can I Automate or Script Configuration File Backups?
• How to configure SSH Public Key Authentication for login to the ESA without a password

Automate or Script a Configuration File Backup of an Appliance in Cluster

For AsyncOS versions earlier than Version 8.5, when you attempt to save the configuration while in cluster with the saveconfig or mailconfig command, the ESA generates this warning:

WARNING: Clustered machines do not support loadconfig. Your configuration file has
 complete  data for the entire cluster, but cannot be used to restore a configuration.

[an error occurred while processing this directive]

In AsyncOS Version 8.5 and later, saved configurations now contain both the machine-level configuration and cluster configuration. This is covered in detail from the Version 8.5 and later User Guide. Refer to the End-User Guides for full detail.

There is no need to back up the configuration for each appliance in a cluster. However, there could be multiple clusters in a network, with multiple groups configured for each cluster. It is quite difficult to remove every appliance from the cluster, and then save the configuration and rejoin the cluster again manually.

These commands can be used if you log into the ESA, remove the ESA from cluster, save or mail the configuration, and then rejoin the cluster again.

In order to begin, it is important to know the machine name and serial number of the ESAs in cluster and the group name. This can be obtained if you enter clusterconfig list on the CLI:

(Cluster ESA1_ESA2)> clusterconfig list

Cluster esaA_esaB
=====================
 Group Main_Group:
 Machine ESA1.local (Serial #: 0000E878109A-G091111) 
 Machine ESA2.local (Serial #: 0000E878525D-9091111)

[an error occurred while processing this directive]

In order to remove the appliance from cluster, use the clusterconfig removemachine <appliance name> command:

(Cluster ESA1_ESA2)> clusterconfig removemachine ESA1.local

Please wait, this operation may take a minute...
Machine ESA1.local removed from the cluster.

[an error occurred while processing this directive]

With the saveconfig command, save the configuration onto the appliance with passwords. As noted, "Files with masked passwords cannot be loaded using loadconfig command." So, be sure to enter N when prompted:

ESA1.local> saveconfig

Do you want to mask the password? Files with masked passwords cannot be loaded
using loadconfig command. [Y]> n

File written on machine "esaA.local" to the location
"/configuration/C100V-0000E878109A-G091111-20140909T184724.xml".
Configuration saved. 

[an error occurred while processing this directive]

Alternatively, use mailconfig in order to email the configuration to a valid email recipient. As noted, "Files with masked passwords cannot be loaded using loadconfig command." So, be sure to enter N when prompted:

ESA1.local> mailconfig

Please enter the email address to which you want to send the configuration file.
Separate multiple addresses with commas.
[]> joe@example.com

Do you want to mask the password? Files with masked passwords cannot be loaded
using loadconfig command. [Y]> n

The configuration file has been sent to joe@example.com.

[an error occurred while processing this directive]

Finally, use the clusterconfig batch command in order to join the appliance back to the cluster:

clusterconfig join [--port=xx] <ip_of_remote_cluster> <admin_username>
<admin_password> <groupname>

[an error occurred while processing this directive]

In order to continue with the previous example, this would be executed in this command:

esaA.local> clusterconfig join --port=22 172.16.6.161 admin ironport Main_Group

Joining a cluster takes effect immediately, there is no need to commit.
(Cluster ESA1_ESA2)>

[an error occurred while processing this directive]

You will notice the automatic change of the command prompt to the cluster-level name, as noted in the previous example as "Cluster ESA1_ESA2)".

Advanced Automated or Scripted Configuration File Backups

From an external host (UNIX/Linux/OSX), you can use the previous commands in order to script the process.

Here is an example of the entire process written into script, with the assumption that cluster runs over Secure Shell (SSH), port 22:

#! /bin/bash
#
# Script to save the ESA config, then copy locally via SCP. This is assuming you 
wish to
# have the cluster in SSH via port 22. This script has been written and tested against
# AsyncOS 9.0.0-390 (01/15/2014).
#
# *NOTE* This script is a proof-of-concept and provided as an example basis. While
these steps have 
# been successfully tested, this script is for demonstration and illustration purposes. 
Custom 
# scripts are outside of the scope and supportability of Cisco. Cisco Technical 
Assistance will 
# not write, update, or troubleshoot custom external scripts at any time.
#
# <SCRIPT>
#
# $HOSTNAME & $HOSTNAME2 can be either the FQDN or IP address of the ESAs in cluster.
#
HOSTNAME= [IP/HOSTNAME ESA1]
HOSTNAME2= [IP/HOSTNAME ESA2]
#
# $MACHINENAME is the local name for ESA1.
# 
MACHINENAME= [MACHINENAME AS LISTED FROM 'clusterconfig list']
#
# $USERNAME assumes that you have preconfigured SSH key from this host to your ESA.
# http://www.cisco.com/c/en/us/support/docs/security/email-security-appliance/
118305-technote-esa-00.html
#
USERNAME=admin
#
# $BACKUP_PATH is the directory location on the local system.
#
BACKUP_PATH= [/local/path/as/desired]
#
# Following will remove ESA1 from cluster in order to backup standalone config.
# "2> /dev/null" at the end of string will quiet any additional output of the 
clustermode command.
#
echo "|=== PHASE 1 ===| REMOVING $MACHINENAME FROM CLUSTER"
ssh $USERNAME@$HOSTNAME "clustermode cluster; clusterconfig removemachine 
$MACHINENAME" 2> /dev/null
#
# $FILENAME contains the actual script that calls the ESA, issues the 'saveconfig' 
command.
# The rest of the string is the cleanup action to reflect only the <model>-
<serial number>-<timestamp>.xml.
#
echo "|=== PHASE 2 ===| BACKUP CONFIGURATION ON ESA"
FILENAME=`ssh -q $USERNAME@$HOSTNAME "saveconfig y 1" | grep xml | sed -e 
's/\/configuration\///g' | sed 's/\.$//g' | tr -d "\""`
#
# The 'scp' command will secure copy the $FILENAME from the ESA to specified 
backup path, as entered above.
# The -q option for 'scp' will disable the copy meter/progress bar.
#
echo "|=== PHASE 3 ===| COPY XML FROM ESA TO LOCAL"
scp -q $USERNAME@$HOSTNAME:/configuration/$FILENAME $BACKUP_PATH
#
# Following will re-add ESA1 back into cluster.
#
echo "|=== PHASE 4 ===| ADDING $MACHINENAME BACK TO CLUSTER"
ssh $USERNAME@$HOSTNAME "clusterconfig join $HOSTNAME2 admin ironport 
Main_Group" 2> /dev/null
#
echo "|=== COMPLETE ===| $FILENAME successfully saved to $BACKUP_PATH"
#
# </SCRIPT>
#

[an error occurred while processing this directive]

Here is an examination of the main commands embedded in the script:

• Remove ESA1 from the cluster:
  
  

  ssh $USERNAME@$HOSTNAME "clustermode cluster; clusterconfig removemachine 
  $MACHINENAME" 2> /dev/null

  [an error occurred while processing this directive]
  
  
• Download standalone configuration file:
  
  

  FILENAME=`ssh -q $USERNAME@$HOSTNAME "saveconfig y 1" | grep xml | sed -e 's/
  \/configuration\///g' | sed 's/\.$//g' | tr -d "\""`

  [an error occurred while processing this directive]
  
  
• Copy the XML from ESA1 to local host:
  
  

  scp -q $USERNAME@$HOSTNAME:/configuration/$FILENAME $BACKUP_PATH

  [an error occurred while processing this directive]
  
  
• Put ESA1 back into the cluster.
  
  

  ssh $USERNAME@$HOSTNAME "clusterconfig join $HOSTNAME2 admin ironport 
  Main_Group" 2> /dev/null

  [an error occurred while processing this directive]

A complete example of the script in action should result in this:

my_host$ ./cluster_backup 
|=== PHASE 1 ===| REMOVING ESA1.local FROM CLUSTER
Please wait, this operation may take a minute...
Machine ESA1.local removed from the cluster.
|=== PHASE 2 ===| BACKUP CONFIGURATION ON ESA
|=== PHASE 3 ===| COPY XML FROM ESA TO LOCAL
|=== PHASE 4 ===| ADDING ESA1.local BACK TO CLUSTER
Joining a cluster takes effect immediately, there is no need to commit.
|=== COMPLETE ===| C100V-0000E878109A-G091111-20150116T192955.xml successfully 
saved to /Users/saved_esa_configurations/

[an error occurred while processing this directive]

Related Information

• Cisco Email Security Appliance - End-User Guides
• Technical Support & Documentation - Cisco Systems