Document Managed by Network Operations
NetDB Documentation Navigation
- Introduction
- Network Contact Groups
- Query Operations
- Hostmaster Functions
- Custom Access Control Lists
- Errata
- XML Operations
- All assets within NetDB (IPs, hostnames, networks, ACLs, NCGs, NLs, etc) are stored and manipulated via XML
- All operations possible via the various NetDB frontends are also possible via the XML interface
- XML Queries and Edits can be submitted via two interfaces
- The NetDB html/java interface located at https://netdb.rutgers.edu/main/ManualXml.do
- The NetDB remote java interface (for automation purposes)
- All assets within NetDB (IPs, hostnames, networks, ACLs, NCGs, NLs, etc) are stored and manipulated via XML
- The XML Interface
- The web XML interface consists of two windows:
- The XML IN window is the input point for XML queries and edits
- The XML OUT window shows the results of the XML submitted in the XML IN window
- The XML IN window contains a number of elements:
- The XML meta tag describes the XML version and encoding type - this should not be altered
- The NetDB Doctype tag references the DTD - this should not be altered
- The NETDB_V2 tag acts as a container for the XML operation itself
- the 'test' value assigned to the tag turns 'testing' mode on or off.
- An XML test will check if the XML operation can be completed but will not parse the changes.
- The AUTH and AUTH_SESSION tags contain authorization information
- Pre-shared keys are available for users submitting changes via the remote interface
- Do not change the AUTH key or username unless you have been assigned a static PSK
- Your XML should be inserted within the NETDB_V2 tag, directly underneath "Insert XML immediately below for desired action."
- The XML OUT window returns the results of your query or edit operation
- If issuing an edit, status messages will be returned with each tag ([error_string="Success"] = success)
- The web XML interface consists of two windows:
- The XML DTD
- The XML DTD (document type definition) outlines all tags usable within the XML interface.
- A copy of the DTD can be found here: https://netdb.rutgers.edu/main/dtd/NETDB_V2.dtd
- The tags are arranged hierarchically. Below is the top-level tag hierarchy for the NetDB DTD:
<NETDB_V2>
<AUTH> - Authorization Information
<HOST_GROUP> - Host Edit Operation tag family
<QUERY_OPPS> - Query Operation tag family
<BULK_OPPS> - Bulk Host Edit Operation tag family
<ADMIN_OPPS> - Network and NCG Operation tag family
<NET_MAN> - ACL Operation tag family
<QUERY_RESULTS> - tag family for returning query operation results
</NETDB_V2>
- For hostname management, staff will primarily use the <QUERY_OPPS> (queries), <HOST_GROUP> (host edits) and <BULK_OPPS> (bulk edits) tags
- The XML DTD (document type definition) outlines all tags usable within the XML interface.
- XML Operation Syntax
- XML Operations submitted to the XML IN window must be properly formatted
- Must contain a nested series of header and operation-specific tags in hierarchical order
- Tags which require attributes (query attributes, auth attributes) must have those attribute fields populated
- As mentioned above, all operations occur within the <NETDB_V2> tag and must contain <AUTH> information. That said, the following must frame all XML ops:
<NETDB_V2>
<AUTH>
<AUTH_SESSION session_key="keygoeshere" username="usernamegoeshere" />
</AUTH>
<insert operations specific tags here />
</NETDB_V2>
- In the above example, session_key and username areattributes required by the <AUTH_SESSION> tag.
- The DTD contains a full list of required attributes for each tag type
- Operation-specific tags include queries, host edits, bulk edits, etc
- Each Operation-specific tag family has its own hierarchy which must be followed and attributes which must be included
- Below is an example of a query operation with each new tag level annotated:
<NETDB_V2>
<NETDB_V2>
<AUTH>
<AUTH_SESSION session_key="keygoeshere" username="usernamegoeshere" />
</AUTH>
<QUERY_OPPS> !! Top-level query operation tag
<QUERY_HOST host_name="netdb" domain_name="rutgers.edu." > !! Query type tag (host query) - attributes populated
<GET_HOST_DATA/> !! GET host_data for the host specified in the above QUERY_HOST tag
</QUERY_HOST>
</QUERY_OPPS>
</NETDB_V2>
- Host edits and Bulk Edit operations follow a similar syntax
- XML Operations submitted to the XML IN window must be properly formatted
- XML Query Operations
- XML Queries are performed using the <QUERY_OPPS> tag
- The following query types can be used within a <QUERY_OPPS> tag:
<QUERY_HOST> - queries host records
<QUERY_NETWORK> - queries a network
<QUERY_IP> - queries an IP
<QUERY_DOMAIN> - queries a domain record
<QUERY_NCG> - queries an NCG
- Each query tag requires one or more attributes to be specified (searching for a network? which network?!)
- These attributes can be found in the DTD, but simply trying the QUERY_OPP without the attribute will return which atributes are missing
- The following query types can be used within a <QUERY_OPPS> tag:
- Within each query type, a number of GETs can be inserted to specify the type of information you'd like returned:
!!! TAG HIERARCHY:
!!! <QUERY_OPPS>
!!! <QUERY_HOST>
!!! <GET_HOST_DATA>
!!! <GET_NETWORK_DATA>
!!! <GET_DOMAIN_DATA>
!!! <GET_HOST_CONTACT>
!!! <GET_TECHNICAL_CONTACT>
!!! <GET_ESCALATION_CONTACT>
!!! </QUERY_HOST>
!!! <QUERY_NETWORK>
!!! <GET_HOST_DATA>
!!! <GET_NETWORK_DATA>
!!! <GET_ZONE_DATA>>
!!! <GET_NCG_DATA>
!!! <GET_ACL_DATA>
!!! </QUERY_NETWORK>
!!! <QUERY_IP>
!!! <GET_HOST_DATA>
!!! <GET_NETWORK_DATA>
!!! <GET_ZONE_DATA>
!!! <GET_NCG_DATA>
!!! <GET_ACL_DATA>
!!! <GET_L2L3_DATA>
!!! <GET_L2L3_HISTORY_DATA>
!!! <GET_RT_L2L3_DATA>
!!! <GET_HOST_CONTACT>
!!! <GET_TECHNICAL_CONTACT>
!!! <GET_ESCALATION_CONTACT>
!!! </QUERY_IP>
!!! <QUERY_DOMAIN>
!!! <GET_HOST_DATA>
!!! <GET_DOMAIN_DATA>
!!! <GET_SN_DATA>
!!! <GET_SN_HISTORY_DATA>
!!! </QUERY_DOMAIN>
!!! <QUERY_NCG>
!!! <GET_NETWORK_DATA>
!!! <GET_NCG_MEMBERS>
!!! <GET_NCG_TREE>
!!! <GET_NCG_DATA>
!!! </QUERY_NCG>Using the tag structure specified above, a Query is formatted as such:
<QUERY_OPPS>
<QUERY_TYPE attribute="value>
<GET_TYPE/>
</QUERY_TYPE>
</QUERY_OPPS>The following query examples use the above query . Each is enclosed with a QUERY_OPPS tag, contains a query type, defining attributes and specifies a GET:
Host Query (getting host data)
<QUERY_OPPS>
<QUERY_HOST host_name="netdb" domain_name="rutgers.edu" >
<GET_HOST_DATA/ >
</QUERY_HOST>
</QUERY_OPPS>Network Query (getting network data)
<QUERY_OPPS>
<QUERY_NETWORK base_address="128.6.227.32" network_size="27>
<GET_NETWORK_DATA/>
</QUERY_NETWORK>
</QUERY_OPPS>Domain Query (getting domain data)
<QUERY_OPPS>
<QUERY_DOMAIN domain_name="rutgers.edu.">
<GET_DOMAIN_DATA/ >
</QUERY_DOMAIN>
</QUERY_OPPS>NCG Query (getting NCG members)
<QUERY_OPPS>
<QUERY_NCG ncg_name="Network Operations">
<GET_NCG_MEMBERS/ >
</QUERY_NCG>
</QUERY_OPPS>
- XML Queries are performed using the <QUERY_OPPS> tag
- Host Edits
- Host Edits, as well as some special host and domain record updates, are accomplished with the <HOST_GROUP> tag:
- The following tag types can be used within the <HOST_GROUP> tag:
<HOST_GROUP>
<HOST/> - generic tag for creating, deleting or overwriting host records - more detail below
<UPDATE_HOST_NCG/> - updates a host's NCG
<UPDATE_HOST_CONTACT/> - updates a host's contact email address
<RENAME_HOST/> - renames a host in the same way the 'rename a host' netdb host edit GUI does
</HOST_GROUP>
- The <HOST> tag deserves further consideration as it is used very frequently:
<HOST> - host record tag
<DNS> - DNS information tag
<A><A_REC/><A_REC/>...</A> - A Record tags
<MX><MX_REC/><MX_REC/>...</MX> - MX record tags
<PTR><PTR_REC/><PTR_REC/>...</PTR> - PTR record tags, used in reverses to specifit a PTR record
<NS><NS_REC/><NS_REC/>...</NS> - NS record tags, used to specifiy downstream NS servers
<TXT><TXT_REC/></TXT> - TXT record tags, for miscellaneous text strings (location, etc)
<SRV><SRV_REC/><SRV_REC/>...</SRV> - SRV record tags
<RP><RP_REC/><RP_REC/>...</RP> - RP record tags, for host contact information
<CNAME><CNAME_REC/><CNAME_REC/>...</CNAME> - CName tag, to specify a host alias
</DNS>
</HOST>
- Pushing a <HOST> tag, while specifying a hostname and leaving the rest of the tag blank, will delete the host
- Multiple record instances (multiple A recs, multiple MX recs) can only be created via the XML interface. Simply duplicate the record tag of your choice.
Here is an example of using the <HOST> tag to create a new host, netdbtest, which is a Cname to existing host netdb:
<HOST_GROUP>
<HOST host_name="netdbtest" domain_name="rutgers.edu." ncg="Network Operations" >
<DNS>
<CNAME ttl="86400" class_type="IN" >
<CNAME_REC canonical_name="netdb.rutgers.edu." views="INSIDE,OUTSIDE" />
</CNAME>
</DNS>
</HOST>
</HOST_GROUP>The following would create two host records, a forward and a reverse. Notice that each host requires a new <HOST> tag:
<HOST_GROUP>
<HOST host_name="urbanus" domain_name="rutgers.edu." ncg="JUNC LAN" >
<DNS>
<A ttl="86400" class_type="IN" >
<A_REC address="128.6.227.41" views="INSIDE,OUTSIDE" />
</A>
<MX ttl="86400" class_type="IN" >
<MX_REC preference_value="0" mail_exchanger="mx.rci.rutgers.edu." views="INSIDE,OUTSIDE" />
</MX>
<TXT ttl="86400" class_type="IN" >
<TXT_REC string="Location: HIll Center Room: 012 Campus: Busch" views="INSIDE,OUTSIDE" />
</TXT>
<RP ttl="86400" class_type="IN" >
<RP_REC email_address="jgaynor.rci.rutgers.edu." host="jgaynor.who.rutgers.edu." views="INSIDE,OUTSIDE" />
</RP>
</DNS>
</HOST>
<HOST host_name="41.227" domain_name="6.128.IN-ADDR.ARPA." ncg="JUNC LAN" >
<DNS>
<PTR ttl="86400" class_type="IN" >
<PTR_REC host_name="urbanus.rutgers.edu." views="INSIDE,OUTSIDE" />
</PTR>
</DNS>
</HOST>
</HOST_GROUP>Here is how one would use the <UPDATE_HOST_NCG> tag to update the NCG of host 'netdbtest' to 'Network Infrastructure':
<HOST_GROUP>
<UPDATE_HOST_NCG host_name="netdbtest" domain_name="rutgers.edu." new_ncg="Network Infrastructure" />
</HOST_GROUP>Here the <RENAME_HOST> tag is used to rename host 'test1' to 'test2':
<HOST_GROUP>
<RENAME_HOST host_name="test1" domain_name="rutgers.edu." new_host_name="test2" />
</HOST_GROUP>
- The following tag types can be used within the <HOST_GROUP> tag:
- Host Edits, as well as some special host and domain record updates, are accomplished with the <HOST_GROUP> tag:
- Bulk Edits
- Bulk Edits are accomplished using the <BULK_OPPS> tag. This tag is organized as follows:
- The tag is organized as follows:
<BULK_OPPS>
<UPDATE_NETWORK_NCG> - updates the NCG of all hosts (on an 'old NCG') in a network to a new NCG
<UPDATE_RP> - updates the RP records of all hosts (within a specified NCG) on a network
<NETWORK_HOST_DELETE> - bulk deletes all hosts (within a specified NCG) on a network
</BULK_OPPS>
Here is an example of <UPDATE_NETWORK_NCG>, changing all hosts in network 128.6.227.32/27 with an NCG of 'hostmaster' to the NCG 'JUNC LAN':
<BULK_OPPS>
<UPDATE_NETWORK_NCG base_address="128.6.227.32" size="27" old_ncg="hostmaster" new_ncg="JUNC LAN" />
</BULK_OPPS>Here is an example of <UPDATE_RP>, changing all RP records in 128.6.227.32/27 from jgaynor@rci.rutgers.edu to noc@rutgers.edu:
<BULK_OPPS>
<UPDATE_RP ncg="JUNC LAN" old_rp_host="jgaynor.who.rutgers.edu." old_rp_email="jgaynor.rci.rutgers.edu." new_rp_host="noc.who.rutgers.edu." new_rp_email="noc.rutgers.edu." />
</BULK_OPPS>The <NETWORK_HOST_DELETE> operation will clear a network of host data (forward and reverse):
<BULK_OPPS>
<NETWORK_HOST_DELETE base_address="128.6.227.32" network_size="27" />
</BULK_OPPS> - The tag is organized as follows:
- Bulk Edits are accomplished using the <BULK_OPPS> tag. This tag is organized as follows:
