Introduction
This document describes how to upload portions of the eXtensible Markup Language (XML) configuration file into the Email Security Appliance (ESA).
Prerequisites
Requirements
Cisco recommends that you have knowledge of these topics:
- eXtensible Markup Language (XML)
- Email Security Appliance (ESA)
Components Used
This document is not restricted to specific software or hardware versions.
The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.
Note: This document assumes that the configuration to upload is from the same AsyncOS version.
Configure
Overview
The ESA allows you to import a configuration file obtained from any point in time or any other ESA.
ESA FAQ: How do you import a configuration file into a new appliance?
You can encounter scenarios on which it is more convenient to import only portions of the configuration, instead of an entire configuration file.
- Recreations
- Feature tests
- Adding a large number of entries at once to specific settings
Background Information
You can load information in one of three methods:
- Place information in the configuration directory and upload it.
- Upload the configuration file directly from your local machine.
- Paste configuration information directly.
Regardless of the method, you must include these tags at the top of your configuration:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE config SYSTEM "config.dtd">
<config>
... your configuration information in valid XML
</config>
The closing </config> tag should follow your configuration information. The values in XML syntax are parsed and validated against the DTD located in the configuration directory on your Cisco Content Security Appliance. The DTD file is named config.dtd. If validation errors are reported at the command line when you use the loadconfig command, the changes are not loaded. You can download the DTD to validate configuration files outside of the appliance before uploading them.
Configuration
In order to import a subsection of the configuration file, the subsection is required to be complete and unique and must contain the declarations tags above, as well as being within <config></config>.
Complete means that the entire start and end tags for a given subsection as defined by the DTD are included. For example, uploading or pasting the following code causes validation errors:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE config SYSTEM "config.dtd">
<config>
<autosupport_enabled>0</autosu
</config>
However, upload or paste this code, it does not cause validation errors:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE config SYSTEM "config.dtd">
<config>
<autosupport_enabled>0</autosupport_enabled>
</config>
Unique means that the subsection of the configuration file being uploaded or pasted is not ambiguous for the configuration. For example, a system can have only one hostname, so upload this code (including the declarations and <config></config> tags) is allowed:
<hostname>mail4.example.com</hostname>
However, a system can have multiple listeners defined, each with different Recipient Access Tables defined, so upload only this code is considered ambiguous:
<rat>
<rat_entry>
<rat_address>ALL</rat_address>
<access>RELAY</access>
</rat_entry>
</rat>
Because it is ambiguous, it is not allowed, even though it is complete syntax.
Caution: When uploading or pasting a configuration file or subsections of a configuration file, you have the potential to erase uncommitted changes that may be pending.
Empty Versus Omitted Tags
Use caution when uploading or pasting sections of configuration files. If you do not include a tag, then its value in the configuration is not modified when you load a configuration file. However, if you include an empty tag, then its configuration setting is cleared.
For example, uploading the following code removes all listeners from the system:
<listeners></listeners>
Caution: When uploading or pasting subsections of a configuration file, you can disconnect yourself from the GUI or CLI and destroy large amounts of configuration data. Do not disable services with this command if you are not able to reconnect to the appliance using another protocol, the Serial interface, or the default settings on the Management port. Also, do not use this command if you are unsure of the exact configuration syntax as defined by the DTD. Always back up the configuration data before loading a new configuration file.
Note About Character Set Encoding
The encoding attribute of the XML configuration file must be “ISO-8859-1” regardless of the character set you may be used to manipulate the file offline. The encoding attribute is specified in the file whenever you issue the showconfig, saveconfig, or mailconfig command:
<?xml version="1.0" encoding="ISO-8859-1"?>
Verify
Navigate to the page of the modified feature or setting.
Related Information