Editing NAM Console software services XML payload

Applies to NAM 2019+

This topic describes how to edit the software services payload when you use the NAM Console API.

  • How to identify the sections of a software service definition in XML.
  • How to find and edit the XML equivalents of the most common NAM Console settings for software services.
  • How to find and edit other settings in the XML by comparing configurations before and after you make changes in the NAM Console.

Sections of a software service definition in XML

For this example, we used the NAM Console to:

For everything else, we left the default settings for the selected analyzer (HTTP).

The resulting change in the XML configuration file is:

  • A <softwareservice> section was inserted into the XML, including our <name> and <analyzer>.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <softwareservice>
        <name>my software service name</name>
        <analyzer>HTTP</analyzer>
        <probes>
          <probe>5.6.7.8:443</probe>
        </probes>
        <configuration>
          <application>
              <name>my software service name</name>
              <description>my rule description</description>
    
    
  • A <report> subsection with a single <service> that has the <ip> address and <port> number we specified.

        <report>
            <service>
                <ip>1.2.3.4</ip>
                <port>80</port>
            </service>
        </report>
    
    
  • An <analyzer> subsection that specifies the analyzer (<http>) and includes a number of analyzer-specific default settings. We have snipped a number of the settings shown here, but we show all of them later.

        <analyzer>
            <http>
                <nonSyn>false</nonSyn>
                <slowThold>0</slowThold>
                <slowSrvThold>0</slowSrvThold>
    
                [snip]
    
        </analyzer>
    
    
  • A few other settings following the <analyzer> subsection and then the closing </softwareservice> tag to mark the end of this software service definition.

          <packagedElements/>
          <clientGroups>
              <clientIPsource>internal</clientIPsource>
          </clientGroups>
          <sessIdleTmout>0</sessIdleTmout>
          <aggregateSrvPorts>false</aggregateSrvPorts>
        </application>
      </configuration>
    </softwareservice>
    

Putting all the pieces together, including the parts we snipped above, the full software service definition is as follows:

Software service definitions vary depending on the analyzer you select and the options you set, but the above is generally what you need to configure to define a software service.

Common settings

These are some of the most important settings for software service. If you can't find a setting here, see Finding other settings for software services after this table for instructions on how to find other software service settings.

NAM Console page/window NAM Console label XML equivalent
Software Service window Software service name In this example, my software service name is the name of the software service. This is safe to change through the API; it doesn't affect the structure of the XML.
<name>my software service name</name>
Software Service window Analyzer The <analyzer> section in XML starts with the analyzer name (http in this example) and is followed by additional settings (not shown) specific to that analyzer. It is NOT safe to change the analyzer through the API. Selecting a different analyzer completely restructures the underlying XML. If you need to change the analyzer, you should start fresh: define a new software service through the NAM Console UI and then approach your changes through the XML.
<analyzer>
    <http>
Services tab Enabled check box
<disable>true</disable>  
Be careful here. You select the Enabled check box in the NAM Console to enable the software service, but you set the <disable> tag to false in XML to enable the software service.
Services tab IP address and Ports In the following example, the <report> section defines a software service named my software service name that monitors two services (<ip>/<port> pairs).
<application>
     <name>my software service name</name>
     <report>
         <service>                                        
             <ip>1.2.3.4</ip>
             <port>80</port>
         </service>
         <service>
             <ip>1.2.3.5</ip>
             <port>81</port>
         </service>
     </report>
Services tab IP address and Ports ranges For convenience, you can use <ipRange> and <portRange> instead of <ip> and<port>. In the following example, we use portRange to define a port range (80 to 81) for a single <ip>:
<application>
    <name>my software service name</name>
    <description>my rule description</description>
    <disable>true</disable>
    <report>
        <service>
            <ip>1.2.3.4</ip>
            <portRange>
                <b>80</b>
                <e>81</e>
            </portRange>
        </service>
    </report>
    <analyzer>
        <http>
In the NAM Console, the equivalent would be to create a rule for a single address with a range of ports. For example:
Services tab Aggregate ports check box
<aggregateSrvPorts>false</aggregateSrvPorts>
If <aggregateSrvPorts> is set to true and the application is using multiple ports per IP address, the NAM Probe aggregates data for the whole port range (to port 0). Otherwise, each port in the port range is monitored individually.
URL Monitoring tab URL analysis profile URL analysis profile (a setting specific to the HTTP analyzer) is defined with the <appKind> tag. Possible values are:
  • Web
    <appKind>web</appKind>  
    
  • Oracle Forms
    <appKind>of</appKind>  
    
  • SOAP/XML
    <appKind>soapxml</appKind>  
    
URL Monitoring tab URL type URL type is variously defined in the XML:
  • Virtual HTTP server: This option refers to monitoring a host where many websites reside under a single IP address. When you use a virtual HTTP server, all reported pages that have no separate definitions are aggregated into one record and reported together. This does not apply to pages from the IP address that are defined separately in a monitoring configuration. Such individual definitions do not require that you select this option. For example, a valid virtual HTTP server address is http://server.domain.com, without a trailing slash. In the XML, the equivalent is:
    <uri>  
        <hostId>http://server.domain.com</hostId>  
    
  • Static URL part: This is a fully qualified URL containing the protocol to be used, the server to be contacted, and the file to be requested, such as http://server.domain.com/page. In the XML, the equivalent is:
    <uri>
        <id>http://server.domain.com/page</id>  
    
  • URL as a regular expression: An extended POSIX regular expression describing a set of URLs. You can use parentheses “()” to select one or more subexpressions (specific portions of the results). If this mechanism is used, only the specified portions are reported; if more than one portion is specified, the portions are concatenated. In the XML, the equivalent is:
    <uri>  
        <regexId>(http://www.someserver.com/)report/(myreport)</regexId>  
    
URL Monitoring tab Page load time threshold Page load time threshold in the NAM Console is <slowThold>n</slowThold> in the XML, where n is ten-thousandths of a second. For example:
  • 10000 = 1 second
  • 5000 = 0.5 seconds
URL Monitoring tab Server time threshold Server time threshold in the NAM Console is <slowSrvThold>n</slowSrvThold> in the XML, where n is ten-thousandths of a second. For example:
  • 10000 = 1 second
  • 5000 = 0.5 seconds
URL Auto-Learning tab URL auto-learning URL auto-learning has four possible settings:
  • Global settings - To use the global settings, specify an empty autolearning section: <autoUri2/>.
  • Custom settings - To use custom settings, the <autoUri2> section is defined with <monitored> set to the number of reported URLs.
  • Off - To turn URL auto-learning off, the section is the same as for custom settings except that the number of reported URLs is set to 0: <monitored>0</monitored>.
  • All - This setting means that, instead of autolearning, all URLs are monitored. To configure this, set fullLog to true: <fullLog>true</fullLog>.
URL Auto-Learning tab Number of reported URLs Size of reported URLs pool: Number of reported URLs in the NAM Console is <monitored>n</monitored> in the XML, where n can be:
  • 0 to turn auto-learning off for this software service.
  • A positive integer to set the number of monitored URLs for auto-learning for this software service.
HTTP Options tab Generate ADoD data for When controlling ADoD data generation, you can either disable it completely or decide on the depth of available data. In the NAM Console UI:
  • Disabled (the default setting) turns off ADoD data generation. The equivalent settings in XML are:
    <vLog>false</vLog>  
    <hdrLog>false</hdrLog>  
    <hitLog>false</hitLog>  
    
  • Operation loads - the NAM Probe generates data enabling you to access essential operation-level information. The equivalent settings in XML are:
    <vLog>true</vLog>
    <hdrLog>false</hdrLog>
    <hitLog>false</hitLog>
    
  • Operation loads and hits - the NAM Probe generates data enabling you to access a deep drilldown report that represents an HTTP page hit broken down into specific HTTP elements. The equivalent settings in XML are:
    <vLog>true</vLog>
    <hdrLog>false</hdrLog>
    <hitLog>true</hitLog>
    
  • Operation loads, hits, and headers - the NAM Probe generates data enabling you to access even deeper drilldown information retrieved from related request and response headers for the hit. The equivalent settings in XML are:
    <vLog>true</vLog>
    <hdrLog>true</hdrLog>
    <hitLog>true</hitLog>
    

Finding other settings for software services

The most reliable way to determine what you need to change in the XML is to GET the software service before and after your changes on one NAM Probe, and then compare the before and after configurations. After you see what needs to change in the NAM Probe's configuration XML, you can use the API to apply similar changes to multiple other NAM Probes.

  1. Use the NAM Console API to GET the software service before you make changes. That is your before image of the software service.
  2. In the NAM Console UI, make and save the changes you need to make to this software service.
  3. Use the same GET call to get the software service again. That is your after image of the software service.
  4. Compare the before and after images to see what you need to change in the XML for the rest of the machines on which you need to make these change.