XML

Three commands interact with XML documents:

dumpXML

dumpXML extracts the complete set of configuration information from a component, and outputs it as an XML document.

mergeXML
matchXML

mergeXML and matchXML parse an XML file that specifies a configuration, compare it with the current configuration of a component, arrange the minimal set of configuration commands that would implement the specified configuration on the component, and interact with the component to configure it accordingly.

Translation

Rendezvous components do not accept or produce XML directly. Instead, methods of the configuration API act as translators:

• dumpXML gets current configuration data from a component, and builds an XML document incorporating that data.
• Conversely, mergeXML and matchXML read an XML document, and build a set of commands to achieve the specified configuration.
Sensitive Information

dumpXML does not extract sensitive information from components—for example, passwords or private keys. Instead, this command replaces sensitive information with a static string.

This replacement is a security feature, but it can also create confusion for unwary users. If you dump an XML document that contains such replacement strings, and modify it to change some of the parameter values, you cannot successfully load those changes (with the mergeXML or matchXML commands) unless you first remove these replacement strings. For example, in the XML document below, remove the indicated text—that is, everything in the security-parameters section.

Removing Security Replacement Strings from XML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rendezvous SYSTEM "http://www.rv.tibco.com/dtd/rv">
<rendezvous url="http://arrakis:7580">
  <configuration timestamp="20040907152842-0700">
    <rvrd-parameters>
      <logging connections="no"
               subject-data="no" subject-interest="no" />
    </rvrd-parameters>
    <security-parameters>
      <administrator password="!!!SECRET!!!" username="Administrator" />
      <certificate index="1" private-key-password="!!! SECRET !!!">
        <use for="HTTPS" />
        <use for="ROUTERS_TO_ROUTERS" />
        <PEM-data>
          -----BEGIN CERTIFICATE-----
MIICvzCCAiigAwIBAgIBATANBgkqhkiG9w0BAQQFADBhMQswCQYDVQQGEwJOQTEL
MAkGA1UECBMCTkExCzAJBgNVBAcTAk5BMRIwEAYDVQQKEwlBbm9ueW1vdXMxEjAQ
BgNVBAsTCUFub255bW91czEQMA4GA1UEAxMHYXJyYWtpczAeFw0wNDAzMzAyMjMy
MzFaFw0wNTAzMzAyMjMyMzFaMGExCzAJBgNVBAYTAk5BMQswCQYDVQQIEwJOQTEL
MAkGA1UEBxMCTkExEjAQBgNVBAoTCUFub255bW91czESMBAGA1UECxMJQW5vbnlt
b3VzMRAwDgYDVQQDEwdhcnJha2lzMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB
gQDAf+fcyb3UdMjPFtaXetSldSGTfrwV9/t+1xUlXaVb79w2jtS6RtNCg9WkzUy2
78DoZxlD3szKoZt7rdZlssCGWSVx2jO568alYF+5r5RR8Dj5I3ZEQC+iFJyCRprn
t/Kh07UKd3fNy8s4KoQBGTxs7C+mQpuNgpSHV5uMSDIF2wIDAQABo4GGMIGDMBEG
CWCGSAGG+EIBAQQEAwICRDALBgNVHQ8EBAMCAuwwEwYDVR0lBAwwCgYIKwYBBQUH
AwEwHQYDVR0OBBYEFL9s9h3DVCx/asG/Bqfka0Z/fLdwMB8GA1UdIwQYMBaAFL9s
9h3DVCx/asG/Bqfka0Z/fLdwMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQAD
gYEAcJQDKbusUaEYOpMD3iNHSKPYQsrfa76DzxA10MGvLtOEh3kpRoeNKUvqZw5+
dQZIxOnQeY8X7l60GKuwvAiOsyUAgDdOWEGnDJed52+R8NXHg/okmdMnzC05QxO0
gJaiC1mm4zl03gFMtHNUqABh9qmjNJDI34bVwXXC2isCgFg=
          -----END CERTIFICATE-----
          !!! SECRET PRIVATE KEY !!!
        </PEM-data>
      </certificate>
      <certificate index="2" />
      <certificate index="3" />
      <certificate index="4" />
    </security-parameters>
  </configuration>
</rendezvous>

After removal, the resulting XML document would look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rendezvous SYSTEM "http://www.rv.tibco.com/dtd/rv">
<rendezvous url="http://arrakis:7580">
 <configuration timestamp="20040907152842-0700">
   <rvrd-parameters>
     <logging connections="no"
              subject-data="no" subject-interest="no" />
   </rvrd-parameters>
   <security-parameters>
   </security-parameters>
 </configuration>
</rendezvous>
DTD

A set of DTD files defines the correct syntax for Rendezvous configuration XML documents. The configuration API verifies XML documents against this definition.

You can easily reconfigure a component by editing the output of dumpXML, and then supplying the modified file to mergeXML or matchXML. The edited document must conform to the DTD.