IPControlCommand Line Interface (CLI) and Application Program Interface (API) Guide Version 6.0 The information in this document is subject to change without notice. Names of individuals and companies, as w ell as data used in examples, are fictitious unless otherwise noted. No part of this document may be copied, reproduced, or electronically transmitted in any form without the express written consent of BT Diamond IP. Adobe and Adobe Acrobat are trademarks of Adobe Systems Incorporated. Microsoft Windows 2000, Windows 2003, Windows 2008, and Internet Explorer are trademarks or registered trademarks of Microsoft Corporation in the U.S. and/or other countries. MySQL is a registered trademark of Oracle Corporation. Oracle is a registered trademark of Oracle Corporation. Solaris is a registered trademark of Oracle Corporation. UNIX is a registered trademark of the Open Group. Powered by Cryptzone MindTerm - Copyright 1997 – 2013 Cryptzone Group AB (publ). All rights reserved. July 2013 Command Line Interface (CLI) and Application Program Interface (API) Guide DID# IPC6002 Revision 2 Version 6.0 © 2013 BT Americas, Inc. BT Diamond IP 801 Springdale Drive, Suite 100 Exton, PA 19341 Tel. +1 610.423.4770 Fax +1 610.423.4774 Contents Introduction ............................................................................................................................... 1 About This Guide ..................................................................................................................................................................... 1 Command Line Interfaces (CLI) ........................................................................................... 3 Assumptions Regarding CLI Usage ........................................................................................................................................ 3 Executing Commands .............................................................................................................................................................. 4 Direct ..................................................................................................................................................................................... 4 Indirect .................................................................................................................................................................................. 4 File Format ............................................................................................................................................................................ 4 Imports....................................................................................................................................................................................... 6 ImportAddrpool................................................................................................................................................................... 6 ImportAggregateBlo ck ........................................................................................................................................................ 9 ImportChildBlock .............................................................................................................................................................. 11 ImportContainer................................................................................................................................................................. 16 ImportDevice...................................................................................................................................................................... 19 ImportDomain ................................................................................................................................................................... 24 ImportDeviceResourceReco rd ......................................................................................................................................... 26 ImportDhcpServer ............................................................................................................................................................. 28 ImportDNS......................................................................................................................................................................... 30 ImportDomainResourceRecord ....................................................................................................................................... 37 ImportElementSnapshot ................................................................................................................................................... 39 ImportGalaxyDomain........................................................................................................................................................ 40 ImportNetElement ............................................................................................................................................................ 42 ImportNetElementInterface ............................................................................................................................................. 44 ImportNetService ............................................................................................................................................................... 45 ImportNetServiceWithTemplate ...................................................................................................................................... 48 ImportPrefixPool ............................................................................................................................................................... 50 ImportRootBlock ............................................................................................................................................................... 52 ImportServiceSnapshot ..................................................................................................................................................... 54 ImportZone ........................................................................................................................................................................ 55 ImportZoneResourceRecord ............................................................................................................................................ 58 Exports..................................................................................................................................................................................... 60 ExportChildBlo ck .............................................................................................................................................................. 61 ExportContainer................................................................................................................................................................. 67 ExportDevice...................................................................................................................................................................... 69 ExportDeviceResourceRecord ......................................................................................................................................... 73 ExportNetElement............................................................................................................................................................. 76 ExportNetService ............................................................................................................................................................... 79 ExportPrefixPool ............................................................................................................................................................... 82 ExportResourceRecordPendingApproval ....................................................................................................................... 84 ExportResourceRecordPendingApprovalStatus............................................................................................................. 87 ExportRootBlock ............................................................................................................................................................... 89 Deletes ...................................................................................................................................................................................... 92 IPControl CLI and API Guide iii Contents DeleteAddrPool ..................................................................................................................................................................92 DeleteAggregateBlo ck ........................................................................................................................................................94 DeleteBlo ck .........................................................................................................................................................................96 DeleteContain er ..................................................................................................................................................................98 DeleteDevice .....................................................................................................................................................................100 DeleteDomain ...................................................................................................................................................................102 DeleteDeviceInterface ......................................................................................................................................................104 DeleteDeviceResourceReco rd .........................................................................................................................................106 DeleteDomainResourceReco rd .......................................................................................................................................108 DeleteNetElement ............................................................................................................................................................110 DeleteNetElementInterface.............................................................................................................................................112 DeleteNetService...............................................................................................................................................................114 DeletePrefixPool ...............................................................................................................................................................116 DeleteTask .........................................................................................................................................................................118 DeleteZone ........................................................................................................................................................................119 DeleteZoneResourceRecord ............................................................................................................................................121 Tasks .......................................................................................................................................................................................123 ArpDiscoverNetElement Task........................................................................................................................................123 Dh cpConfigurationTask ..................................................................................................................................................125 DHCPUtilization ..............................................................................................................................................................127 DiscoverNetElement ........................................................................................................................................................128 DnsConfigurationTask .....................................................................................................................................................130 GlobalRollup .....................................................................................................................................................................132 GlobalSyn c.........................................................................................................................................................................133 TaskStatus ..........................................................................................................................................................................134 Updates ...................................................................................................................................................................................136 DetachBlo ck ......................................................................................................................................................................136 JoinBlock............................................................................................................................................................................138 ModifyAddrpool ...............................................................................................................................................................139 ModifyBlo ck ......................................................................................................................................................................142 ModifyContainer ...............................................................................................................................................................148 ModifyDevice ....................................................................................................................................................................153 ModifyDeviceResourceRecord ........................................................................................................................................157 ModifyDh cpServer ...........................................................................................................................................................160 ModifyDomainResourceReco rd......................................................................................................................................163 ModifyNetElementInterface............................................................................................................................................166 ModifyPendingApproval ..................................................................................................................................................168 ModifyPrefixPool..............................................................................................................................................................170 SplitBlo ck ...........................................................................................................................................................................173 UseNextReservedIPAddress............................................................................................................................................175 Utilities ....................................................................................................................................................................................176 Dh cpRelease ......................................................................................................................................................................176 Purge...................................................................................................................................................................................179 Application Program Interfaces (API) ............................................................................ 182 Using the API.........................................................................................................................................................................182 Invoking the web service and authentication ................................................................................................................182 Error Pro cessing ...............................................................................................................................................................184 Available Application Program Interface Matrix ...........................................................................................................184 Imports ...................................................................................................................................................................................187 AddSite ...............................................................................................................................................................................187 DetachBlo ck ......................................................................................................................................................................191 ImportAddressPool ..........................................................................................................................................................193 iv IPControl CLI and API Guide Contents ImportAggregateBlo ck .................................................................................................................................................... 196 ImportChildBlock ............................................................................................................................................................ 199 ImportContainer............................................................................................................................................................... 204 ImportDevice.................................................................................................................................................................... 209 ImportDeviceResourceReco rd ....................................................................................................................................... 214 ImportDhcpServer ........................................................................................................................................................... 216 ImportDomain ................................................................................................................................................................. 220 ImportDomainResourceRecord ..................................................................................................................................... 223 ImportGalaxyDomain...................................................................................................................................................... 225 ImportNetElement .......................................................................................................................................................... 227 ImportNetElementInterface ........................................................................................................................................... 229 ImportNetService ............................................................................................................................................................. 231 ImportPrefixPool ............................................................................................................................................................. 234 ImportRootBlock ............................................................................................................................................................. 237 ImportZone ...................................................................................................................................................................... 240 JoinBlock ........................................................................................................................................................................... 244 ModifyBlo ck...................................................................................................................................................................... 245 ModifyPendingApproval ................................................................................................................................................. 253 SplitBlo ck .......................................................................................................................................................................... 255 Gets ........................................................................................................................................................................................ 257 getAddressPool................................................................................................................................................................. 257 getBlo ck ............................................................................................................................................................................. 258 getContainer...................................................................................................................................................................... 260 getDevice........................................................................................................................................................................... 261 getDeviceResourceRec .................................................................................................................................................... 263 getDh cpServer .................................................................................................................................................................. 265 getDomainResourceRec .................................................................................................................................................. 266 getNetelementInterface ................................................................................................................................................... 267 getPrefixPool .................................................................................................................................................................... 268 Tasks....................................................................................................................................................................................... 269 ArpDiscoverNetElement ................................................................................................................................................ 269 DHCPUtilization .............................................................................................................................................................. 270 DiscoverNetElement ....................................................................................................................................................... 272 GetTask ............................................................................................................................................................................. 273 GetTaskStatus ................................................................................................................................................................... 274 GlobalNetElementSyn c ................................................................................................................................................... 275 GlobalNetServiceSyn c ..................................................................................................................................................... 276 GlobalRollup..................................................................................................................................................................... 277 Exports................................................................................................................................................................................... 278 Overview ........................................................................................................................................................................... 278 Export Catego ries ............................................................................................................................................................. 278 Legacy Web Services ........................................................................................................................................................ 278 Next Generation W eb Services ....................................................................................................................................... 278 Legacy Web Services ............................................................................................................................................................. 279 ExportNetElementsAsCSV ............................................................................................................................................ 279 ExportAllNetElementsAsCSV ....................................................................................................................................... 282 ExportNetServicesAsCSV ............................................................................................................................................... 283 ExportAllNetServicesAsCSV .......................................................................................................................................... 286 Next Generation W eb Services ........................................................................................................................................... 287 Selectors ............................................................................................................................................................................. 287 Options.............................................................................................................................................................................. 287 Paging ................................................................................................................................................................................ 287 Sessions.............................................................................................................................................................................. 288 ExportRootBlock ............................................................................................................................................................. 289 IPControl CLI and API Guide v Contents ExportChildBlo ck .............................................................................................................................................................292 ExportContainer ...............................................................................................................................................................297 ExportDevice ....................................................................................................................................................................299 ExportDeviceResourceRecord ........................................................................................................................................305 ExportPrefixPool ..............................................................................................................................................................309 ExportResourceRecordPendingApproval ......................................................................................................................312 ExportResourceRecordPendingApprovalStatus ...........................................................................................................315 Updates ...................................................................................................................................................................................318 UseNextReservedIPAddress............................................................................................................................................318 Deletes ....................................................................................................................................................................................320 DeleteAddrPool ................................................................................................................................................................320 DeleteAggregateBlo ck ......................................................................................................................................................322 DeleteBlo ck .......................................................................................................................................................................324 DeleteContain er ................................................................................................................................................................325 DeleteDevice .....................................................................................................................................................................326 DeleteDeviceInterface ......................................................................................................................................................328 DeleteDeviceResourceReco rd .........................................................................................................................................331 DeleteDomain ...................................................................................................................................................................334 DeleteDomainResourceReco rd .......................................................................................................................................336 DeleteNetElement ............................................................................................................................................................338 DeleteNetElementInterface.............................................................................................................................................340 DeleteNetService...............................................................................................................................................................342 DeletePrefixPool ...............................................................................................................................................................344 DeleteTaskByDate ............................................................................................................................................................346 DeleteTaskByDays ............................................................................................................................................................347 DeleteTaskById .................................................................................................................................................................348 DeleteZone ........................................................................................................................................................................349 DeleteZoneResourceRecord ............................................................................................................................................351 Other Interfaces ................................................................................................................... 353 Callout Manager .....................................................................................................................................................................353 Operation ...........................................................................................................................................................................353 Configuration.....................................................................................................................................................................353 Applian ce Events ..............................................................................................................................................................356 RIR Template Support ..........................................................................................................................................................358 Introduction.......................................................................................................................................................................358 Configuration.....................................................................................................................................................................358 Operation ...........................................................................................................................................................................360 DNS Listen er .........................................................................................................................................................................363 Configuration.....................................................................................................................................................................363 Reco rd Pro cessing Rules ..................................................................................................................................................366 Detailed Description.........................................................................................................................................................367 DNS Deployment Callout................................................................................................................................................369 Appendix A API Changes ............................................................................................. 370 IPControl 6.0..........................................................................................................................................................................370 vi IPControl CLI and API Guide Introduction About This Guide This guide outlines command line interfaces (CLIs) into IPControl and application programming interfaces (APIs) to IPControl. Using CLIs extends the effectiveness of the IPControl Administrator, allowing him or her flexibility to run IPControl functions from a command line. Often this can shorten the time needed to bulk import or export data, or can allow for scheduling of tasks outside the IPControl product using cron or Windows Task Scheduler. Using APIs extends the effectiveness of the IPControl Administrator, allowing him or her flexibility to programmatically interface to IPControl. This enables the integration of IPControl into business processes or custom workflow. Introduction 1 About This Guide 2 IPControl CLI and API Guide . create IP address allocation templates Manual step . there are assumed dependencies among the different CLIs such that some CLIs will not function properly unless either other CLIs are run or some manual data setup is performed. The following manual data setup is recommended to populate the initial IPControl database before running any CLIs: Manual step – create block types Manual step – create device types Manual step – create user defined fields Manual step – create IP allocation reasons Manual step . However.create DNS and/or DHCP servers Table 1 illustrates the recommended order in which the IPControl CLIs should be run. or in some cases. ImportRootBlock.Command Line Interfaces (CLI) Assumptions Regarding CLI Usage Each CLI performs a specific task. or created manually 2 3 4 5 6 Com mand Line Interfaces (CLI) 3 . Table 1 CLI Sequence Sequence 1 CLI Nam e Brief Description Data Dependencies ImportContainer (logical) Imports logical containers N/A ImportNetElement Imports network elements such as routers and switches N/A ImportContainer (device) Imports device containers Network elements created using ImportNetElement CLI or created manually ImportRootBlock Imports root IP address blocks Containers created using ImportContainer CLI or created manually ImportChildBlock Imports child IP address blocks Root blocks created using ImportRootBlock CLI or created manually ImportDevice Imports devices Blocks created using ImportChildBlock. several tasks at once. Direct Sequence 7 8 9 CLI Nam e Brief Description Data Dependencies DiscoverNetElement Discovers live network element data Network elements created using ImportNetElement CLI or created manually DHCPUtilization Discovers live DHCP utilization data DHCP servers created manually ImportElementSnapshot Imports network element data Data generated from DiscoverNetElement CLI ImportServiceSnapshot Imports address pools discovered by “Collect DHCP Utilization” or “Global Synchronization of DHCP Servers” tasks. or indirectly via the available command script. Data generated from DHCPUtilization CLI ImportDNS Imports DNS domain and zone data DNS servers and views created manually 10 11 Executing Commands Each CLI is capable of being executed either directly by invoking the Java JVM.xls or .diamondip.csv Indirect The following example executes the same call but uses the indirect approach of calling a predefined command script: /opt/incontrol/ImportNetService. namely INC_HOME. For greater ease of use. Template files for each CLI are available in the templates directory underneath the CLI directory (typically <product home>/etc/cli).sh –u joe –p joepwd –f southeast. These files are easily created or modified using any standard text editor. any lines that begin with the pound (#) character are ignored by the InControl CLIs. Note when creating import files.csv File Format The format for import files is comma-separated values (CSV) and Microsoft Excel Workbook (. 4 IPControl CLI and API Guide . most spreadsheet applications like Microsoft Excel or OpenOffice Calc support saving as a CSV format. JAVA_HOME and CLASSPATH are resident): $INCHOME/jre/bin/java –DINC_HOME=$INCHOME –DNCX_HOME=$NCX_HOME –Duser. Direct The following is an example of the direct method of execution (it assumes that the IPControl environment variables. while the indirect method requires the proper passing of necessary parameters.. The direct approach requires a rather lengthy and cumbersome syntax.netcontrol.ImportNetService –u joe –p joepwd –f southeast.cli.dir=$INCHOME –cp $CLASSPATH com.xlsx). File Form at Available Command Line Interface Matrix Object Im port Modify Delete Address Pool X X X Aggregate Block X Child Block X X X X Container X X X X Device X X X X X Device Interface X Device RR X X DHCP Server X X DNS X Domain X Domain RR X Galaxy Domain X Net Element X Net Element Interface X Net Service X Prefix Pool X RR Pending Approval X X X X X X X X X X X X X X X X RR Pending Approval Status X Root Block X Zone X Zone RR X Next Available IP X X (see ImportZone) X X X X Join Block X Split Block X Detach Block X Task Im port GlobalNetElementSync X X GlobalNetServiceSync X X ImportElementSnapshot X ImportServiceSnapshot X GlobalRollup X X DiscoverNetElement X X DhcpConfigurationTask X DhcpUtilization X GetTask X GetTaskStatus X DeleteTask Export Modify Delete Export X X Com mand Line Interfaces (CLI) 5 . This address must be in a block with an In-Use/Deployed status.ImportAddrpoolCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportAddrpool.cli. -e <error messages> No The name of the file that error messages will be reported in.sh –u joe –p joepwd –f newaddrpools. See below for the required file format. $INCHOME/etc/cli/ImportAddrpool.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. Yes 6 IPControl CLI and API Guide .txt file.reject –e importerrors. places into the newaddrpools.csv –r newaddrpools.netcontrol.txt File Format Col Field Accepted Values Required A Start Address The IP Address of the first address in the pool.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportAddrpool.csv file. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. and reports errors to the importerrors. Usage Example This example imports address pools from the newaddrpools.diamondip.reject file any records that could not be imported. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.Im portAddrpool Imports ImportAddrpool Overview The ImportAddrpool CLI allows the user to bulk import address pools into IPControl. No I DHCP Option Set The name of an Option Set used with this pool. ”Automatic TA DHCPv6” Yes D Name Address Pool name. K Allow DHCP Client Classes For IPv4 and IPv6 Dynamic and Automatic type pools: A list of Client Classes that are allowed in this address pool. For example. to disallow two client classes named “denyA” and “denyB”. and the start address is in overlapping space. Primary Net Service must also be specified. No. to allow two client classes named “allowA” and “allowB”. G Primary Net Service The name of the DHCP server that will serve addresses from this pool Yes. This address must be in the same block as the Start Address. “Automatic DHCP”.(PrefixLength is used instead). “Static”. the Start and End addresses must not overlap any other pools. To use this field. H Failover Net Service The name of the failover DHCP server that will serve addresses from this pool. For example. No For IPV4 address pools. the DHCP policy set applies only to non-CNR DHCP servers. C Address Pool Type One of “Dynamic DHCP”. when a DHCP server is not defined for the subnet. unless Start address is not unique. Separate the list entries with a vertical bar “|”. No For IPV4 address pools. In addition. “Reserved”. for IPv4 pool.Im portAddrpool Col Field Accepted Values Required B End Address The IP Address of the last address in the pool. “Dynamic NA DHCPv6”. No F Container The name of the container that holds the block in which the pool is defined. specify: No allowA|allowB L Deny DHCP Client Classes For IPv4 and IPv6 Dynamic and Automatic type pools: A list of Client Classes that are NOT allowed in this address pools. Defaults to “Start Address-End Address” No E Share Name DEPRECATED. ”Automatic NA DHCPv6”. This field will be ignored. The container is then used to uniquely determine the block that will contain the address pool. This is ignored for IPv6 pools. ”Dynamic TA DHCPv6”. specify: No denyA|denyB Com mand Line Interfaces (CLI) 7 . For IPV6 address pools. the DHCP policy set applies only to CNR DHCP servers. This is required only if there is overlapping address space in use. Yes. For IPV6 address pools. the DHCP option set applies only to CNR DHCP servers. Separate the list entries with a vertical bar “|”. J DHCP Policy Set The name of a Policy Set used with this pool. the DHCP option set applies only to non-CNR DHCP servers. for IPv6 pool.This is ignored for an IPv4 pool(End Address field is used instead). 8 IPControl CLI and API Guide .Im portAddrpool Col Field Accepted Values Required M PrefixLength CIDR size of the pool for an IPv6 pool. An IPv6 should be on CIDR boundaries. Yes. target block and a container. -e <error messages> No The name of the file that error messages will be reported in. It will also adjust the parent block assignments of any would-be child blocks. and reports errors to the importerrors.reject file any records that could not be imported.cli. IPControl will validate and insert the desired aggregate block. places into the newaggblocks.sh –u joe –p joepwd –f newaggblocks.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. See below for the required file format.netcontrol. By specifying a parent block.csv file. Yes Com mand Line Interfaces (CLI) 9 . Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.reject –e importerrors. Long format eliminates ambiguity in cases where there are duplicate container names. $INCHOME/etc/cli/ImportAggregateBlock. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in. Usage Example This example imports aggregate blocks from the newaggblocks.txt File Format Col A Field Container Accepted Values Required The name of the container into which to insert the new aggregate block.diamondip.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportAggregateBlock. Names can be in either short or long format. Short format example: Dallas.txt file. Long format example: IPControl/Texas/Dallas.csv –r newaggblocks.Im portAggregateBlock ImportAggregateBlock Overview The ImportAggregateBlock CLI allows the user to insert an intermediate level Aggregate block between existing blocks in the block hierarchy.ImportAggregateBlockCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportAggregateBlock. Yes. defaults to “Default”. the name of the interface to attach the block to. Yes D Block Type The Block Type for the block If not specified. No E Block Name A name for the block. This field will be ignored. No F Description A description of the block.g. use “\n” to separate lines. Yes 10 IPControl CLI and API Guide .255. No L Create Reverse Domains Whether or not to automatically create reverse DNS domain(s) for this block. where the name is the UDF name and the value is desired value. If not specified. If the UDF type is Textarea. If the UDF type is Checkbox. Yes P Parent Block Address The address of the parent block Yes Q Parent Block Size The size of the parent block in short-notation (e. 24 for a 255. a block type of Any is assumed.255. K Interface Offset or Address DEPRECATED.255. no. Multiple pairs can be specified by separating each pair with the “|” character. No J Interface Name If this block is being added to a device container.g. If not specified. Accepted values are true or false. For example. No G SWIP Name SWIP name for the block. 24 for a 255. No N User Defined Fields A series of name=value pairs. O Parent Container The name of the container where the parent block resides. Defaults to system supplied name of Address space/Block size. Yes C Block Size The size of the block in short-notation (e.255. Yes. defaults to false.0 network).. for UDFs defined as required fields.0 network). No M Domain Type Specify the domain type for the reverse DNS domain(s) to be created when Create Reverse Domains is “true”. Otherwise. UDFone=value one |UDFtwo=value two. No I Allocation Reason Description A description of the reason for the allocation. if block is being added to device container.. the valid values are “on” or “off”. if required by container rules H Allocation Reason The name of a pre-existing Allocation Reason.Im portAggregateBlock Col Field Accepted Values Required B Start Address The start address of the new aggregate block. Yes. Wrap the statement in “quotes” if it contains any commas. -v No Produces verbose output.txt file. and reports errors to the importerrors.sh –u joe –p joepwd –f newchildblocks. It can also be used to attach an existing block to another container.netcontrol. described later in this section. This option requires expanded format. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.cli.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-o] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportChildBlock. See below for the required file format.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-o] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import.csv –r newchildblocks.Im portChildBlock ImportChildBlock Overview The ImportChildBlock CLI allows the user to bulk import child blocks into IPControl. See below.reject file any records that could not be imported.diamondip. places into the newchildblocks.ImportChildBlockCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-o] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportChildBlock. by specifying an existing Address Block. -e <error messages> No The name of the file that error messages will be reported in. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. Specify whether the import file contents will overwrite any matching records that exist in the database.reject –e importerrors. It also allows modification of existing records when using the overwrite option (-o) and the expanded format. Usage Example This example imports child blocks from the newchildblocks. -o No Overwrite option.txt Com mand Line Interfaces (CLI) 11 .csv file. $INCHOME/etc/cli/ImportChildBlock. A cell with no value. For example. To clear a field in an existing record. Blocks cannot be moved to a different container using this CLI. $INCHOME/etc/cli/ImportChildBlock. The rows describe blocks to be either imported or modified. new blocks will be imported. columns AB-AD contain the values for the user defined fields. beginning with “^”. The first row is a header line. 12 IPControl CLI and API Guide . The column headers beyond the architected column AA contain the user defined field tags. existing blocks will be modified. as in row 2 column AD. container (A). The –o (overwite) parameter is required in order to modify blocks via this CLI. row 3 has no user defined fields defined for that block.csv –o Here is the input file: Note the following: You can produce a file in this format using the ExportChildBlock CLI. In other words. as shown in row 4 column AC. In this example. If an expanded user defined field column contains data for a block where that field is not defined. Blocks to be modified are identified by either blockName (D) or blockAddr (E) and. will result in no change to the value for the record stored in the database. an empty cell will be exported. because the container is used to identify the block. specify “!BLANK!”. an error will be reported. Column P contains “Expanded” when the row includes user defined fields beyond column AA. If there is no value for a field in the block. when necessary to resolve ambiguity.sh –u joe –p joepwd –f cexport.Im portChildBlock Import with overwite using expanded format and the !BLANK! keyword This example imports child blocks using the expanded format. Names can be in either short or long format. IPV4 is the default. the block will be attached to the specified container. Com mand Line Interfaces (CLI) 13 . Yes H SWIP Name SWIP name for the block. FullyAssigned. Reserved. If no address block is specified. Defaults to system supplied name of Address space/Block size. Yes | No If an IPV6 block is desired.Im portChildBlock File Format Col Field Accepted Values Required A Container The name of the container that will hold the block. follow the block size with “|true”. Yes.255. No J Allocation Reason Description A description of the reason for the allocation. No E Address Block The address block to allocate. a block type of Any is assumed. No F Description A description of the block. Short format example: Dallas. if required by Container rules I Allocation Reason The name of a pre-existing Allocation Reason. C Block type The Block Type for the block If not specified. Use “\n” to separate lines. No L Interface Name If this block is being added to a device container. Accepted values are: Deployed.255.g. Long format example: IPControl/Texas/Dallas. the name of the allocation template to use to create address pools from the newly created block. 24 for a 255. the name of the interface to attach the block to. Aggregate. Otherwise.. Yes B Block size | IPV6 The size of the block in short-notation (e. this field is skipped. Long format eliminates ambiguity in cases where there are duplicate container names. no. Wrap the statement in “quotes” if it contains any commas. Yes. If the address is specified and already exists. No D Block Name A name for the block. space will be auto-allocated. if block is being added to device container. No G Current Status The current status of the block.0 network). No K Allocation Template If this block is being added to a device container with blockStatus=Deployed. If Allocation Reason is not currently in IPControl. it will be interpreted as an offset from the beginning of the block (i. UDFone=value one |UDFtwo=value two. For example. No O Domain Type Specify the domain type for the reverse DNS domain(s) to be created when Create Reverse Domains is “true”.2). This can also be the string “from-start” or “from-end” if you are attaching a block to a device container and wish IPControl to determine the first available address from the start or the end of the block. an expanded format input file is expected. for the interface IP address(es). Accepted values are true or false. No 14 IPControl CLI and API Guide .xxx. Valid only for Deployed blocks. N Create Reverse Domains Whether or not to automatically create reverse DNS domain(s) for this block. This list is supplied to DHCP clients on this subnet. it should be in the form xxx. No S DHCP Policy Set The name of a DHCP Policy Set defined within IPControl that should apply to this subnet. the valid values are “on” or “off”. For example. When this column contains the word “Expanded”. Yes. Accepted values are true or false. or offset(s) from the beginning. An offset of 1 is assumed if none is specified.xxx.e. If an integer is specified. The server name or IP Address is valid. Multiple addresses can be specified by separating the values with the ‘|’ character. defaults to “Default”.xxx. defaults to false. Valid only for Deployed blocks. If the UDF type is Textarea. defaults to false. If the UDF type is Checkbox. See below for an example of this format. You cannot add an interface address or delete all interface addresses. If not specified. separate the server names with a vertical bar (|). No T DNS Servers The list of default DNS Servers for this subnet. If not specified. If an IP address is specified. separated by the ‘|’ character if there is more than one. Note that you cannot modify or delete a virtual interface address. Valid only for Deployed blocks. You can modify or delete interface addresses using the overwrite option. No P User Defined Fields A series of name=value pairs.xxx. R DHCP Option Set The name of a DHCP Option Set defined within IPControl that should apply to this subnet. For multiple servers. use “\n” to separate lines.xxx. where the name is the UDF name and the value is desired value. Multiple pairs can be specified by separating each pair with the ‘|’ character. an offset of 2 in a /24 block will create an interface xxx. specify 3 interface offsets as 1|2|3. No Valid only for Deployed blocks. If not specified. for UDFs defined as required fields. No. Q Exclude From Discovery Flag indicating if this subnet should be included in Host Discovery tasks. Specify the complete list of addresses using the IP address.Im portChildBlock Col Field Accepted Values Required M Interface Offset or Address The specific address(es). 0-15. Multiple WINS servers may be specified. Y DNS Reverse Domains The list of DNS Reverse domains for this address space. separated by a vertical bar (|).0. This list will appear in the GUI when choosing domains for devices.in-addr. (IPv6 only) Note this field is not used for overwrite. In this example.10. No W Failover DHCP Server The name or IP Address of the failover DHCP Server for this address space. To specify a domain type. Valid only for Deployed blocks.1. Valid only for Deployed blocks. and 40. This list will appear in the GUI when choosing domains for devices. Com mand Line Interfaces (CLI) 15 . No Valid only for Deployed blocks in device containers. /External |40. separated by a comma. is of type ‘External’. No X DNS Forward Domains The list of DNS Forward domains for this address space.ins.arpa. hr. For example: No hr. To specify a domain type.arpa.0. If not specified. specify the domain followed by ‘/’ followed by the domain type. Used to provide this information to DHCP for Dynamic Address types.com.0. Valid only for Deployed blocks.arpa. defaults to false.com is of type ‘External’. and dmz.10. Valid only for Deployed blocks. No V Primary DHCP Server The name or IP Address of the primary DHCP server for this address space. specify the domain followed by ‘/’ followed by the domain type. Valid options are: No ‘Bestfit’ (the default option when none is specified) ‘Sparse’ (IPv6 only) ‘Random’. For example: No 0-15.1.|dmz. Z Primary WINS Server The IP Address of the Primary WINS Server for this subnet. AB Primary Subnet Flag indicating if this subnet is primary. This address is supplied to DHCP clients on this subnet.10. Accepted values are true or false.ins.com. No AA Allocation Strategy The Automatic Allocation Strategy to use where a block address is not provided.in-addr.arpa.10. Valid only for Deployed blocks.in-addr. uses the default domain type.Im portChildBlock Col Field Accepted Values Required U Default Gateway The default gateway address for this subnet.in-addr.com uses the default domain type. separated by a vertical bar (|)./External In this example. csv –r newcontainers. -e <error messages> No The name of the file that error messages will be reported in.Im portContainer ImportContainer Overview The ImportContainer CLI allows the user to bulk import containers into IPControl. $INCHOME/etc/cli/ImportContainer.diamondip.txt File Format Col Field Accepted Values Required A Container Name The name of the container. See below for the required file format.cli.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportContainer. this container name must match exactly the name of a network element already in the database or the record will be rejected.csv file.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import.sh –u joe –p joepwd –f newcontainers. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in. No 16 IPControl CLI and API Guide . Use “\n” to separate lines.ImportContainerCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportContainer. If you are creating a device container. and reports errors to the importerrors. places into the newcontainers.netcontrol.reject –e importerrors.reject file any records that could not be imported. Usage Example This example imports containers from the newcontainers. Yes B Container Description A brief description of the container.txt file. the name must be the complete path beginning at the top of the container tree. To specify that all device types should be allowed. separated by ‘/’. use NONE. Note this applies only to logical containers. specify the device type followed by ‘|’ followed by the information template name. use ALL. For example: No devicetype1|templateone/devicetype2/ devicetype3|templatetwo In this example. separated by ‘/’. Yes D Container Type Either logical or device. To specify information templates to be used for a block type. J Information Template The name of a pre-existing information template to be associated with this container. separated by ‘/’. Long format example: IPControl/Texas/Dallas. F Rule2 A listing of the block types enabled for root block creation. separated by ‘/’. Short format example: Dallas.Im portContainer Col Field Accepted Values Required C Parent Container The name of the parent container for this container. specify the block type followed by ‘|’ followed by the information template name. ALL is the default. Yes E Rule1 A listing of the valid block types for this container. No Com mand Line Interfaces (CLI) 17 . To specify that no device types should be allowed. If using the long format. separated by ‘/’. Long format eliminates ambiguity in cases where there are duplicate container names. For example: No blocktype1|templateone/blocktype2/block type3|templatetwo In this example. No H Rule4 A listing of the block types for which SWIP Names are required. No G Rule3 A listing of the block types that can be used for space allocation from the parent container. To specify information templates to be used for a device type. Names can be in either short or long format. No I Rule5 A listing of the device types for this container. blocktype2 does not use an information template. and will be ignored if specified for device containers. devicetype2 does not use an information template. No . specified in the previous parameter. Multiple fields can be specified by separating each name=value pair with the ‘|’ character. where the name is the UDF name and the value is the desired value. L Maintain History Records 18 IPControl CLI and API Guide Specify whether or not Container History and Block History records will be kept for all appropriate block types. The history records are created each time the Global Utilization Rollup task is run. If not specified. defaults to false.Im portContainer Col Field Accepted Values Required K User Defined Fields Specify the values for the UDFs in the container information template. Specify as a series of name=value pairs. use “\n” to separate lines. the valid values are “on” or “off”. For example: Yes. Accepted values are true or false. If the UDF type is Textarea. for UDFs defined as required fields fieldOne=valueOne|fieldTwo=valueTwo If the UDF type is Checkbox. Usage Example This example imports all of the devices in the file devices.sh –u joe –p joepwd –f devices. It also allows modification of existing records when using the overwrite option (-o) and the expanded format.cmd –u <userId> -p <pswd> –f <import_file> [-e <error messages>] [-r <rejects file>] [-o] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import.ipcontrol. This is used to bulk load information about existing network devices. See below. described later in this section.csv –e importerrors. This option requires expanded format. Produces verbose output.sh –u <userId> -p <pswd> -f <import_file> [-e <error messages>] [-r <rejects file>] [-o] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportDevice.cli. $INCHOME/etc/cli/ImportDevice. -o No -v No Overwrite option. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.ImportDevice –u <userId> -p <pswd> -f <import_file> [-e <error messages>] [-r <rejects file>] [-o] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportDevice.csv and reports errors to the importerrors.Im portDevice ImportDevice Overview The ImportDevice CLI imports devices into IPControl. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.txt Com mand Line Interfaces (CLI) 19 .diamondip. Specify whether the import file contents will overwrite any matching records that exist in the database.txt –r importrejects. See below for the required file format.txt file. -e <error messages> No The name of the file that error messages will be reported in. an error will be reported. If an expanded user defined field column contains data for a device where that field is not defined. as in row 5 column U. The –o (overwite) parameter is required in order to modify devices via this CLI. For example. specify “!BLANK!”. In other words. as shown in row 6 column U. new devices will be imported. The rows describe devices to be either imported or modified. will result in no change to the value for the record stored in the database. beginning with “^”. ipaddress or MACAddress. Columns S-V contain the values for the user defined fields. existing devices will be modified. row 4 has no user defined fields defined for that device.csv –o Here is the input file: Note the following: You can produce a file in this format using the ExportDevice CLI. Devices to be modified are identified by hostname. To clear a field in an existing record. A cell with no value. For example. Column L contains “Expanded” when the row includes user defined fields beyond column R. $INCHOME/etc/cli/ImportDevice.sh –u joe –p joepwd –f cexportdevice. an empty cell will be exported.Im portDevice Import with overwite using expanded format and the !BLANK! keyword This example imports devices using the expanded format. The first row is a header line. If there is no value for a field in the device. The column headers beyond the architected column R contain the user defined field tags. row 5 has no value in column U. 20 IPControl CLI and API Guide . F MAC Address The hardware MAC addresses of the device. followed by “/from-start” or “/from-end”. For DHCP V6: Dynamic NA DHCPv6. the address type and IP address cannot be updated. but an Interface address cannot be modified or deleted. if Hostname specifies use of naming policy No Yes. Dynamic TA DHCPv6 and Automatic TA DHCPv6. Note that if Dynamic. this will default to Ethernet. Separate multiple IP addresses with a vertical bar (“|”). Dynamic DHCP. specify the block address.0/from-start Yes For devices with multiple IP Addresses on a single interface (devices with address type Interface). Use ImportChildBlock with overwrite to modify or delete an Interface address. E Hardware Type Specify Ethernet or Token Ring. there must be a DHCP server defined in the subnet policies for this IP Address. C Host Name Devices of type Interface may not be imported. the device is created as a multi-homed device. for example: 10. If not left blank.0. Manual DHCP and Reserved. Valid host name or APPLYNAMINGPOLICY D Device Type The name of a device type configured in IPControl. B Address Type The address type of this device. Automatic NA DHCPv6. If MAC Address is specified. MAC Address must also be specified. Automatic or Manual DHCP is specified. If there is more than one. For single-homed devices only. However. Note that device attributes can be modified. Accepted values are: Static. When Hardware Type is specified. Yes Yes Yes. use one or more address to locate the device for an overwrite. to indicate that IPControl should use the next available address in an IPV4 block.30. Automatic DHCP. Manual NA DHCPv6. Separate multiple entries with a vertical bar (“|”). if Hardware Type is specified or if address type is Manual DHCP Com mand Line Interfaces (CLI) 21 . there must be one MAC for each IP Address in column A.Im portDevice File Format Col Field Accepted Values Required A IP Address The IP Addresses of the Device. but they can be modified using overwrite. The alias may be fully qualified (contains a trailing dot). M Aliases The alias or list of aliases for this hostname. Also. Short format example: Dallas. See below for an example of this format. the valid values are “on” or “off”. the CNAME record will be created in the same domain as the device. When fully qualified. or not. J Domain Type Domain type name already defined to IPControl. for UDFs defined as required fields. Domain name already defined to IPControl H Domain Name I Container The name of the container that contains the block. If the UDF type is Checkbox. you must also specify Resource Record Flag = true. an expanded format input file is expected.Im portDevice Col Field Accepted Values Required G Resource Record Flag Whether or not to add resource records for this device. where the name is the UDF name and the value is desired value. use “\n” to separate lines. Multiple fields can be specified by separating each name=value pair with the ‘|’ character. the “Default” domain type will be used No K Description A description of the device. For example. When this column contains the word “Expanded”. 22 IPControl CLI and API Guide No . the reverse domain must exist in order for the PTR record to be added. When you specify an alias. Specify multiple aliases by separating each one with the ‘|’ character. everything after the first qualifier is interpreted as a domain name. To use this field. If not specified. Long format eliminates ambiguity in cases where there are duplicate container names. When not fully qualified. If not specified. Accepted values are true or false. if overlapping space is in use and the block name is ambiguous. Long format example: IPControl/Texas/Dallas. defaults to false. No Note that the domain name must be specified if the block policy has no forward domains. Use “\n” to separate lines. Names can be in either short or long format. Yes. Yes. if Resource Record Flag is “true” and the block policy has no forward domains. No L User Defined Fields A series of name=value pairs. Yes. a CNAME record is created. fieldOne=valueOne|fieldTwo=valueTwo. If the UDF type is Textarea. There must one entry for each IP Address in Column A. for Address Type “Manual NA DHCPV6”. No O Interface Names Specify the names of the interfaces created for a multi-homed device. Q Virtual flag Specify the flags for each interface created for a multi-homed device. if multiple IP Addresses are entered in Column A. Yes. There must one entry for each IP Address in Column A. If not specified. defaults to false. Accepted values are true or false. Com mand Line Interfaces (CLI) 23 . P Exclude from Discovery Flags Flag indicating if this subnet should be included in Host Discovery tasks. If not specified. Separate entries with a vertical bar (“|”). Yes. defaults to false. Reserved and will be ignored R DUID DHCP Unique Identifier No Yes. the warning will be ignored and the device added with the duplicate hostname when this field is true. Accepted values are true or false. if multiple IP Addresses are entered in Column A. Separate entries with a vertical bar (“|”).Im portDevice Col Field Accepted Values Required N Ignore Warning If the administrator policy of the user indicates “Warn” for the “Allow Duplicate Hostnames Checking” option. No C Managed Indicates that this domain is fully defined in IPControl.ipcontrol.ImportDomain –u <userId> -p <pswd> -f <import_file> [-e <error messages>] [-r <rejects file>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportDomain. Yes B Domain Type Domain type name already defined to IPControl. If not specified. the “Default” domain type will be used.cmd –u <userId> -p <pswd> –f <import_file> [-e <error messages>] [-r <rejects file>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in. $INCHOME/etc/cli/ImportDomain. See below for the required file format.cli. Accepted values are true or false. No 24 IPControl CLI and API Guide . -e <error messages> No The name of the file that error messages will be reported in.diamondip. -v <verbose> No Produces verbose output. defaults to true.txt file.sh –u <userId> -p <pswd> -f <import_file> [-e <error messages>] [-r <rejects file>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportDomain. If not specified. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. Usage Example This example imports all of the domains in the file domains.csv and reports errors to the importerrors.txt File Format Col Field Accepted Values Required A Domain Name The name of the domain being created.csv –e importerrors.txt –r importrejects.Im portDomain ImportDomain Overview The ImportDomain CLI imports domains into IPControl.sh –u joe –p joepwd –f domains. ignored if Managed is “False”.arpa’ domain. If not specified. defaults to “604800”. For example. Com mand Line Interfaces (CLI) 25 . No User Defined Fields A series of name=value pairs. For example. No I Refresh Zone refresh interval.ins. No E Reverse Indicates that this domain is a reverse ‘in-addr. defaults to “3600”. would be represented as 'root. No Information Template Pre-defined information template to be associated with this domain. No N Contact O P The contact email address in dotted format. defaults to “10800”.ins. defaults to “86400”. if Derivative is “ALIAS” H Serial Number Zone serial number. If not specified.Im portDomain Col Field Accepted Values Required D Delegated Indicates that this domain will be associated directly with a zone file. for UDFs defined as required fields. use “\n” to separate lines. defaults to false. an email address of 'root@ins. This can be one of “STANDARD”. If not specified a default contact name will be formed by prepending 'dnsadmin' to the domain name as in 'dnsadmin. or “ALIAS”. No J Retry Zone retry interval. If the UDF type is Textarea. defaults to true. The default is “STANDARD”. Yes. If not specified. ignored if Managed is “False”. the valid values are “on” or “off”. No G Template Domain Name of template domain. If not specified. defaults to “1”. If not specified.arpa’ or ‘ip6. No K Expire Zone expire time. If the UDF type is Checkbox. fieldOne=valueOne|fieldTwo=valueTwo. Yes. ignored if Managed is “False”. ignored if Managed is “False”. If not specified. If not specified. defaults to “86400”. Accepted values are true or false.com'.'.com'. where the name is the UDF field name/tag and the value is desired value. No L Negative Cache TTL Zone negative cache time to live. ignored if Managed is “False”. Accepted values are true or false. No F Derivative Specify the role of this domain. “TEMPLATE”. No M Default TTL Default time to live. ignored if Managed is “False”. Multiple fields can be specified by separating each name=value pair with the ‘|’ character. If not specified.com. csv file.cli.ImportDeviceResourceRecordCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportDeviceResourceRecord.reject –e importerrors. Yes B Domain Type The name of the domain type to which the domain belongs. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. $INCHOME/etc/cli/ImportDeviceResourceRecord. places into the newresourcerecs. -e <error messages> No The name of the file that error messages will be reported in.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportDeviceResourceRecord. Refer to the appropriate RFC for exact text that should be entered. and reports errors to the importerrors. Usage Example This example imports resource records from the newresourcerecs. Yes 26 IPControl CLI and API Guide . Note that this section is specific to the type of resource record.Im portDeviceResourceRecord ImportDeviceResourceRecord Overview The ImportDeviceResourceRecord CLI allows the user to bulk import DNS resource records for a device into IPControl.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. Defaults to “Default” No C Owner The OWNER section of the resource record.sh –u joe –p joepwd –f newresourcerecs. See below for the required file format. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.txt File Format Col Field Accepted Values Required A Domain The name of the domain to which the resource records will be added.csv –r newresroucerecs.txt file.reject file any records that could not be imported.diamondip.ipcontrol. if IP Address in overlapping space. The container is then used to uniquely determine the device. Yes J Data The text for the DATA area of the resource record. Yes. G TTL The Time To Live. Yes K Comment Text to be appended to the resource record. F Container The name of the container that holds the device. unless Host Name is specified. Yes. defaults to IN. If not specified. Yes. No H Class The value currently supported is IN. No Com mand Line Interfaces (CLI) 27 . No I Resource Record Type The type of resource record being imported.Im portDeviceResourceRecord Col Field Accepted Values Required D Host Name The device host name. E IP Address The IP Address of the Device. Note that this section is specific to the type of resource record. This is required only if there is overlapping address space in use and the IP address is in overlapping space. Refer to the appropriate RFC for exact text that should be entered. unless IP Address is specified. No 28 IPControl CLI and API Guide . File Format Col Field Accepted Values Required A Name The name of the DHCP Server.ipcontrol. Defaults to 90. This must be one of the products defined in IPControl.ImportDhcpServer –u <userId> -p <pswd> -f <import filename> [-e <error messages>] [-r <rejects file>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportDhcpServer. then this must be a legal IPv6 address. No F Global Sync Specify TRUE to include this server in Global Sync tasks. Yes C Product The product name of the DHCP Server. This is often the hostname of the system running the server. -e <error messages> No The name of the file that error messages will be reported in. If the V4V6Both parameter is V6. No G Configuration Path The path to the server’s configuration file. Must be a legal. Yes B IP Address The IP Address of the DHCP Server. See below for the required file format. This must be a legal IP address. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.Im portDhcpServer ImportDhcpServer Overview The ImportDhcpServer CLI creates DHCP Servers in IPControl. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.cli. Yes D Agent The IPControl agent that manages the server Yes E Default Threshold The default alert threshold applied to all scopes managed by this server. Defaults to false. fully qualified path name for the host system.diamondip.cmd –u <userId> -p <pswd> –f <import filename> [-e <error messages>] [-r <rejects file>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import.sh –u <userId> -p <pswd> -f <import filename> [-e <error messages>] [-r <rejects file>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportDhcpServer. This must be a number between 0 and 100. No I Start Script The path to the script that starts the server. Defaults to FALSE. No R CLI Password Collection program password credential No S CLI Arguments Arguments to the Collection program.Im portDhcpServer Col Field Accepted Values Required H Lease Path The path to the lease file. No V DHCP Policy Set The name of a policy set defined in IPControl. then the remainder of the field is treated as a file name and the file’s contents are used. No M Collection User User name for SCP/FTP access to the executive. ‘V6’ or ‘Both’ Yes Com mand Line Interfaces (CLI) 29 . If the field begins with “file:”. This can be the text itself. No K Collection Type SCP or FTP No L Collection Port Must be between 1 and 65535. fully qualified path name for the host system. If the field begins with “file:”. No U DHCP Option Set The name of an option set defined in IPControl. Defaults to FALSE. Must be a legal. No P CLI Command Collection program name No Q CLI User Collection program user credential. No X DHCP Failover IP Address The IP Address used by the DHCP server for failover communications. then the remainder of the field is treated as a file name and the file’s contents are used. Differs according to product. No W DHCP Client Classes The names of client classes defined in IPControl that this server will be using. Must be a legal. fully qualified path name for the host system. Valid values are ‘V4’. This can be the text itself. fully qualified path for the host system. Must be a legal. Separate multiple client classes with a vertical bar (“|”). No J Stop Script The path to the script that stops the server. No Y DHCP Failover Port The Port used by the DHCP server for failover communications. AB V4V6Both IP version supported by the DHCP server. No N Collection Password Password for the collection user. or a reference to a file. or a reference to a file. No Z Configuration File Pre-Extension Text to prepend to the DHCP server configuration file. Must be a legal. No T DDNS Specify TRUE to enable dynamic DNS updates when this server issues a lease. No AA Configuration File Post-Extension Text to append to the DHCP server configuration file. No O Collect Backup Subnets Specify TRUE to collection statistics on backup subnets. Defaults to 21 for FTP and 22 for SCP. fully qualified path name for the host system. x and newer named. If not supplied new domains will be created in the view named 'Default. Otherwise it is assumed to be a ISC DNS zone file.sh -f <import filename> -s <server> [-v <view>] [-z <zone>] [-l] [-t <domainType>] [-m <view/zone=domainType.Im portDNS ImportDNS Overview The ImportDNS CLI allows the user to import the contents of a DNS zone file.dnsimport.DNSImport –f <import filename> -s <server> [-v <view>] [-z <zone>] [-l] [-t <domainType>] [-m <view/zone=domainType. If the -z parameter is not supplied.ipcontrol. See -f. … >] [-n] [-2 None|ZoneOnly|ZoneAndRR] [-c container] Via command script (Windows) %INCHOME%/etc/cli/ImportDNS. If not specified.conf file. … >] [-n] [-2 None|ZoneOnly|ZoneAndRR] [-c container] Parameters Param eter Required Description -f <import filename> Yes File name containing data to import. -t No The name of the DomainType to assign to the imported domain(s).x or newer configuration file. or the zone files referenced by master zones declared in an ISC BIND 8. the file is assumed to be a ISC BIND 8. then the Default DomainType is used. … >] [-n] [-2 None|ZoneOnly|ZoneAndRR] [-c container] Via command script (Unix) $INCHOME/etc/cli/ImportDNS.cmd -f <import filename> -s <server> [-v <view>] [-z <zone>] [-l] [-t <domainType>] [-m <view/zone=domainType. but any other sub-domains found within the zone will not be created as separate domains.cli.diamondip.' -z <zone> No The name of the zone. 30 IPControl CLI and API Guide . Must be supplied when importing a single zone file. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. If supplied the view must exist. The domain hierarchy will be created to support the domain in the SOA. -v <view> No The name of the view in which new domains should be created. -l No Import “flat” zone. -s <server> Yes The name of the DNS network service as defined in IPControl to import the zone data into. ins. If the IP reflected in the ‘rdata’ of an A record or the ‘owner’ of a PTR record falls within an In-Use/Deployed Block which overlaps space with another In-Use/Deployed Block in another portion of the container hierarchy. This processing can include filling in any missing TTL values or Name fields. They are used here for completeness. Valid values are: None – (default) Ignore all slave zones.com=internal.dmz. It does this by sequentially reading each resource record contained in a specified zone file.ins . Class. processing each one according to a set of rules described below. An example with Views defined: -m “internal/hr.ins. -2 No Slave (or secondary) zone handling. This means that after initial processing the resource record will contain all the required fields: Name. -h. not when parsing an individual zone file using the –z option. -? No Print help. correctly using the Origin when an @ character is Com mand Line Interfaces (CLI) 31 .com=internal.Im portDNS Param eter Required Description -m No Comma separated list of ViewName/ZoneName=DomainType entries. These are used as an override of either the –t option or the system Default DomainType. -c No Container name. NS records are ignored. the Autogenerate NS records flag for the zone will be turned off. ZoneOnly – Import the zone definition only. TTL.com=external” An example when views are not defined: -m “hr. Note: This option is only valid when parsing a configuration file.external/dmz. then this parameter can be used to specify a container which is used to select the proper block . By specifying this option. -n No Allow NS records to be imported. “InControl/North America/US/PA”) of a container in IPControl to be used to distinguish between overlapping address blocks. The full pathname (e.ins. not when parsing an individual zone file using the –z option. In addition.com=external” Note: Quotes are not necessary unless there are spaces in the DomainType names. and then inserting some portion of the resulting data into IPControl. Type. NS records will be imported into the domain Resources Records. Description The ImportDNS CLI imports DNS resource records contained in zone data files into IPControl. and Rdata. By default. it will attempt to create Device and IP Address records accordingly. ZoneAndRR – Import the zone definition and the Resource Records in the zone file. Note: This option is only valid when parsing a configuration file. Resource records read from zone files are initially processed using the same rules described in RFC 1035. When ImportDNS encounters A or PTR records when importing a zone.g. The type-specific rules are described in Table 2: Table 2 Type-specific Rules Type Description SOA Data from the SOA record is used to create or update a domain in IPControl. Top level domains created in this way have no parent associated with them. If the domain does not exist in IPControl it will be created. 32 IPControl CLI and API Guide . and appending the Origin when appropriate as described by RFC 1035. NS NS records are ignored by the ImportDNS CLI. Note: If parent domains are created as a result of the record being imported. If the domain name ends with . and a device will be created using the name field. PTR Data from each PTR record is used in the same way as data from A records with the exception that the name and rdata field are swapped when creating an IP address and device. refresh.arpa. or a top level domain is created. while the managed property will not be set. and contact fields. the data from the imported record will be used to update the domain. The domain name is taken from the name field of the resource record. MX MX records are imported into IPControl and attached to the domain supplied in the name field. When importing an A record the ImportDNS CLI will use the left-most label of the domain supplied in the name field as the host portion of the FQDN for the host. negative caching TTL. The resulting resource record is then processed using rules specific to each resource record’s Type field. expire.Im portDNS encountered in a name field. retry. This includes the serial number. the reverse property will be set. When a domain is created by the ImportDNS CLI its parent domain will be created and linked to its child. If the resulting domain (everything to the right of the left-most label) does not exist in IPControl. If parent domains were also created. while its delegated property will not be set. then it will be created along with any necessary parent domains. the managed and delegated properties will be set for the domain. their delegated property will be set and their managed property will not be set. A Data from each A record is used to create resource record entries attached to domains in IPControl and additionally can create individual IP addresses and devices. After the domain and its parents have been created. This process continues until an existing parent is found. an IP address will be created using the rdata field. If the address found in the rdata field of the resource record can be located within an existing address block defined in IPControl. or if it already exists in IPControl. The device and IP address will also be associated with the resource record in addition to the domain. The newly created domain will have its managed property set.in-addr. default TTL. or sub-domain. the delegated property will be set. In addition. com._msdcs. Example zone data file db. mail.0: Com mand Line Interfaces (CLI) 33 . A resource record object is created using the data supplied by the imported record. Parent domains will have the delegated property set and the managed property not set._tcp IN SRV 0 100 400 ftp. ( 1 .192.0.com.0.sw. ftp.168.example: $TTL 3600 @ IN SOA thomas.example.5 mail IN A 192.168. Serial number 10800 .com. 600 SRV 0 100 400 pdc.example. Retry 604800 .0.168. If the domain cannot be found in IPControl it will be created._msdcs and the domain name part would be: sw. All others The domain name that the resource record will be placed in is taken from the name field of the resource record after the left label has been removed.example.168. The name field of SRV records specifies a service available for the domain for which it is a part of.example._tcp _http.168.example. dns w3 web incoming smtp pop IN IN IN IN IN IN CNAME CNAME CNAME CNAME CNAME CNAME thomas.ins. along with any necessary parent domains.com.thomas.example.www.3 www IN A 192. Minimum TTL IN NS thomas.com. hostmaster. To avoid collision with the rest of the domain name space.com. Refresh 3600 .com.example.ins.1 dhcp IN A 192.com.0.ins.168.6 _ftp._tcp.4 ftp IN A 192.example.com.0. and it is linked to the domain._tcp.com.example. leading underbars are prepended to the labels that describe the service.Im portDNS Type Description SRV The data from SRV records are processed in the same way as other resource records with the exception of the name field. Expire 86400 ) .pdc.0.pdc.0. Examples The usage examples below use these example zone data or configuration files: Example zone data file db.2 msdc IN A 192. It considers all the labels to the right of the right-most label that starts with an underscore to be part of the domain name of the SRV record.example. mail.com www. IN SRV 0 100 434. www.168. For example in the following SRV record: _ldap.sw.example.com.1 thomas IN A 192.com. localhost IN A 127.0. This practice is not always followed in the field and so the ImportDNS CLI uses the following rule to determine where the domain name part of the name field starts.com. The service specification part would be: _ldap. The service type and protocol is encoded in the left portion of its name field. PTR PTR PTR PTR PTR PTR dhcp.com.168. Expire 86400 ) ..168. The following domains are created: com.example. }. The zone 0.in-addr. The domain 0.arpa.” { type master.192”.Im portDNS 0. mail.example”.arpa is created and associated with the server dns1.com.com.com.example.com. zone “0.168. and 0. ftp.” { type master.com. }.in-addr. Refresh 3600 . msdc.com.0.168.192.192. and the NS record.168.example.168. 1. and reverse properties set. has associated with it the resource records from the db. specifically the files db. The domain example.0. managed. Serial number 10800 .192.192.0.192.arpa.cmd -f /etc/named.in-addr.192.arpa.in-addr. and are marked as delegated and managed.168. It is also marked as reverse.conf -s dns1.168.168.arpa IN SOA thomas.example.0.inaddr.ins. Retry 604800 .192.arpa is created if it does not already exist.example. is marked as delegated and managed. all the ones declared in the db.thomas.in-addr.192.0.conf: Options { directory “/var/lib/named”. 34 IPControl CLI and API Guide .example file except the SOA record. 4. The domain example. Minimum TTL ( 2.192. www. $INCHOME/etc/cli/ImportDNS.sw.arpa. hostmaster.168.arpa.example.168.192.192.168. file “db.192.com. Usage Example 1 This example creates master zones linked to the server dns1. IN NS thomas.0.conf file. Its properties are also updated with the information from the SOA record for the zone. file “db.in-addr.in-addr.com using the zone data contained within the zone files that are referenced by the master zone declarations within the named. has 14 resource records associated with it. 2. 5.192. The data from the SOA record updates the domain example..in-addr.168.arpa.192.0.example.example.com with the values from its rdata field.arpa. The domain has its delegated.com.com.in-addr.in-addr.arpa.0.example and db.example.168.168.com.0.192 file except the SOA and NS records.sw. 1 . zone “example. 6.0.192.sw.168.168. Example Bind 9 configuration file named.in-addr.com. notify no.arpa. example.arpa.in-addr. }.ins. 3.com.com.com Usage Example 2 This example imports the resource records declared in the zone file db. The domain 0.ins. thomas.0. 168.168.. and 0.com.in-addr. The domain hr. It is also marked as reverse. The domain 0. Its properties are also updated with the information from the SOA record for the zone.com –t internal Usage Example 4 This example creates master zones linked to the server dns1.sw. The domains in-addr.168.com. .sw.ins.sw.192.com.com -s dns1.com=external” Usage Example 5 This example creates master zones linked to the server dns1.192. and 0.sw.com using the zone data contained within the zone files that are referenced by the master zone declarations within the named.192.arpa.168.arpa. The domain example.foo.in-addr..ins. Its “masters” substatement is set to 192. are assigned to the “Default” DomainType.ins.192.arpa. specifically the files db.com. example.168. Com mand Line Interfaces (CLI) 35 .168.Im portDNS $INCHOME/etc/cli/ImportDNS. The domain is marked as delegated and managed.0. The domain has its delegated.192 file except the SOA and NS records. has 14 resource records associated with it.com.0.example file except the SOA record.conf file.ins.arpa and 0.arpa.com is created and associated with the server dns1. $INCHOME/etc/cli/ImportDNS.ins.168. is marked as delegated and managed. if they did not already exist: com.com is also created with the SOA information found in the file bak.0 -s dns1.192.168.168.cmd -f /etc/named.0.0.conf -s dns1.com -z hr.0.hr.inaddr.192 file except the SOA and NS records.ins. and the NS record. The domain example. and reverse properties set. The domain 0.conf -s dns1.1.arpa.com -2 ZoneOnly In addition.in-addr.conf file. $INCHOME/etc/cli/ImportDNS..ins.168.example file except the SOA record. specifically the files db.ins.168. all the ones declared in the db. is associated with it the resource records from the db.168.sw. $INCHOME/etc/cli/ImportDNS.cmd -f /etc/named.example and db. The following domains are created: com.in-addr. 192. has 14 resource records associated with it. and example. example.com -z 0.192.com.ins.com –m “example.168.com is created if it does not already exist. and are marked as delegated and managed.2.192.ins. managed.ins. The zone hr. The domains com. If necessary the domain foo. The data from the SOA record updates the domain example.com.ins.cmd -f db. The following domains are created.com. all the ones declared in the db. Its properties are also updated with the information from the SOA record for the zone. a zone definition is created for the Slave zone foo. The domain example.arpa Usage Example 3 This example imports the resource records declared in the zone file db.in-addr.hr. It is also marked as reverse.com. has associated with it the resource records from the db.com with the values from its rdata field. The domain example. The data from the SOA record update the domain example. and are marked as delegated and managed.com with the values from its rdata field..arpa. The domain is assigned to the “internal” DomainType.sw. No resource records are imported for foo.sw.com.192.com using the zone data contained within the zone files that are referenced by the master zone declarations within the named.example and db.com.192.com are assigned to the “external” DomainType. and the NS record. in-addr.0.cmd -f db. is marked as delegated and managed. foo. a zone definition is created for the Slave zone foo.com.sw.168.example and db.com file except the SOA and NS records. Its properties are also updated with the information from the SOA record for the zone. It is also marked as reverse. all the ones declared in the db.arpa.0.0.192..com is also created with the SOA information found in the file bak.168.1.168.com using the zone data contained within the zone files that are referenced by the master zone declarations within the named.168. If it did not already exist. The domain 0.cmd -f /etc/named.com -2 ZoneAndRR In addition.example file except the SOA record.0.192.ins.com.168.com.conf -s dns1. 192.0. has 14 resource records associated with it.192.ins.conf file. The domain example.com.com..arpa. specifically the files db. has associated with it the resource records from the db. Its “masters” substatement is set to 192. and are marked as delegated and managed. example. The data from the SOA record updates the domain example. is marked as delegated and managed. The following domains are created: com. The domain is marked as delegated and managed. The domain has associated with it the resource records from the bak.168.foo. and 0.com with the values from its rdata field. Return codes The ImportDNS CLI always returns 0. and the NS record. The domain example.inaddr. the domain foo.sw. 36 IPControl CLI and API Guide .2.Im portDNS Usage Example 6 This example creates master zones linked to the server dns1. $INCHOME/etc/cli/ImportDNS.in-addr.192 file except the SOA and NS records. txt file.ipcontrol. Usage Example This example imports resource records from the newresourcerecs.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportDomainResourceRecord.txt Com mand Line Interfaces (CLI) 37 . -e <error messages> No The name of the file that error messages will be reported in. $INCHOME/etc/cli/ImportDomainResourceRecord. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.ImportDomainResourceRecordCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportDomainResourceRecord. and reports errors to the importerrors.sh –u joe –p joepwd –f newresourcerecs.reject –e importerrors.diamondip.cli. This CLI allows the administrator to enter resource records that are not bound to a particular device. See below for the required file format.csv –r newresroucerecs. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. places into the newresourcerecs.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. Note: For Glue records that link one zone to another.csv file.Im portDomainResourceRecord ImportDomainResourceRecord Overview The ImportDomainResourceRecord CLI allows the user to bulk import DNS resource records for a domain into IPControl.reject file any records that could not be imported. use the ImportZoneResourceRecord CLI. Note that this section is specific to the type of resource record. No 38 IPControl CLI and API Guide No . Yes B Domain Type The name of the domain type to which the domain belongs. Note that this section is specific to the type of resource record. If not specified. The Time To Live. Defaults to “Default” No C Owner Yes D TTL The OWNER section of the resource record. defaults to IN.Im portDomainResourceRecord File Format Col Field Accepted Values Required A Domain The name of the domain to which the resource records will be added. No F Resource Record Type The type of resource record being imported. Yes G Data The text for the DATA area of the resource record. Refer to the appropriate RFC for exact text that should be entered. Yes H Comment Text to be appended to the resource record. Refer to the appropriate RFC for exact text that should be entered. E Class The value currently supported is IN. Im portElementSnapshot ImportElementSnapshot Overview The ImportElementSnapshot CLI allows the user to import interfaces and blocks discovered by either a “Discover Router Subnets” or “Global Synchronization of Network Elements” task.out Com mand Line Interfaces (CLI) 39 .cli.cmd –u <userId> -p <pswd> -t <taskId> [-o <output file>] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -t <taskId> Yes The Id of the “Discover Router Subnets” or “Global Synchronization of Network Elements” task. such tasks are used to query the current state of the network and perform difference analysis to compare actual deployment with the topology modeled in IPControl.ImportElementSnapshot –u <userId> -p <pswd> -t <taskId> [-o <output file>] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportElementSnapshot.diamondip. and places into the elementsnapshot. However. If not specified output will be sent to STDOUT. Usage Example This example imports blocks and interfaces discovered by task 12345. This CLI then.sh –u joe –p joepwd –t 12345 -o elementsnapshot. Typically. during the initial setup of the system the queried information from these tasks can be used to populate the original IPControl model. is used to perform this initial population of discovered blocks and interfaces. -v No Produces verbose output.out file any output messages. $INCHOME/etc/cli/ImportElementSnapshot. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u <userId> -p <pswd> -t <taskId> [-o <output file>] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportElementSnapshot. -o <output file> No The name of the file to write all output.netcontrol. -e <error messages> No The name of the file that error messages will be reported in.reject –e importerrors.ImportGalaxyDomainCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportGalaxyDomain.reject file any records that could not be imported.csv -r newgdomains.diamondip. Usage Example This example import galaxy domains from the newgdomains.txt 40 IPControl CLI and API Guide .Im portGalaxyDomain ImportGalaxyDomain Overview The ImportGalaxyDomain CLI allows the user to bulk import Galaxy Domains into IPControl. places into the newgdomains.cli.txt file.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. $INCHOME/etc/cli/ImportGalaxyDomain. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportGalaxyDomain. See below for the required file format.sh –u joe –p joepwd –f newgdomains.ipcontrol. and reports errors to the importerrors.csv file. -v No Produces verbose output. Yes C Domain Type The name of the domain type to which the domain belongs. already defined to IPControl. to be assigned to specified galaxy. No D View The name of the galaxy view to which to assign this domain. If specified.' No Com mand Line Interfaces (CLI) 41 . If not specified. Yes B Domain Name Domain name. the new zone will be created in the view named 'GalaxyDefault. the “Default” domain type will be used. If not specified.Im portGalaxyDomain File Format Col Field Accepted Values Required A Galaxy Name Name of the Galaxy to which to assign this domain. the view must exist. This can be any combination of letters and numbers. or a fully-qualified host name. This must be a valid IPv4 or IPv6 IP address. See below for the required file format.sh –u joe –p joepwd –f netelements. Usage Example This example imports Network Elements from the netelements. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import.txt File Format Col Field Accepted Values Required A Name The name of the Network Element. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. Yes B IP Address/FQDN The IP address or fully-qualified domain name (FQDN) of the Network Element.reject –e importerrors.Im portNetElement ImportNetElement Overview The ImportNetElement CLI allows the user to bulk import network elements into IPControl. places into the netelements.diamondip.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportNetElement.ImportNetElementCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportNetElement. $INCHOME/etc/cli/ImportNetElement.reject file any records that could not be imported.cli.csv file. Yes 42 IPControl CLI and API Guide .txt file. and reports errors to the importerrors. -e <error messages> No The name of the file that error messages will be reported in.netcontrol.csv –r netelements. No K Read community string The community string used by SNMP to read details from this network element. No Com mand Line Interfaces (CLI) 43 . or vpn. Yes H Telnet user A user name used to telnet to this device. Model must be predefined in IPControl. defaults to Unknown. No N V3 Authentication Protocol Either MD5 or SHA1. No I Telnet password A password used by the telnet user to telnet to this device. No L Interface List Separated by vertical bars (“|”). No O V3 Authentication Password Required if field N is set to either MD5 or SHA1 No P V3 Privacy Protocol Only DES supported at this time.Im portNetElement Col Field Accepted Values Required C Vendor The vendor of the Network Element. Leave blank or set to NONE if no authentication. Otherwise use V3 parameters below. Accepted values are cmts. No M V3 Username Required if using SNMP V3. No R V3 Context Name SNMP V3 Context name. No J Enable password Password used to enter “enabled” or “privileged” mode on the device. Yes when Vendor is specified. Vendor must be predefined in IPControl. Set this when using SNMP V1. No Q V3 Privacy Password Required if field P is set to DES. if needed. Yes G Agent Name The exact name of the IPControl Agent that’s responsible for contacting this Network Service. router. Accepted values are True or False (case insensitive). Yes when Model is specified. defaults to Unknown. E Type The type of Network Element. If not specified. If not specified. Leave blank or set to NONE if no privacy. switch. D Model The model name of the Network Element. Yes F Global Sync Whether or not to include this Network Element in the Global Sync process. if needed. No S V3 Engine ID SNMP V3 Engine ID. cli.sh –u joe –p joepwd –f netelementinterfaces.csv –r netelementinterfaces. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.txt File Format Col Field Accepted Values Required A Name The name of a Network Element already defined to IPControl.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import.diamondip.reject –e importerrors. -v No Produces verbose output. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in. and reports errors to the importerrors.Im portNetElementInterface ImportNetElementInterface Overview The ImportNetElementInterface CLI allows the user to bulk import network element interfaces into IPControl.reject file any records that could not be imported. $INCHOME/etc/cli/ImportNetElementInterface. Yes B Interface Name The name of the interface being imported. No 44 IPControl CLI and API Guide .ImportNetElementInterfaceCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportNetElementInterface.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportNetElementInterface.ipcontrol. -e <error messages> No The name of the file that error messages will be reported in. places into the netelementinterfaces. See below for the required file format. This can be one of “Disabled”.txt file. Yes C Status The status of the new interface.csv file. Usage Example This example imports Network Elements interfaces from the netelementinterfaces. or “Deployed”. “Enabled”. The default is “Enabled”. diamondip.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportNetService. places into the netservices. This can be any combination of letters and numbers.reject –e importerrors. This must be a valid IPv4 or IPv6 IP address.cli. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in. Usage Example This example imports network services from the netservices.csv –r netservices. Yes Com mand Line Interfaces (CLI) 45 . Yes B IP Address/FQDN The IP address or fully-qualified domain name (FQDN) of the Network Service. ImportNetService support will be removed in a future release.csv file. Use the ImportDhcpServer CLI instead.netcontrol. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.txt File Format Col Field Accepted Values Required A Name The name of the Network Service.0. $INCHOME/etc/cli/ImportNetService.txt file. Note: This CLI has been deprecated as of IPControl 6.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameter Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import.ImportNetServiceCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportNetService. See below for the required file format. -e <error messages> No The name of the file that error messages will be reported in.Im portNetService ImportNetService Overview The ImportNetService CLI allows the user to bulk import DHCP network services into IPControl. or a fully-qualified host name. and reports errors to the importerrors.sh –u joe –p joepwd –f netservices.reject file any records that could not be imported. db or c:\qip\dhcp\dhcpd. L VendorInfo Vendor specific information for the product’s collection type. J Collection port The port number the collection method (scp or ftp) is listening on. for example. For collection types qip.db For collection type cnr that are not managed via the SDK. K Container(s) No longer used. this field is not used. the 46 IPControl CLI and API Guide No . This must be a value already defined in IPControl. I Password for collection The password used by the collection method (scp or ftp) to log in to the remote server. the information includes the Path/Executable of NRCD command. Accepted values are scp or ftp. Accepted values are True or False (case insensitive). If this column is left blank. H User name for collection The username used by the collection method (scp or ftp) to log in to the remote server.Im portNetService Col Field Accepted Values Required C Type The type of Network Service. dhcp is assumed. If no value is specified. No For CNR servers. No If the collection method is cnrsdk. No D Product name The Network Service product name. Used in conjunction with the ‘User name for collection’. this will default to 22 if the collection method is scp. If no value is specified.conf |c:\qip\dhcp\dhcp. /opt/qip/dhcp/dhcpd. No G Collection Method The method by which the IPControl Agent will collect data from the Network Service.conf |/opt/qip/dhcp/dhcp. Each item of information is specified in this single field by separating each field with the ‘|’ character. the information includes the DHCP Configuration file pathname and DHCP Active Lease file pathname. Yes F Global Sync Whether or not to include this Network Service in the Global Sync process. Accepted value is dhcp. this will default to False. this will be the port that the CNR server is listening on for connections. this field is not used. and 21 if the collection method is ftp. No For CNR servers managed via the SDK. msft and isc. adc. No If the collection method is cnrsdk. For example. INS DHCP or CNR DHCP. the collection type may also be cnrsdk for those servers that are managed via the SDK. Yes E Agent name The name of the IPControl Agent that’s responsible for contacting this Network Service. |myuserid|mypass M WarningThreshold Default scope utilization warning threshold. For example. Provide warnings when usage of a pool assigned to this service is exceeded. the NRCMD password and the Cluster Name. this will default to 90. No Com mand Line Interfaces (CLI) 47 .Im portNetService Col Field Accepted Values Required NRCMD user id. the directory component is not required. For example. /opt/cnr/bin/nrcmd|myuserid|mypass| cluster1 For CNR servers managed via the SDK. however the username and password to connect to the CNR machine are required as the second and third fields. If no value is specified. Using the IPControl GUI.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. places into the netserviceswithtemp.reject file any records that could not be imported. create a DNS Server Template. See below for the required file format.reject –e importerrors. This is accomplished through the System Network Services Policies & Options DNS Server Templates.csv file. Yes 48 IPControl CLI and API Guide .sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportNetServiceWithTemplate.Im portNetServiceWithTemplate ImportNetServiceWithTemplate Overview The ImportNetServiceWithTemplate CLI allows the user to bulk import DNS servers into IPControl by applying a pre-defined Server Template. Usage Example This example imports network services with template from the netserviceswithtemp.txt file.csv –r netserviceswithtemp. $INCHOME/etc/cli/ImportNetServiceWithTemplate. and reports errors to the importerrors.netcontrol. This can be any combination of letters and numbers and should be a fully qualified domain name (FQDN). Then use this CLI to create new servers using that template. -e <error messages> No The name of the file that error messages will be reported in.cli.diamondip.txt File Format Col Field Accepted Values Required A Name The name of the Network Service.ImportNetServiceWithTemplateCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportNetServiceWithTemplate. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u joe –p joepwd –f netserviceswithtemp. Yes C Type The type of Network Service. Accepted value is dns.Col Field Accepted Values Required B IP Address The IP address of the Network Service. Yes Com mand Line Interfaces (CLI) 49 . Yes E Agent name The name of the IPControl Agent that is responsible for contacting this Network Service as defined in System Agents. UNIX Standard for INS DNS. dns is assumed. No D Template name The name of the DNS Server Template as defined in System Network Services Policies & Options DNS Server Templates. This must be a valid IPv4 IP address. For example. If this column is left blank. netcontrol.csv –r newprefixpools. Usage Example This example imports prefix pools from the newprefixpools. This address must be in a block with an In-Use/Deployed status.diamondip.reject –e importerrors. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. Yes B Length The length of the prefix pool. -e <error messages> No The name of the file that error messages will be reported in. $INCHOME/etc/cli/ImportPrefixPool.reject file any records that could not be imported. Yes D Name Prefix Pool name.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportPrefixPool. Defaults to “Start Address/Length” No 50 IPControl CLI and API Guide . places into the newprefixpools. See below for the required file format.Im portPrefixPool ImportPrefixPool Overview The ImportPrefixPool CLI allows the user to bulk import prefix pools into IPControl.txt File Format Col Field Accepted Values Required A Start Address The IP Address of the first address in the pool. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.cli.txt file. and reports errors to the importerrors. Yes C Address Pool Type One of “Dynamic PD DHCPv6” or “Automatic PD DHCPv6”.csv file.sh –u joe –p joepwd –f newprefixpools.ImportPrefixPoolCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportPrefixPool. unless Start address is not unique. and the start address is in overlapping space. Separate the list entries with a vertical bar “|”. No H Shortest Prefix Length The shortest prefix length allowed for delegated prefixes. CNR DHCP only. to disallow two client classes named “denyA” and “denyB”. No I Primary Net Service The name of the DHCP server that will serve addresses from this pool No J DHCP Option Set The name of an Option Set used with this pool. No L Allow DHCP Client Classes A list of Client Classes that are allowed in this address pool. Yes G Longest Prefix Length The longest prefix length allowed for delegated prefixes. to allow two client classes named “allowA” and “allowB”. This is required only if there is overlapping address space in use.Im portPrefixPool Col Field Accepted Values Required E Container The name of the container that holds the block in which the pool is defined. For example. No. The container is then used to uniquely determine the block that will contain the address pool. CNR DHCP only. specify: denyA|denyB No Com mand Line Interfaces (CLI) 51 . Separate the list entries with a vertical bar “|”. No K DHCP Policy Set The name of a Policy Set used with this pool. specify: allowA|allowB No M Deny DHCP Client Classes A list of Client Classes that are NOT allowed in this address pools. For example. F Delegated Prefix Length The default length of the delegated prefix. csv –r newrootblocks.0.ImportRootBlockCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportRootBlock.csv file.g. places into the newrootblocks.txt File Format Col Field Accepted Values Required A Container The name of the logical container that will hold the block. Short format example: Dallas.cli. This should be in the format of a network address (e.reject file any records that could not be imported.netcontrol..sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportRootBlock. 10.diamondip. $INCHOME/etc/cli/ImportRootBlock. Usage Example This example imports Root Blocks from the newrootblocks. and reports errors to the importerrors.txt file.0).cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in. Long format eliminates ambiguity in cases where there are duplicate container names.0. See below for the required file format. -e <error messages> No The name of the file that error messages will be reported in.reject –e importerrors. Yes B IP space The IP block to create. Names can be in either short or long format. Long format example: IPControl/Texas/Dallas. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u joe –p joepwd –f newrootblocks. Yes 52 IPControl CLI and API Guide .Im portRootBlock ImportRootBlock Overview The ImportRootBlock CLI allows the user to bulk import root blocks into IPControl. If not specified. Yes D Description A description of the block.Im portRootBlock Col Field Accepted Values Required C Block size The size of the block in short-notation (e. No K Allocation Reason Description A description of the reason for the allocation. No N Domain Type Specify the domain type for the reverse DNS domain(s) to be created when Create Reverse Domains is “true”. Defaults to system supplied name of Address space/Block size. UDFone=value one |UDFtwo=value two. this field is skipped. No H Regional Internet Registry The Regional Internet Registry this space was obtained from. Multiple pairs can be specified by separating each pair with the ‘|’ character. If not specified. defaults to false.255. Yes. Accepted values are: Generic. 24 for a 255. Yes. This id must be predefined in IPControl. ARIN.g. If not specified. LACNIC. a block type of Any is assumed. defaults to “Default”. Generic is assumed. RFC1918. If the UDF type is Textarea.255. defaults to false. No O User Defined Fields A series of name=value pairs. If not specified. No I Organization Id The organization id for the Regional Internet Registry this space was obtained from. APNIC. Accepted values are true or false. and AFRINIC. No J Allocation Reason The name of a pre-existing Allocation Reason. Accepted values are true or false. If the UDF type is Checkbox. For example. No E Block type The Block Type for the block. the valid values are “on” or “off”.0 network). No G Allow Duplicate Space Whether or not to allow duplicate (overlapping) address space in this block. if required by Container rules M Create Reverse Domains Whether or not to automatically create reverse DNS domain(s) for this block. Use “\n” to separate lines.. No F Block Name A name for the block. Com mand Line Interfaces (CLI) 53 . use “\n” to separate lines. If Allocation Reason is not currently in IPControl. No L SWIP/Net Name SWIP/Net name for the block. RIPE. where the name is the UDF name and the value is desired value. for UDFs defined as required fields. If not specified. such tasks are used to query the current state of the network and perform difference analysis to compare actual deployment with the topology modeled in IPControl.cli. and reports errors to the importerrors. Usage Example This example imports address pools discovered by task 12345. is used to perform this initial population of discovered address pools.diamondip.txt file.cmd –u <userId> -p <pswd> -t <taskId> [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -t <taskId> Yes The Id of the “Collect DHCP Utilization” or “Global Synchronization of DHCP Servers” task. Typically. However. places into the servicesnapshot.reject file any records that could not be imported.netcontrol.sh –u joe –p joepwd –t 12345 54 IPControl CLI and API Guide . $INCHOME/etc/cli/ImportServiceSnapshot. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. during the initial setup of the system the queried information from these tasks can be used to populate the original IPControl model.Im portServiceSnapshot ImportServiceSnapshot Overview The ImportServiceSnapshot CLI allows the user to import address pools discovered by either a “Collect DHCP Utilization” or “Global Synchronization of DHCP Servers” task.ImportServiceSnapshot –u <userId> -p <pswd> -t <taskId> [-?] Via command script (Unix) $INCHOME/etc/cli/ImportServiceSnapshot.sh –u <userId> -p <pswd> -t <taskId> [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportServiceSnapshot. This CLI then. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in. and reports errors to the importerrors.reject file any records that could not be imported.Im portZone ImportZone Overview The ImportZone CLI allows the user to bulk import DNS zones into IPControl.diamondip. Usage Example This example imports zones from the newzones. Note: Zone options are not supported in the first release of this service.txt file.txt CNR Servers Important! For CNR servers.sh –u joe –p joepwd –f newzones. -e <error messages> No The name of the file that error messages will be reported in. Com mand Line Interfaces (CLI) 55 . and to update existing DNS zones.reject –e importerrors.csv -r newzones.csv file. $INCHOME/etc/cli/ImportZone.ipcontrol. either Update Policies (Column R) or Allow Update (Column Q) MUST allow dynamic updates from localhost in order for IPControl to successfully manage the zone without having to overwrite the zone every time the resource records change. places into the newzones.ImportDnsZoneCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportZone.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportZone.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import.cli. See below for the required file format. forward or stub. If not specified. defaults to false. No K Masters For zone types slave and stub only. No M Zone extensions After Specifies the name of the file containing text lines that will be inserted following the resource records for this zone. This field only applies to master zones. Any field not specified on an update is cleared or set to its default value.' No G Filename The name of the zone file that will be generated by IPControl. 56 IPControl CLI and API Guide . the view must exist. It will be ignored for all other zone types. No F View The name of the view in which the new zone will be created. If specified. the “Default” domain type will be used. No E Update Zone Specify true to update an existing zone. Yes C Domain Name Domain name already defined to IPControl Yes D Domain Type Domain type name already defined to IPControl. This field is not valid for other zone types. defaults to true. No J Allow Zone Transfers to DNS Listener Accepted values are true or false. It will be ignored for all other zone types and any zone designated as an Alias zone. If not specified. w ill default to a systemgenerated value based on zone type. specify the master server. Yes for zone types slave and stub L Zone extensions Prior Specifies the name of the file containing text lines that will be inserted prior to the resource records for this zone. If not specified. If not specified. Yes. No Accepted values are true or false. No H Automatic Generation of NS/GLUE Records Accepted values are true or false. slave. B Zone type Specifies the type of zone being imported. If not specified. if GalaxyNa me is not supplied. defaults to true. If not specified.Im portZone File Format Col Field Accepted Values Required A Server The network service name of the DNS Server. false to import a new zone. When true. If not specified. the new zone will be created in the view named 'Default. specify all fields as you would for an import. No I MNAME Specifies an alternative name for the primary or “master” DNS server that DDNS requests should be sent to for this zone. defaults to false. If not specified. No N Template Zone Indicates if the imported zone is intended to be a template zone. no MNAME will be used. This field only applies to master zones. Accepted values are master. defaults to false. P Galaxy Name Q Allow Update ACL Future Use No Specifies the DNS ‘allow -update’ address match list a BIND based server uses to filter DDNS update requests against. The linked template zone will be chosen by using the zone assigned to the template domain to which the alias domain is linked. when Dynamic Zone is true. R S Update Policy Dynamic Zone This field is ignored for non-master zones. This field is ignored for non-master and non-dynamic zones. one of Allow Update ACL or Update Policy must be specified. If not specified. When true. This free text field only applies to master zone types with dynamic updates enabled and is accepted without input validation. See Allow Update ACL No Com mand Line Interfaces (CLI) 57 . Specifies an update policy. Setting this field value to “!BLANK!” on a zone update will serve to completely remove the ‘allow update’ option from the zone. True indicates that this is a dynamic zone. If not specified. defaults to false. Yes. for a dynamic master zone.Im portZone Col Field Accepted Values Required O Alias Zone Indicates if the imported zone is intended to be a alias zone. No Accepted values are true or false. Accepted values are true or false. already defined in IPControl. Setting this field value to “!BLANK!” on a zone update will serve to completely remove the update policy option from the zone. Applicable only for master zones and BIND based servers. you must specify either Update Policy or Allow Update ACL. Usage Example This example imports resource records from the newresourcerecs.Im portZoneResourceRecord ImportZoneResourceRecord Overview The ImportZoneResourceRecord CLI allows the user to bulk import DNS resource records for a zone into IPControl. places into the newresourcerecs. which is used to add records to a domain. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ImportZoneResourceRecord. $INCHOME/etc/cli/ImportZoneResourceRecord.cmd –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the file to import. ImportZoneResourceRecord is only effective when the ‘Automatic Generation of NS/Glue Records’ is set to OFF on the target zone.sh –u joe –p joepwd –f newresourcerecs.cli. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in.ImportZoneResourceRecordCLI –u <userId> -p <pswd> -f <import filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ImportZoneResourceRecord.reject –e importerrors. Note: this interface should not be confused with the ImportDomainResourceRecord CLI. and reports errors to the importerrors.reject file any records that could not be imported.csv –r newresroucerecs.ipcontrol.txt 58 IPControl CLI and API Guide .csv file.diamondip. See below for the required file format. -e <error messages> No The name of the file that error messages will be reported in.txt file. If not specified. The Time To Live. If not specified. F Class The value currently supported is IN. 'Default' will be used. Note that this section is specific to the type of resource record. Yes No Com mand Line Interfaces (CLI) 59 . Note that this section is specific to the type of resource record. Yes H Data The text for the DATA area of the resource record. Accepted values are A and NS. Refer to the appropriate RFC for exact text that should be entered. If supplied the view must exist. Yes D Owner Yes E TTL The OWNER section of the resource record. Yes B View The name of the view for this zone. Refer to the appropriate RFC for exact text that should be entered. defaults to IN. No G Resource Record Type The type of resource record being imported. Yes C Zone The name of the zone. which is the top level domain name.Im portZoneResourceRecord File Format Col Field Accepted Values Required A Server The network service name of the DNS Server. Note that user access control lists (ACL) are enforced. 60 IPControl CLI and API Guide . Users are not allowed to perform exports on data without the appropriate Read rights in the system.Im portZoneResourceRecord Exports Export CLIs allow you to retrieve and filter information from IPControl. or output into a file suitable for modifying and importing. which may affect export results. Data may be viewed on the screen. Specify the CIDR notation of a block. Specify a User Defined Field (UDF) attached to a block.diamondip.0. use a “*” character within “double quotes”. Allows you to filter export based on the block description.. Surround the parameter with double quotes if there is an embedded blank. results are outputted to the screen. If no file name is specified. and value is the value of the UDF. followed by the block size.ExportChildBlockCLI –u <userId> -p <pswd> [-n name] [-i ipaddress>] [-j <interface>] [-d <user defined field name=value>] [-r <ipaddressrange>] [-s <status>] [-b <block>] [-c <container>] [-t <blocktype>] [-f <export-file>] [-pb <parentBlock>] [-pc <parentContainer>] [-h] [-l] [-ex] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportChildBlock. -de “two words”. -de [description] No Filter. separated by a slash ‘/’. -b <block address/size> No Filter. -d <user defined field name=value> No Filter. i.ExportChildBlock ExportChildBlock Overview The ExportChildBlock CLI exports a list of all the Child Blocks into a specified file. 10.0. Also surround the parameter with double quotes if there is an embedded blank in the filter string. -c <container name> No Filter. The wildcard character ‘*’ can be used in the start address only. where name is the name of the UDF.cli.0/24. specify the starting IP address for the block.cmd –u <userId> -p <pswd> [-n name] [-i <ipaddress>] [-j <interface>] [-d <user defined field name=value>] [-r <ipaddressrange>] [-s <status>] [-b <block>] [-c <container>] [-t <blocktype>] [-f <export-file>] [-pb <parentBlock>] [-pc <parentContainer>] [-h] [-l] [-ex] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <export filename> No The name of the file to export the data to.e. Com mand Line Interfaces (CLI) 61 . That is. This file can be modified and then imported using the ImportChildBlock CLI.sh –u <userId> -p <pswd> [-n name] [-i <ipaddress>] [-j <interface>] [-d <user defined field name=value>] [-r <ipaddressrange>] [-s <status>] [-b <block>] [-c <container>] [-t <blocktype>] [-f <export-file>] [-pb <parentBlock>] [-pc <parentContainer>] [-h] [-l] [-ex] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ExportChildBlock. The UDF is specified using the syntax name=value. Specify the name of a specific container or use the wildcard character ‘*’ to perform a partial match on the container name. –d “udfName=value*”. For example. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.ipcontrol. for example. For wildcarding. recursively exports child blocks of the named parent block. Usage Example This example exports all child blocks to the file rbexport. Include this Boolean option for the free blocks to be included in the export.sh –u joe –p joepwd –f rbexport. -st <block status> No Filter.ExportChildBlock Param eter Required Description -ex No -h (--recurse) No -i <IP address> No Filter. the list of exported child blocks will not include the free blocks which are maintained by IPControl. including the tag name for each UDF. The architected UDF column P will contain “Expanded”.16.16. For example.csv. Only valid when accompanied by –pb option. Specify an IP address which falls within the start and end address of a block.0-10.csv in the current directory.0. 62 IPControl CLI and API Guide . -j <Interface> No Filter. with each column’s field name.csv –pb 172. -t <block type> No Filter. $INCHOME/etc/cli/ExportChildBlock. See below for an example.0/23 recursively. Specifying the container can help to avoid ambiguity. aggregate.255.sh –u joe –p joepwd –f rbexport. $INCHOME/etc/cli/ExportChildBlock. Specify the name of the specific block’s parent block’s container.0/23 This example exports all child blocks of the parent block named 172. -l (--includeFreeBlocks) No Flag. Additional columns will be appended for each UDF defined in the exported records. Specify the name of an interface to which the block must be attached. If the block name contains embedded spaces.csv This example exports child blocks that begin with the name MyBlock and that are of block type Private to the file rbexport. A fully qualified container name may be supplied.0/23. Specify the name of the specific block’s parent or starting address followed by /CIDR size -pc <parentContainer> No Filter. the –l option must be used. The format of the range is specified as start-end. Expanded mode. The first row of the file will be a comment header row. $INCHOME/etc/cli/ExportChildBlock. By default. Only valid when –pb is specified. -pb < parentBlock > No Filter.csv –n MyBlock* -t Private Export via parent block name parameter eexample This example exports all child blocks of the parent block named 172. reserved. Specify a range of IP addresses which span one or more blocks. Specify the name of a specific block type or use the wildcard character ‘*’ to perform a partial match on the block type name.0. When present. subnet.0. beginning with “^”. surround the name with double-quotes “ “.0.sh –u joe –p joepwd –f rbexport. Note: if blocks of status ‘free’ are desired.16. Specify the name of a specific block or use the wildcard character ‘*’ to perform a partial match on the name.0. Specify the block status. -n <block name> No Filter. 10. -r <IP address range> No Filter. {free.255.0. fullyassigned}. as in row 2 column AD.csv –pb 172. In this example. Short format example: Dallas. Long format eliminates ambiguity in cases where there are duplicate container names.0.csv –c CA –ex Here is the output file: Note the following: The first row is a header line. the cell will be blank. $INCHOME/etc/cli/ExportChildBlock.16.sh –u joe –p joepwd –f rbexport. columns AB-AD contain the values for the user defined fields. with the output in expanded format. Row 3 has no user defined fields defined for that block.0/23 contained in container /InControl/Canada/North. Yes Com mand Line Interfaces (CLI) 63 .16.ExportChildBlock $INCHOME/etc/cli/ExportChildBlock. Note: This is the same format that the ImportChildBlock CLI requires. Only those user defined field tags defined for the blocks exported (based on container and blockType) will have columns in the output file.0. The column headers beyond the architected column AA contain the user defined field tags.0/23 -h This example exports all child blocks of the parent block named 172. Long format example: IPControl/Texas/Dallas. Names can be in either short or long format. Column P contains “Expanded” when the row includes user defined fields beyond column AA. $INCHOME/etc/cli/ExportChildBlock. If there is no value.16.0. Col Field Accepted Values Required A Container The name of the container that will hold the block.sh –u joe –p joepwd –f rbexport. You can use ImportChildBlock to import an expanded format exported file by using the –o (overwrite) parameter.0/23” –pc “/InControl/Canada/North” Export using expanded format example This example exports all child blocks in the container named CA. File Format The format for the export file is as follows.csv –pb “172. beginning with “^”.sh –u joe –p joepwd –f cexport. 2|10. No L Interface Name If this block is being added to a device container. For example. No G Current Status The current status of the block. If no address block is specified. No F Description A description of the block. Yes | No If an IPV6 block is exported. Yes. Reserved. M Interface Offset or Address The specific address(es) for the interface IP address(s). 24 for a 255. No D Block Name A name for the block.g. Otherwise. Defaults to system supplied name of Address space/Block size.0. No O Domain Type Specify the domain type for the reverse DNS domain(s) to be created when Create Reverse Domains is “true”. No K Allocation Template If this block is being added to a device container with blockStatus=Deployed. Accepted values are: Deployed. the name of the interface to attach the block to. Yes H SWIP Name SWIP name for the block. Aggregate.0.0.ExportChildBlock Col Field Accepted Values Required B Block size | IPV6 The size of the block in short-notation (e.0 network). defaults to false.0. the block size will be followed by “|true”. No 64 IPControl CLI and API Guide . If Allocation Reason is not currently in IPControl.255.. C Block type The Block Type for the block If not specified. Multiple addresses will be separated by the ‘|’ character. Accepted values are true or false. no.1|10. An offset of 1 is assumed if none is specified. No E Address Block The address block to allocate. this field is skipped. if required by Container rules I Allocation Reason The name of a pre-existing Allocation Reason. for IPV4 “|false”. the name of the allocation template to use to create address pools from the newly created block.3 No. if block is being added to device container. No J Allocation Reason Description A description of the reason for the allocation. Yes. space will be auto-allocated. defaults to “Default”. 10.0. a block type of Any is assumed. Wrap the statement in “quotes” if it contains any commas. If not specified.255. N Create Reverse Domains Whether or not to automatically create reverse DNS domain(s) for this block. FullyAssigned.0. If not specified. For example: No hr.com is of type ‘External’. R DHCP Option Set The name of a DHCP Option Set defined within IPControl that should apply to this subnet. If not specified. hr. No Valid only for Deployed blocks.com. No V Primary DHCP Server The name or IP Address of the primary DHCP server for this address space. Multiple pairs can be specified by separating each pair with the ‘|’ character. No T DNS Servers The list of default DNS Servers for this subnet. Yes. Valid only for Deployed blocks. If the UDF type is Checkbox. Valid only for Deployed blocks. This list is supplied to DHCP clients on this subnet. Com mand Line Interfaces (CLI) 65 . This address is supplied to DHCP clients on this subnet. where the name is the UDF name and the value is desired value. Valid only for Deployed blocks. specify the domain followed by ‘/’ followed by the domain type. Accepted values are true or false. For multiple servers. No S DHCP Policy Set The name of a DHCP Policy Set defined within IPControl that should apply to this subnet. See below for an example of the results.ins. Valid only for Deployed blocks. defaults to false. and dmz. separated by a vertical bar (|). separate the server names with a vertical bar (|). Q Exclude From Discovery Flag indicating if this subnet should be included in Host Discovery tasks.com uses the default domain type. When this column contains the word “Expanded”./External In this example. the –ex option was invoked. This list will appear in the GUI when choosing domains for devices. Valid only for Deployed blocks.|dmz. No U Default Gateway The default gateway address for this subnet. No X DNS Forward Domains The list of DNS Forward domains for this address space. No W Failover DHCP Server The name or IP Address of the failover DHCP Server for this address space. To specify a domain type. Valid only for Deployed blocks.ExportChildBlock Col Field Accepted Values Required P User Defined Fields A series of name=value pairs.com. Valid only for Deployed blocks.ins. The server name or IP Address is valid. For example. UDFone=value one |UDFtwo=value two. for UDFs defined as required fields. the valid values are “on” or “off”. 0-15. Flag indicating if this subnet is primary. specify the domain followed by ‘/’ followed by the domain type. This list will appear in the GUI when choosing domains for devices.ExportChildBlock Col Field Accepted Values Required Y DNS Reverse Domains The list of DNS Reverse domains for this address space. Multiple WINS servers may be specified. Z Primary WINS Server AA Allocation Strategy AB Primary Subnet 66 IPControl CLI and API Guide The IP Address of the Primary WINS Server for this subnet. For example: No 0-15.in-addr. uses the default domain type.10. is of type ‘External’.inaddr. Valid only for Deployed blocks in device containers.0. To specify a domain type.10.in-addr.arpa. /External |40. Valid only for Deployed blocks.1.arpa. separated by a comma.in-addr.10.0. Accepted values are true or false. Exported with no value as a place holder for consistency with ImportChildBlock. No No No .arpa. Used to provide this information to DHCP for Dynamic Address types.arpa.1. separated by a vertical bar (|).0. and 40.10. In this example. use a “*” character w ithin “double quotes”.cli. NOTE: if both –n and –d are specified. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u <userId> -p <pswd> [-f <export filename>] [-n containerName] [-d udfName=value] [-fp] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ExportContainer. This file can be modified and then imported using the ImportContainer CLI. If omitted. Allows you to filter export based the user defined field name and value.diamondip. Also surround the parameter with single quotes if there is an embedded blank in the filter string. Usage Examples This example exports all containers to the file named exportcontainer.e. $INCHOME/etc/cli/ExportContainer.csv This example exports all containers whose name starts with the characters West. the export includes containers that satisfy both criteria.csv file in the current directory. Allows you to filter export based on the name of the container. -fp No Populates the parent container field using the long format. Only containers that have this UDF set to this value will be exported.ExportContainer ExportContainer Overview The ExportContainer CLI exports containers into a specified file.e. the export includes containers that satisfy both criteria. -d [udfName=value] No Filter. i. –d “udfName=value*”. Com mand Line Interfaces (CLI) 67 ...sh –u joe –p joepwd –f exportcontainer. results are sent to the screen.cmd –u <userId> -p <pswd> [-f <export filename>] [-n containerName] [-d udfName=value] [-fp] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <export filename> No The name of the file to export the data to.ExportContainerCLI –u <userId> -p <pswd> [-f <export filename>] [-n containerName] [-d udfName=value] [-fp] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportContainer. Use a “*” character (within ‘single quotes’. for example: IPControl/Texas/Dallas -v No Produces verbose output. i. –n ‘ContainerName*’) for wildcarding. -n [containerName] No Filter. For wildcarding. NOTE: if both –n and –d are specified.ipcontrol. Note: This is the same format that the ImportContainer CLI requires.csv –n “West*” This example exports all containers that have a UDF named customer with the value 12345. Device types that with an associated information template have the template name concatenated to the device type name. separated by ‘/’. . separated by a ‘|’.ExportContainer $INCHOME/etc/cli/ExportContainer.csv –d customer=12345 File Format The format for the export file is as follows. Block types that with an associated information template have the template name concatenated to the block type name. The history records are created each time the Global Utilization Rollup task is run. Multiple values are separated by a vertical bar (“|”). separated by a ‘|’. C Parent Container The name of the parent container for this container. K User Defined Fields User defined field values. For example: fieldOne=valueOne|fieldTwo=valueTwo If the UDF type is Checkbox. in name=value format. separated by ‘/’. $INCHOME/etc/cli/ExportContainer. L Maintain History Records 68 IPControl CLI and API Guide Indicates whether or not Container History and Block History records will be kept for all appropriate block types. E Rule1 A listing of the valid block types for this container. Col Field Accepted Values Col Field Accepted Values A Container Name The name of the container. D Container Type Either logical or device. separated by ‘/’. F Rule2 A listing of the block types enabled for root block creation. separated by ‘/’. separated by ‘/’.sh –u joe –p joepwd –f exportcontainer. the list will contain the keyword NONE. B Container Description A brief description of the container. Accepted values are “true” or “false”. G Rule3 A listing of the block types that can be used for space allocation from the parent container. the valid values are “on” or “off”. J Information Template The name of a pre-existing information template to be associated with this container. If no device types are allowed. I Rule5 A listing of the valid device types for this container. H Rule4 A listing of the block types for which SWIP Names are required.sh –u joe –p joepwd –f exportcontainer. Accepted values are: Static. For wildcarding.ExportDevice ExportDevice Overview The ExportDevice CLI exports a list of all the Devices into a specified file. i. This file can be modified and then imported using the ImportDevice CLI.ExportDeviceCLI –u <userId> -p <pswd> [-f <export filename>] [-i ipaddress] [-n deviceName] [-d udfName=value] [-m domainName] [-r ipaddress1/ipaddress2] [-e devicetype] [-b blockName] [-c containerName] [-t blocktype] [-ex] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportDevice. Allows you to filter export based on block name. Com mand Line Interfaces (CLI) 69 . For DHCP V6: Dynamic NA DHCPv6. results are outputted to the screen. Automatic DHCP. Allows you to filter export based on the user defined name and value of the device.diamondip. Dynamic TA DHCPv6 and Automatic TA DHCPv6.e. Dynamic DHCP. Automatic NA DHCPv6. -at [addressType] No Filter. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. –d “udfName=value*”. -b [blockName] No Filer. Manual NA DHCPv6. -c [containerName] No Filter. -d [udfName=value] No Filter. If no file name is specified.ipcontrol..cli. Allows you to filter export based on address type. Manual DHCP.sh –u <userId> -p <pswd> [-f <export filename>] [-i ipaddress] [-n deviceName] [-d udfName=value] [-m domainName] [-r ipaddress1/ipaddress2] [-e devicetype] [-b blockName] [-c containerName] [-t blocktype] [-ex] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ExportDevice. Interface and Reserved.cmd –u <userId> -p <pswd> [-f <export filename>] [-i ipaddress] [-n deviceName] [-d udfName=value] [-m domainName] [-r ipaddress1/ipaddress2] [-e devicetype] [-b blockName] [-c containerName] [-t blocktype] [-ex] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <export filename> No The name of the file to export the data to. Allows you to filter export based on the name of the container the device is located in. use a “*” character within “double quotes”. Also surround the parameter with double quotes if there is an embedded blank in the filter string. 0. Allows you to filter export based on the device description.0. Allows you to filter export based the user device type name. The architected UDF column L will contain “Expanded”. -hw [mac address] No Filter. -h No Filter. Usage Examples This example exports all devices to file named exportdevice.200 This example exports devices that are located in the container named Exton to the file exportdevice. with each column’s filed name. -v No Produces verbose output. Allows you to filter export based on an address range between ipaddress1 and ipaddress2 inclusive. Allows you to filter export based the domain name. -r [ipaddress1/ipaddress2] No Filter.0.1/10. -vf [true|false] No Filter.0.csv –r 10.sh –u joe –p joepwd –f exportdevice. Must be accompanied with –c parameter. including the tag name for each UDF.csv.200 inclusive.csv This example exports devices that contain an IP address within the range of 10.0.csv. Allows you to filter export based on virtual flag.sh –u joe –p joepwd –f exportdevice. The first row of the file will be a comment header row. -i [ipaddress] No Filter. $INCHOME/etc/cli/ExportDevice. beginning with “^”.csv in the current directory. $INCHOME/etc/cli/ExportDevice.0. Additional columns will be appended for each UDF defined in the exported records. -m [domain] No Filter. See below for an example.csv –c Exton 70 IPControl CLI and API Guide . Specifies to recursively include all devices contained in child containers of specified –c parameter filter. -n [name] No Filter.sh –u joe –p joepwd –f exportdevice.ExportDevice Param eter Required Description -de [description] No Filter. to the file exportdevice. Allows you to filter export based on the device hostname. Allows you to filter export based on block type name. -ex No Expanded mode. -t [blocktype] No Filter. $INCHOME/etc/cli/ExportDevice.0. Allows you to filter export based the ipaddress.1 through 10. -e [devicetype] No Filter.0. Allows you to filter export based on the MAC Address. In this example. Column L contains “Expanded” when the row includes user defined fields beyond column R. When deviceType=PC. when deviceType=Router or Printer.sh –u joe –p joepwd –f cexportdevice. Com mand Line Interfaces (CLI) 71 . columns S-V are used. W and X are used. the cell will be blank. $INCHOME/etc/cli/ExportDevice. Only those user defined field tags defined for the devices exported (based on container and deviceType) will have columns in the output file. You can use ImportDevice to import an expanded format exported file by using the –o (overwrite) parameter. beginning with “^”. The column headers beyond the architected column R contain the user defined field tags. as in row 6 column U. with the output in expanded format. Row 5 has no user defined fields defined for that device. In this example.csv –c Pennsylvania –ex Here is the output file: Note the following: The first row is a header line.ExportDevice Export using expanded format example This example exports devices in the container named Pennsylvania. columns S-X contain the values for the user defined fields. If there is no value. Yes E Hardware Type The device’s hardware type. Note: This is the same format that the ImportDevice CLI requires.ExportDevice File Format The format for the export file is as follows. No I Container Name The container name the device is located in. No Q Virtual Indicates a virtual address No R DUID DHCP Unique Identifier No 72 IPControl CLI and API Guide . No O Interface Names The device’s interface names No P Exclude from Discovery flags The flags for excluding the device’s IP addresses from host discovery. the –ex option was invoked. ‘true’ if not. Col Field Accepted Values Required A IP Address The IP address of the device and its device interfaces delimited by ‘|’. Yes J Domain Type The device’s domain type. No L User Defined Fields The device’s user defined field and values delimited by ‘|’. No H Domain Name The device’s domain name. M Aliases The device’s alias names No N Duplicate warning ‘False’ if this is a duplicate. Yes C Hostname The hostname of the device. See below for an example of the results. Yes B Address Type The Address type of the device. ‘false’ if not. No When this column contains the word “Expanded”. No F Mac Address The Mac Address of the device and its device interfaces delimited by ‘|’ No G Resource Record Flag “true” if the device is to automatically create an ‘A’ or ‘AAAA’ record upon import. Yes D Device Type The device’s device type. No K Description The device’s description. Allows you to filter export based the user device type name. No Filter.cmd –u <userId> -p <pswd> [-f <export filename>] [-i ipaddress] [-n deviceName] [-d udfName=value] [-m domainName] [-a domaintype] [-r ipaddress1/ipaddress2] [-e devicetype] [-b blockName] [-c containerName] [-t blocktype] [-h] [-o option] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help No The name of the file to export the data to. Allows you to filter export based on the domain name of the device.sh –u <userId> -p <pswd> [-f <export filename>] [-i ipaddress] [-n deviceName] [-d udfName=value] [-m domainName] [-a domaintype] [-r ipaddress1/ipaddress2] [-e devicetype] [-b blockName] [-c containerName] [-t blocktype] [-h] [-o option] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ExportDeviceResourceRecord. No Filter. If no file name is specified. results are outputted to the screen. This file can be modified and then used with the ImportDeviceResourceRecord CLI or the ModifyDeviceResourceRecord CLI. No Filter.cli. Allows you to filter export based on the name of the container the device is located in. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.ExportDeviceResourceRecordCLI –u <userId> -p <pswd> [-f <export filename>] [-i ipaddress] [-n deviceName] [-d udfName=value] [-m domainName] [-a domaintype] [-r ipaddress1/ipaddress2] [-e devicetype] [-b blockName] [-c containerName] [-t blocktype] [-h] [-o option] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportDeviceResourceRecord. Allows you to filter export based the user defined name and value the device owns. Allows you to filter export based the device’s IP Address.diamondip.ExportDeviceResourceRecord ExportDeviceResourceRecord Overview The ExportDeviceResourceRecord CLI exports a list of the resource records for a device or group of devices into a specified file. This export will only include resource records (regardless of type) that are visible on the device’s Resource Record tab within the user interface. No Filter. No Filter. Allows you to filter export based on the domain type of the device. -f <export filename> -c <containerName> -d <udfName=value> -e <devicetype> -i <ipaddress> -m <domain> -a <domaintype> Com mand Line Interfaces (CLI) 73 . No Filter.ipcontrol. “Exception in thread "main" java. The output is formatted for the ModifyDeviceResourceRecord CLI. $INCHOME/etc/cli/ExportDeviceResourceRecord.csv in the current directory. use I. No To specify that the export output should be in the format used by ImportDeviceResourceRecord. Allows you to filter export based on the device hostname. Use M for the ModifyDeviceResourceRecord format. Allows you to filter export based on an address range between ipaddress1 and ipaddress2 inclusive. -t <blocktype> No Filter. $INCHOME/etc/cli/ExportDeviceResourceRecord.0.csv in the current directory.csv This example exports all device resource records (that appear on the device’s Resource Record tab within the user interface) for the device with hostname switch00024 to a file named exportdevicerr. The output is formatted for the ModifyDeviceResourceRecord CLI. $INCHOME/etc/cli/ExportDeviceResourceRecord. -h -o <option> -s <batch-size> -v Usage Examples This example exports all device resource records (that appear on the device’s Resource Record tab within the user interface) for the device at 10.0. No Produces verbose output. No Filter.0.csv in the current directory.OutOfMemoryError: Java heap space”.ExportDeviceResourceRecord Param eter Required Description -n <name> No Filter.sh –u joe –p joepwd –n switch00024 –f exportdevicerr.24. You can also edit the command file and change the –Xmx parameter.lang. -b <blockName> No Filter. -r <ipaddress1/ipaddress2> No Filter.csv –o M This example exports all device resource records (that appear on a device’s Resource Record tab within the user interface) for devices located in container Exton to a file named exportdevicerr. The output is formatted for the ImportDeviceResourceRecord CLI. for example. The default batch size for each call to the web service is 1000 devices. If you receive the error. Specifies to recursively include all devices contained in child containers of specified –c parameter filter.0. you can use this parameter to specify a smaller batch size. Allows you to filter export based on block type name.sh –u joe –p joepwd –i 10. No There can be a very large number of resource records exported with this command.csv –o M 74 IPControl CLI and API Guide . Must be accompanied with –c parameter. to a file named exportdevicerr. Allows you to filter export based on block name.sh –u joe –p joepwd –c Exton exportdevicerr. The default is I. -s 500.24 –f exportdevicerr. The set following the colon specifies the values to be changed.comment= ipAddress=10.com.0.domain=mycompany.in-addr.24.comment= ipAddress=10.do mainType=External. If not specified. G TTL The Time To Live.owner=switch00026.com.com.0.comment= ipAddress=10.24. The format for the export file when “–o M” is specified will be of the format that the ModifyDeviceResourceRecord CLI requires.data=switch 00026. suppose a device at 10.do mainType=Default.container=IPControl/Texas/Dallas.TTL=2400.0.0.24.arpa.domainType=Default.24 has 4 resource records (that appear on the device’s Resource Record tab within the user interface).resourceRecType=PTR:owner=24. All of the values that can be modified are exported. E IP Address The IP Address of the Device.com .resourceRecType=A:owner=switch00026.in-addr.0. I Resource Record Type The type of resource record. Defaults to “Default” C Owner The OWNER section of the resource record.TTL=2400. Note that this section is specific to the type of resource record. The set of attribute-value pairs before the colon identifies the record to be changed.0.domain=10.0.ExportNetElement File Format The format for the export file when “–o I” is specified is as follows.domainType=External.0.domain=mycompany.0.0. Refer to the appropriate RFC for exact text that should be entered.domainType=Default.resourceRecType=A.in-addr.container=IPControl/Texas/Dallas. H Class The value currently supported is IN.TTL=2400.domainType=Default.0.in-addr.domain=10.com.0.24.0.owner=24.domain=10. defaults to IN. Note that this section is specific to the type of resource record.resourceRecType=A.domain=10. Note: This is the same format that the ImportDeviceResourceRecord CLI requires. K Comment Text appended to the resource record. Refer to the appropriate RFC for exact text that should be entered. 0.domain=mycompany.mycompany.arpa.arpa.0. F Container The name of the container that holds the device.owner=24.owner=switch00026. ipAddress=10.24.domainType=External.arpa.0. B Domain Type The name of the domain type to which the domain belongs.0.domain=mycompany.0.data=10.0.0.data=switch0 0026. D Host Name The device host name.com .container=IPControl/Texas/Dallas.0.mycompany.data=10 . J Data The text for the DATA area of the resource record. This is required only if there is overlapping address space in use and the ip address is in overlapping space.resourceRecType=PTR.TTL=2400.resourceRecType=PTR:owner=24.24.domainType=External. Col Field Accepted Values A Domain The name of the domain to which the resource records belongs. The container is then used to uniquely determine the device.0.comment= Com mand Line Interfaces (CLI) 75 .container=IPControl/Texas/Dallas. For example.resourceRecType=PTR.resourceRecType=A:owner=switch00026. -globalSync <Y|N> No Filter. If no file name is specified. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. Allows you to filter export based on specific fields.cmd –u <userId> -p <pswd> [-f <export filename>] [-n <NetElement Name>] [-i <IP Address or host name>] [-vendor <Network Element vendor>] [-model <Network Element model>] [-e <Element type>] [-globalSync <Y|N>] [-agent <Agent Name>] [-c <Container Name>] [-s batch-size] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <export filename> No The name of the file to export the data to.diamondip. Allows you to filter export based on specific fields. Allows you to filter export based on specific fields.sh –u <userId> -p <pswd> [-f <export filename>] [-n <NetElement Name>] [-i <IP Address or host name>] [-vendor <Network Element vendor>] [-model <Network Element model>] [-e <Element type>] [-globalSync <Y|N>] [-agent <Agent Name>] [-c <Container Name>] [-s batch-size] [-?] Via command script (Windows) %INCHOME%/etc/cli/ExportNetElement. “exton closet “. If the network element name contains embedded spaces. -model <Network Element model> No Filter. for example. If the model name contains embedded spaces. If the vendor name contains embedded spaces. 76 IPControl CLI and API Guide .netcontrol. -vendor <Network Element vendor> No Filter. See file format for accepted values. -i <IP Address or host name> No Filter.ExportNetElement ExportNetElement Overview The ExportNetElement CLI exports a list of all the Network Elements into a specified file. Allows you to filter export based on specific fields.cli. surround the name with double-quotes. Allows you to filter export based on specific fields. surround the name with double-quotes. See file format for accepted values. Allows you to filter export based on specific fields. See file format for accepted values. -e <Element type> No Filter. See file format for accepted values. surround the name with double-quotes. See file format for accepted values.ExportNetElementCLI –u <userId> -p <pswd> [-f <export filename>] [-n <NetElement Name>] [-i <IP Address or host name>] [-vendor <Network Element vendor>] [-model <Network Element model>] [-e <Element type>] [-globalSync <Y|N>] [-agent <Agent Name>] [-c <Container Name>] [-s batch-size] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportNetElement. See file format for accepted values. -n <NetElement Name> No Filter. results are outputted to the screen. This file can be modified and then imported using the ImportNetElement CLI. $INCHOME/etc/cli/ExportNetElement. This can be any combination of letters and numbers. See file format for accepted values. Yes E Type The type of Network Element.ExportNetElement Param eter Required Description -agent <Agent Name> No Filter. Col Field Accepted Values Required A Name The name of the Network Element. surround the name with double-quotes. -o No The format option is not implemented in this CLI. router. $INCHOME/etc/cli/ExportNetElement. Allows you to filter export based on specific fields. for example. Yes F Global Sync Whether or not to include this Network Element in the Global Sync process. A user name used to telnet to this device.csv This example exports Cisco network elements that are not included in the GlobalSync process to the file neexport. If the container name contains embedded spaces. Note: This is the same format that the ImportNetElement CLI requires. -c <Container Name> No Filter. Allows you to filter export based on container. Yes B IP Address/FQDN The IP address or fully-qualified domain name (FQDN) of the Network Element.csv –globalSync N –vendor “Cisco Systems” File Format The format for the export file is as follows. I Telnet password A password used by the telnet user to telnet to this device.csv file in the current directory. Yes C Vendor The vendor of the Network Element. or vpn. No J Enable password Password used to enter “enabled” or “privileged” mode on the device.csv. “New York “. Usage Example This example exports all network elements to an neexport. No No Com mand Line Interfaces (CLI) 77 . or a fully-qualified host name. No K Read community string The community string used by SNMP to read details from this network element. Yes D Model The model name of the Network Element. No L Interfaces A list of enabled interfaces. switch.sh –u joe –p joepwd –f neexport. -s No The batch size option is not implemented in this CLI.sh –u joe –p joepwd –f neexport. -v No Provides verbose output. If the agent name contains embedded spaces. Accepted values are True or False (case insensitive). This must be a valid IPv4 or IPv6 IP address. Yes G Agent Name Yes H Telnet user The exact name of the IPControl Agent that’s responsible for contacting this Network Service. Accepted values are CMTS. surround the name with double-quotes. Blank if V1 or no SNMP. Blank if V1 or no SNMP No Q V3 Privacy Password Privacy Password.ExportNetElement Col Field Accepted Values Required M V3 Username Required if using SNMP V3. Blank if V1 or no SNMP No O V3 Authentication Password Authentication password. Blank if V1 or no SNMP No 78 IPControl CLI and API Guide . No N V3 Authentication Protocol Either MD5 or SHA1. Blank if V1 or no SNMP No P V3 Privacy Protocol Privacy Protocol. Blank if V1 or no SNMP No S V3 Engine ID SNMP V3 Engine ID. Blank if V1 or no SNMP No R V3 Context Name SNMP V3 Context name. ExportNetServiceCLI –u <userId> -p <pswd> [-f <export filename>] [-name <NetService Name>] [-address <IP Address or host name>] [-type <NetService Type>] [-product <Product name>] [-agent <Agent name>] [-globalsync <Y|N>] [-s batch-size] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportNetService. Allows you to filter export based on specific fields. If no file name is specified. Allows you to filter export based on specific fields. in CSV format. for example. for example.x“.cli.ExportNetService ExportNetService Overview The ExportNetService CLI exports a list of all the DHCP Network Services into a specified file. See file format for accepted values. -name <NetService Name> No Filter.netcontrol. Allows you to filter export based on specific fields. results are outputted to the screen. surround the name with double-quotes. If the agent name contains embedded spaces. This file can be modified and then imported using the ImportNetService CLI. See file format for accepted values. If the product name contains embedded spaces.cmd –u <userId> -p <pswd> [-f <export filename>] [-name <NetService Name>] [-address <IP Address or host name>] [-type <NetService Type>] [-product <Product name>] [-agent <Agent name>] [-globalsync <Y|N>] [-s batch-size] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <export filename> No The name of the file to export the data to. “Executive Agent”. “ISC DHCP 3.sh –u <userId> -p <pswd> [-f <export filename>] [-name <NetService Name>] [-address <IP Address or host name>] [-type <NetService Type>] [-product <Product name>] [-agent <Agent name>] [-globalsync <Y|N>] [-s batch-size] [-?] Via command script (Windows) %INCHOME%/etc/cli/ExportNetService. Com mand Line Interfaces (CLI) 79 . -product <Product name> No Filter.diamondip. surround the name with double-quotes. -address <IP Address or host name> No Filter. See file format for accepted values. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. -agent <Agent name> No Filter. See file format for accepted values. Allows you to filter export based on specific fields. -v No Provides verbose output. Yes C Type The type of Network Service. This must be a valid IPv4 or IPv6 IP address. Exported as “password”. $INCHOME/etc/cli/ExportNetService. INS DHCP or CNR DHCP. This must be a value already defined in IPControl. for example. Used in conjunction with the ‘User name for collection’. Yes B IP Address/FQDN The IP address or fully-qualified domain name (FQDN) of the Network Service.sh –u joe –p joepwd –product “INS DHCP” File Format The format for the export file is as follows.ExportNetService -c <Container Name> No Filter.csv This example exports network services using the product INS DHCP to the standard output (usually screen). Exported as “username”.sh –u joe –p joepwd –f nsexport. Yes 80 IPControl CLI and API Guide . This can be any combination of letters and numbers. Usage Example This example exports network services to an nsexport. If the container name contains embedded spaces. Col Field Accepted Values Required A Name The name of the Network Service. Yes F Global Sync Whether or not to include this Network Service in the Global Sync process. $INCHOME/etc/cli/ExportNetService. Accepted values are scp or ftp. Note: This is the same format that the ImportNetService CLI requires.globalsync <Y|N> No Filter. or a fully-qualified host name. -type No The type option is not implemented in this CLI. Allows you to filter export based on container. This is always dhcp. “New York “. . -s No The batch size option is not implemented in this CLI. Yes E Agent name The exact name of the IPControl Agent that’s responsible for contacting this Network Service. for example.csv file in the current directory. Allows you to filter export based on specific fields. surround the name with double-quotes. Accepted values are True or False (case insensitive). -o No The format option is not implemented in this CLI. Yes H User name for collection The username used by the collection method (scp or ftp) to log in to the remote server. Yes I Password for collection The password used by the collection method (scp or ftp) to log in to the remote server. Yes G Collection Method The method by which the IPControl Agent will collect data from the Network Service. No D Product name The Network Service product name. See file format for accepted values. No For collection types qip. Provide warnings when usage of a pool assigned to this service is exceeded. the NRCMD password and the Cluster Name. For example. If no value is specified.conf |/opt/qip/dhcp/dhcp. Com mand Line Interfaces (CLI) 81 . /opt/cnr/bin/nrcmd|myuserid|mypass| cluster1 M WarningThreshold Default scope utilization warning threshold. Each item of information is specified in this single field by separating each field with the ‘|’ character. No Note: The CLI does not export columns H or I since these could contain sensitive information. adc. No K Container(s) No longer used. this will default to 90. If no value is specified.db For collection type cnr. the information includes the Path/Executable of NRCD command. the information includes the DHCP Configuration file pathname and DHCP Active Lease file pathname.ExportNetService Col Field Accepted Values Required J Collection port The port number the collection method (scp or ftp) is listening on. msft and isc. /opt/qip/dhcp/dhcpd. For example. the NRCMD user id. L VendorInfo Vendor specific information for the product’s collection type.conf |c:\qip\dhcp\dhcp. and 21 if the collection method is ftp. The columns are preserved to maintain conformity with the ImportNetService CLI.db or c:\qip\dhcp\dhcpd. this will default to 22 if the collection method is scp. in CSV format. -name <Prefix Pool Name> No Filter. -netservice <DHCP Server Name> No Filter.sh –u <userId> -p <pswd> [-f <export filename>] [-name <Prefix Pool Name>] [-ipaddress <IP Address>] [-container <Container Name>] [-ipaddressrange <Contained IP Address Range IPAddress/length>] [-netservice <DHCP Server Name>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ExportPrefixPool. results are outputted to the screen. If no file name is specified. Allows you to filter export based on whether a range of values falls within the prefix pool. -ipaddress <IP Address> No Filter. 82 IPControl CLI and API Guide . -container <Container name> No Filter.ipcontrol.ExportPrefixPoolCLI –u <userId> -p <pswd> [-f <export filename>] [-name <Prefix Pool Name>] [-ipaddress <IP Address>] [-container <Container Name>] [-ipaddressrange <Contained IP Address Range IPAddress/length>] [-netservice <DHCP Server Name>] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportPrefixPool.cli. Allows you to filter export based on a DHCP server assigned to that prefix pool. -ipaddressrange < IP Address /length> No Filter. Allows you to filter export based on which pools live in a specific container. Allows you to filter export based on specific fields.ExportPrefixPool ExportPrefixPool Overview The ExportPrefixPool CLI exports a list of all the V6 Prefix Pools into a specified file. See file format for accepted values.diamondip. This file can be modified and then imported using the ImportPrefixPool CLI. Allows you to filter export based on what pools contain this specific address. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.cmd –u <userId> -p <pswd> [-f <export filename>] [-name <Prefix Pool Name>] [-ipaddress <IP Address>] [-container <Container Name>] [-ipaddressrange <Contained IP Address Range IPAddress/length>] [-netservice <DHCP Server Name>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> No The name of the file to export the data to. The range should be of the format IPAddress/length. ExportPrefixPool Usage Example This example exports network services to an prefixpoolexport. Separate the list entries with a vertical bar “|”. Defaults to “Start Address/Length” E Container The name of the container that holds the block in which the pool is defined. Note: This is the same format that the ImportPrefixPool CLI requires. Yes G Longest Prefix Length The longest prefix length allowed for delegated prefixes. This address must be in a block with an In-Use/Deployed status. F Delegated Prefix Length The default length of the delegated prefix. specify: No denyA|denyB Com mand Line Interfaces (CLI) 83 . No.sh –u joe –p joepwd –netservice “INS DHCP” File Format The format for the export file is as follows. No L Allow DHCP Client Classes A list of Client Classes that are allowed in this address pool. No K DHCP Policy Set The name of a Policy Set used with this pool. For example. No H Shortest Prefix Length The shortest prefix length allowed for delegated prefixes.sh –u joe –p joepwd –f prefixpoolexport. $INCHOME/etc/cli/ExportPrefixPool. CNR DHCP only. No I Primary Net Service The name of the DHCP server that will serve addresses from this pool No J DHCP Option Set The name of an Option Set used with this pool. specify: No No allowA|allowB M Deny DHCP Client Classes A list of Client Classes that are NOT allowed in this address pools. to allow two client classes named “allowA” and “allowB”. For example. Yes C Address Pool Type Yes D Name One of “Dynamic PD DHCPv6” or “Automatic PD DHCPv6”. and the start address is in overlapping space. Separate the list entries with a vertical bar “|”.csv file in the current directory. to disallow two client classes named “denyA” and “denyB”. $INCHOME/etc/cli/ExportNetService. Yes B Length The length of the prefix pool. CNR DHCP only. unless Start address is not unique. Prefix Pool name. Col Field Accepted Values Required A Start Address The IP Address of the first address in the pool. The container is then used to uniquely determine the block that will contain the address pool.csv This example exports prefixpools using the netservice INS DHCP to the standard output (usually screen). This is required only if there is overlapping address space in use. sh –u <userId> -p <pswd> [-f <export filename>] [-m <domain>] [-a <domaintype>] [-q <requesting admin>] [-x <action>] [-v] [-?] Via command script (Window s) %INCHOME%/etc/cli/ExportResourceRecordPendingApproval. Allows you to filter export based on the domain type of the resource record. No Filter. “update” or “delete” a resource record. No Filter. results are written to the screen. These updates include those to create. or delete a resource record. -v No Produces verbose output. -x <action> No Filter. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.diamondip. Allows you to filter export based on the domain name of the resource record. The list of workflow ids included in the exported information can then be used with the ModifyPendingApproval CLI by an administrator with approval authority to approve or reject the requested changes. The domain names of the exported records will contain the specified value.cmd –u <userId> -p <pswd> [-f <export filename>] [-m <domain>] [-a <domaintype>] [-q <requesting admin>] [-x <action>] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help No The name of the file to export the data to. No Filter.cli. update.ipcontrol. -f <export filename> -m <domain> -a <domaintype> -q <requesting admin> 84 IPControl CLI and API Guide . Allows an approving administrator to filter the export based on the login id of the administrator requesting the resource record change.ExportResourceRecordPendingApprovalCLI –u <userId> -p <pswd> [-f <export filename>] [-m <domain>] [-a <domaintype>] [-q <requesting admin>] [-x <action>] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportResourceRecordPendingApproval. If not specified.ExportResourceRecordPendingApproval ExportResourceRecordPendingApproval Overview The ExportResourceRecordPendingApproval CLI exports a list of the resource record updates that are waiting for approval by the invoking administrator. Allows you to filter export based on the request to “create”. RouterSevenWest.com. 2009-07-17 21:32:22.CNAME.example.A.ExportResourceRecordPendingApproval Usage Examples This example exports all resource records that are in a pending approval state for administrator joe to a file named exportpending.oldcomment->newcomment 1020.sh –u joe –p joepwd –f exportpending.example.3.Default. H TTL The Time To Live. The following example exports all resource records that are in a pending state for administrator joe .CNAME. F Domain Type The name of the domain type to which the domain belongs.. 1019. Switch3.. D Action One of “Create.0.Delete. Col Field Accepted Values A Workflow id The id required to approve/reject this change via ModifyPendingApproval.jane. The remaining columns provide a full description of the resource record. B Date/Time The date and time of the approval request.com.sh –u joe –p joepwd –f exportpending.1800->2400.com. The next two columns contain the domain name and type. Default.csv in the current directory.IN. Delete” E Domain The name of the domain to which the resource records belongs.router00007.Update.Default.com.tom. File Format The format for the export file is described in the table following. 2009-07-16 23:45:12. For update requests.Create. old and new values are shown as “old value -> new value”.csv Sample file contents are shown below: 1018.csv –q jane This produces the first two records of the file contents shown in the previous example. Refer to the appropriate RFC for exact text format.com.test.com. Each line starts with the workflow information: workflow id date and time the action was requested requestor’s IPControl administrator’s login id action requested..switch00024. Note that this section is specific to the type of resource record.switch00033. $INCHOME/etc/cli/ExportResourceRecordPendingApproval.example. I Class The value currently supported is IN. Com mand Line Interfaces (CLI) 85 .IN.2009-07-16 21:23:02.10.1800.1300.jane.example. G Owner The OWNER section of the resource record.example.IN. C Administrator The login id of the administrator submitting the request for approval. requested by jane: $INCHOME/etc/cli/ExportResourceRecordPendingApproval.->new.0. Update. L Comment Text appended to the resource record. 86 IPControl CLI and API Guide .ExportResourceRecordPendingApproval J Resource Record Type The type of resource record. Refer to the appropriate RFC for exact text format. K Data The text for the DATA area of the resource record. Note that this section is specific to the type of resource record. or delete a resource record. $INCHOME/etc/cli/ExportResourceRecordPendingApprovalStatus. These updates include those to create. update.cli. No Produces verbose output.sh –u joe –p joepwd –f exportstatus.diamondip. No Filter. “update” or “delete” a resource record.csv Com mand Line Interfaces (CLI) 87 . Allows you to filter export based on the domain name of the resource record. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. Allows you to filter export based on the domain type of the resource record. -f <export filename> -m <domain> -a <domaintype> -x <action> -v Usage Example This example exports all resource records that administrator joe submitted for approval to a file named exportstatus.csv in the current directory. No Filter. No Filter.ExportResourceRecordPendingApprovalStatusCLI –u <userId> -p <pswd> [-f <export filename>] [-m <domain>] [-a <domaintype>] [-x <action>] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportResourceRecordPendingApprovalStatus.cmd –u <userId> -p <pswd> [-f <export filename>] [-m <domain>] [-a <domaintype>] [-x <action>] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help No The name of the file to export the data to.sh –u <userId> -p <pswd> [-f <export filename>] [-m <domain>] [-a <domaintype>] [-x <action>] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ExportResourceRecordPendingApprovalStatus.ExportResourceRecordPendingApprovalStatus ExportResourceRecordPendingApprovalStatus Overview The ExportResourceRecordPendingApprovalStatus CLI exports a list of the resource record updates that were submitted for approval by the invoking administrator.ipcontrol. If no file name is specified. results are written to the screen. Allows you to filter export based on the request to “create”. The domain names of the exported records will contain the specified value. Refer to the appropriate RFC for exact text format.CNAME.1800. The remaining columns provide a full description of the resource record..com.1300. old and new values are shown as “old value -> new value”. C Administrator The login id of the administrator submitting the request (same as invoking administrator).joe.10. 88 IPControl CLI and API Guide .0. H TTL The Time To Live.joe.joe. 2009-07-16 23:45:12.switch00024.IN. Default. RouterSevenWest. The next two columns contain the domain name and type. 2009-07-17 21:32:22. D Action One of “Create.CNAME. Refer to the appropriate RFC for exact text format.router00007. K Data The text for the DATA area of the resource record.example..com.test.0.example.com. Delete” E Domain The name of the domain to which the resource records belongs.com.Update. Update.com.A..Default. For update requests. Note that this section is specific to the type of resource record.2009-07-16 21:23:02. L Comment Text appended to the resource record. B Date/Time The date and time of the approval request.3.IN.1800->2400. F Domain Type The name of the domain type to which the domain belongs. File Format The format for the export file is described in the table following. I Class The value currently supported is IN. Note that this section is specific to the type of resource record. Switch3.Default. Each line starts with the workflow information: workflow id date and time the action was requested requestor’s IPControl administrator’s login id (same as invoking administrator) action requested. J Resource Record Type The type of resource record.switch00033. Col Field Accepted Values A Workflow id The id required to approve/reject this change via ModifyPendingApproval. 1019.Delete. G Owner The OWNER section of the resource record.example.oldcomment->newcomment 1020.com.example.Create.ExportResourceRecordPendingApprovalStatus Sample file contents are shown below: 1018.example.IN.->new. surround the name with doublequotes “ “.ExportRootBlock ExportRootBlock Overview The ExportRootBlock CLI exports a list of all the Root Blocks into a specified file. followed by the block size. 10. Com mand Line Interfaces (CLI) 89 .0. -n <block name> No Filter. -i <IP address> No Filter.0/24. results are outputted to the screen.0. 10. Specify an IP address which falls within the start and end address of a block. The wildcard character ‘*’ can be used in the start address only. -r <IP address range> No Filter. The format of the range is specified as start-end. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.cli. -b <block address/size> No Filter. If the block name contains embedded spaces.cmd –u <userId> -p <pswd> [-f <export filename>] [-n <block name>] [–b <block address/size>] [–t <block type>] [–c <container name>] [–i <IP address>] [–r <IP address range>] [–d <user defined field name=value>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <export filename> No The name of the file to export the data to.0-10. -t <block type> No Filter.0.ExportRootBlockCLI –u <userId> -p <pswd> [-f <export filename>] [-n <block name>] [–b <block address/size>] [–t <block type>] [–c <container name>] [–i <IP address>] [–r <IP address range>] [–d <user defined field name=value>] [-?] Via command script (Unix) $INCHOME/etc/cli/ExportRootBlock.sh –u <userId> -p <pswd> [-f <export filename>] [-n <block name>] [–b <block address/size>] [–t <block type>] [–c <container name>] [–i <IP address>] [–r <IP address range>] [–d <user defined field name=value>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ExportRootBlock. Specify the name of a specific block type or use the wildcard character ‘*’ to perform a partial match on the block type name. separated by a slash ‘/’.ipcontrol.255. This file can be modified and then imported using the ImportRootBlock CLI. Specify a range of IP addresses which span one or more blocks. That is. Specify the name of a specific block or use the wildcard character ‘*’ to perform a partial match on the name. Specify the name of a specific container or use the wildcard character ‘*’ to perform a partial match on the container name. Specify the CIDR notation of a block. -c <container name> No Filter. For example. specify the starting IP address for the block. If no file name is specified.diamondip.0.0.255. For example. The UDF is specified using the syntax name=value. For wildcarding. defaults to false. Col Field Accepted Values Required A Container The name of the container that will hold the block. Long format eliminates ambiguity in cases where there are duplicate container names.255. where name is the name of the UDF. and AFRINIC. Short format example: Dallas. ARIN. This should be in the format of a network address (e. No 90 IPControl CLI and API Guide . $INCHOME/etc/cli/ExportRootBlock. this field is skipped. Names can be in either short or long format... No E Block type The Block Type for the block. 10. APNIC.csv –n MyBlock* -t Private File Format The format for the export file is as follows.csv This example exports root blocks that begin with the name MyBlock and that are of block type Private to the file rbexport. Usage Example This example exports all root blocks to a rbexport.csv file in the current directory. a block type of Any is assumed. –d “udfName=value*”.0.csv. No I Organization Id The organization id for the Regional Internet Registry this space was obtained from. Note: This is the same format that the ImportRootBlock CLI requires.e. i. If not specified. Long format example: IPControl/Texas/Dallas.sh –u joe –p joepwd –f rbexport.ExportRootBlock Param eter Required Description -d <user defined field name=value> No Filter. Yes C Block size The size of the block in short-notation (e. Accepted values are true or false. If Allocation Reason is not currently in IPControl.g. Also surround the parameter with double quotes if there is an embedded blank in the filter string. Specify a User Defined Field (UDF) attached to a block.0 network). and value is the value of the UDF. No J Allocation Reason The name of a pre-existing Allocation Reason. use a “*” character within “double quotes”. Defaults to system supplied name of Address space/Block size. RIPE. 24 for a 255. $INCHOME/etc/cli/ExportRootBlock. Generic is assumed.0. This id must be predefined in IPControl. Yes B IP space The IP block to create.. No H Regional Internet Registry The Regional Internet Registry this space was obtained from. Accepted values are: Generic. LACNIC.255. No G Allow Duplicate Space Whether or not to allow duplicate (overlapping) address space in this block. RFC1918. No F Block Name A name for the block. If not specified. If not specified. Yes D Description A description of the block.0).g.sh –u joe –p joepwd –f rbexport. defaults to “Default”.ExportRootBlock Col Field Accepted Values Required K Allocation Reason Description A description of the reason for the allocation. Multiple pairs can be specified by separating each pair with the ‘|’ character. If not specified. Yes. If not specified. where the name is the UDF name and the value is desired value. if required by Container rules M Create Reverse Domains Whether or not to automatically create reverse DNS domain(s) for this block. for UDFs defined as required fields. Com mand Line Interfaces (CLI) 91 . For example. No L SWIP/Net Name SWIP/Net name for the block. defaults to false. No O User Defined Fields A series of name=value pairs. Yes. If the UDF type is Checkbox. Accepted values are true or false. No N Domain Type Specify the domain type for the reverse DNS domain(s) to be created when Create Reverse Domains is “true”. the valid values are “on” or “off”. UDFone=value one |UDFtwo=value two. Usage Example This example deletes the address pools listed in the file addrpools.txt File Format The input file format for DeleteAddrPool is the same as for ImportAddrPool.cmd –u <userId> -p <pswd> -f <delete filename> [-d] [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -d No Delete devices within this pool -f <delete filename> Yes The name of the CSV file listing address pools to be deleted.sh –u <userId> -p <pswd> -f <delete filename> [-d] [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteAddrPool. See below for the required file format. Multiple addr pools to be deleted can be specified. $INCHOME/etc/cli/DeleteAddrPool.DeleteAddrPoolCLI –u <userId> -p <pswd> -f <delete filename> [-d] [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteAddrPool.diamondip. -e <error messages> No The name of the file that error messages will be reported in. This CLI enables you to specify a file containing a list of address pools to delete. Col Field Accepted Values Required A Start Address The IP Address of the first address in the pool. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in. The addr pool is identified by its Start Address or Name.ipcontrol. Yes B End Address Ignored No 92 IPControl CLI and API Guide . Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.txt.DeleteAddrPool Deletes DeleteAddrPool Overview The DeleteAddrPool CLI allows the user to delete Address Pools in the system.sh –u joe –p joepwd –f addrpools.cli. Yes E Share Name Ignored No F Container Ignored No G Primary Net Service Ignored No H Failover Net Service Ignored No I DHCP Option Set Ignored No J DHCP Policy Set Ignored No K Allow DHCP Client Classes Ignored No L Deny DHCP Client Classes Ignored No M PrefixLength Ignored No Com mand Line Interfaces (CLI) 93 .DeleteAddrPool Col Field Accepted Values Required C Address Pool Type Ignored No D Name Address Pool name. and reports errors to the importerrors.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV file listing blocks to be deleted. place into the delaggblocks.csv file. $INCHOME/etc/cli/DeleteAggregateBlock.csv –r delaggblocks. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. IPControl validates and deletes the block.txt 94 IPControl CLI and API Guide . By specifying the block to be deleted.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteAggregateBlock. See below for the required file format.DeleteAggregateBlock DeleteAggregateBlock Overview The DeleteAggregateBlock CLI allows the user to delete an intermediate level Aggregate block from the block hierarchy. Usage Example This example deletes resource records described in the delaggblocks.reject file any records that could not be deleted.reject –e importerrors. -r <rejects file> No The name of the file that rejected (non-imported) records will be placed in. -e <error messages> No The name of the file that error messages will be reported in. It also adjusts the parent block assignments of any child blocks.cli.diamondip.sh –u joe –p joepwd –f delaggblocks.txt file.ipcontrol.DeleteAggregateBlockCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteAggregateBlock. No K Interface Offset or Address DEPRECATED. Long format example: IPControl/Texas/Dallas. No N User Defined Fields A series of name=value pairs. If the UDF type is Checkbox. the valid values are “on” or “off”. where the name is the UDF name and the value is desired value.255. This field will be ignored. 24 for a 255. defaults to false. 24 for a 255. No G SWIP Name SWIP name for the block. Accepted values are true or false. No I Allocation Reason Description A description of the reason for the allocation. No Yes Com mand Line Interfaces (CLI) 95 . a block type of Any is assumed.. The start address of the aggregate block.255. For example.0 network). Multiple pairs can be specified by separating each pair with the “|” character. Wrap the statement in “quotes” if it contains any commas. the name of the interface to attach the block to. No M Domain Type Specify the domain type for the reverse DNS domain(s) to be created when Create Reverse Domains is “true”. No L Create Reverse Domains Whether or not to automatically create reverse DNS domain(s) for this block.g.DeleteAggregateBlock File Format Col Field Accepted Values Required A Container Yes B Start Address The name of the container holding the aggregate block to be deleted. Short format example: Dallas.255. defaults to “Default”. If not specified. No E Block Name A name for the block. No F Description A description of the block. Yes D Block Type The Block Type for the block If not specified. UDFone=value one |UDFtwo=value two. Names can be in either short or long format. No O Parent Container The name of the container where the parent block resides.g. No J Interface Name If this block is being added to a device container. If not specified. No P Parent Block Address The address of the parent block No Q Parent Block Size The size of the parent block in short-notation (e. Defaults to system supplied name of Address space/Block size. C Block Size The size of the block in short-notation (e. No H Allocation Reason The name of a pre-existing Allocation Reason. Long format eliminates ambiguity in cases where there are duplicate container names.0 network).255.. cli. containername. -b <block name> Either –f or –b must be specified. 96 IPControl CLI and API Guide . or to read a file containing a list of blocks to delete. 10. The name of the container holding the block. The name of the CSV file listing blocks to be deleted. -e <error messages> No The name of the file that error messages will be reported in.diamondip. -f <delete filename> Either –f or –b must be specified.ipcontrol. Otherwise. This CLI allows you to specify a single block to delete on the command line. When the –x flag is not present.sh –u <userId> -p <pswd> [-f <delete filename>] [-r <rejects file>] [-e <error messages>] [-b <block Name>] [-c <container name>] [-x] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteBlock. the whole system is searched.1.DeleteBlock DeleteBlock Overview The DeleteBlock CLI allows the user to remove blocks from the system. where the file format lists the container name as the first column and the block name as the 4 th column. the container is searched for the block to delete. -c <container name> Must be specified if the block name is not unique. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com..2.g. If this parameter is supplied.0/24. e. if the block name was set manually during allocation. This is typically the CIDR address.DeleteBlockCLI –u <userId> -p <pswd> [-f <delete filename>] [-r <rejects file>] [-e <error messages>] [-b <block Name>] [-c <container name>] [-x] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteBlock. the file format is blockname. that value must be used instead. However. See below for the required file format. The name of the block to be deleted.cmd –u <userId> -p <pswd> [-f <delete filename>] [-r <rejects file>] [-e <error messages>] [-b <block Name>] [-c <container name>] [-x] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -x No When presents indicates the CSV file specified by the –f flag is from the export*Block cli. if the block name was set manually during allocation.1.2.0/24 File Format Col Field Accepted Values Required A Block Name The name of the block to delete. this example assumes that there is only one block with this name in the system.0/24 from the system. This is typically the CIDR address. $INCHOME/etc/cli/DeleteBlock.DeleteBlock Usage Example This example deletes the block 10. 10. e.g. However. Yes B Container Name The name of the container holding the block.2.sh –u joe –p joepwd –b 10.2.1. that value must be used instead.1.0/24. No Com mand Line Interfaces (CLI) 97 . As mentioned above. DeleteContainer DeleteContainer Overview The DeleteContainer CLI allows the user to remove individual containers from the system.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteContainer. -e <error messages> No The name of the file that error messages will be reported in.txt.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV file listing containers to be deleted.cli. Only containers that contain no blocks. Usage Example This example deletes the containers listed in the file containers.txt 98 IPControl CLI and API Guide . $INCHOME/etc/cli/DeleteContainer. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.ipcontrol. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in. See below for the required file format.sh –u joe –p joepwd –f containers. This CLI allows you to specify a file containing a list of containers to delete.DeleteContainerCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteContainer. services or child containers are available for deletion.diamondip. Yes B Container Description Ignored No C Parent Container Ignored No D Container Type Ignored No E Rule1 Ignored No F Rule2 Ignored No G Rule3 Ignored No H Rule4 Ignored No I Rule5 Ignored No J Information Template Ignored No K User Defined Fields Ignored No Com mand Line Interfaces (CLI) 99 .DeleteContainer File Format By design. one can use the same file to delete a set of containers and then re-add them without copying data. Only the container name is required. Col Field Accepted Values Required A Container Name The name of the container. An unqualified name must be unique. This way. The container names should be separated by slashes. A qualified name must start with the root container and include the complete container path to the desired container. the input file format for DeleteContainer is the same as for ImportContainer. The name can be either qualified or unqualified. cli.txt 100 IPControl CLI and API Guide .txt. $INCHOME/etc/cli/DeleteDevice. Usage Example This example deletes the devices listed in the file devices.ipcontrol. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteDevice. See below for the required file format. -e <error messages> No The name of the file that error messages will be reported in. Use the ImportChildBlock CLI with the overwrite parameter to delete Interface-type devices. Note that this is not used to delete devices of type “Interface”. This CLI allows you to specify a file containing a list of devices to delete.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV file listing devices to be deleted.DeleteDevice DeleteDevice Overview The DeleteDevice CLI allows the user to remove individual devices from the system. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.diamondip.sh –u joe –p joepwd –f devices.DeleteDeviceCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteDevice. In this case. This way. the Container is required to uniquely determine the device. The container might also be required if overlapping address space is in use and the device is in a block that is part of that overlapping space. only the IP Address is required. the input file format for DeleteDevice is the same as for ImportDevice. one can use the same file to the delete a set of devices and then re-add them without copying data. Com mand Line Interfaces (CLI) 101 . Yes. In the simplest case. Col Field Accepted Values Required A IP Address The IP Address of the Device Yes B Address Type Ignored No C Host Name Ignored No D Device Type Ignored No E Hardware Type Ignored No F MAC Address Ignored No G Resource Record Flag Ignored No H Domain Name Ignored No I Container The name of the container holding the block to which the device belongs.DeleteDevice File Format By design. if overlapping space is in use and the block in which the device resides is ambiguous. sh –u joe –p joepwd –f domains.DeleteDomainCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteDomain. $INCHOME/etc/cli/DeleteDomain. See below for the required file format. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.diamondip. Usage Example This example deletes the domains listed in the file domains. This CLI allows you to specify a file containing a list of domains to delete. -v <verbose> No Produces verbose output.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV file listing domains to be deleted. -e <error messages> No The name of the file that error messages will be reported in.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteDomain.DeleteDomain DeleteDomain Overview The DeleteDomain CLI allows the user to remove individual domains from the system.ipcontrol.txt 102 IPControl CLI and API Guide .txt.cli. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. C Managed Ignored No D Delegated Ignored No E Reverse Ignored No F Derivative Ignored No G Template Domain Ignored No H Serial Number Ignored No I Refresh Ignored No J Retry Ignored No K Expire Ignored No L Negative Cache TTL Ignored No M Default TTL Ignored No N Contact Ignored No O Information Template Ignored No P User Defined Fields Ignored No Com mand Line Interfaces (CLI) 103 . If not specified.DeleteDomain File Format By design. the input file format for DeleteDomain is the same as for ImportDomain. In the simplest case. Col Field Accepted Values Required A Domain Name The name of the domain being created. Yes B Domain Type Domain type name already defined to IPControl. This way. The Domain Type might also be required if it is not “Default”. Yes. when not “Default”. the “Default” domain type will be used. one can use the same file to delete a set of domains and then re-add them without copying data. only the Domain Name is required. cli. Note that this is not used to delete devices of type “Interface”. This CLI enables you to specify a file containing a list of device interfaces to delete.ipcontrol.DeleteDeviceInterfaceCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteDeviceInterface. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.txt. -e <error messages> No The name of the file that error messages will be reported in. See below for the required file format.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV file listing device interfaces to be deleted. Usage Example This example deletes the device interfaces listed in the file deviceInterfaces.sh –u joe –p joepwd –f deviceInterfaces. $INCHOME/etc/cli/DeleteDeviceInterface.txt 104 IPControl CLI and API Guide .sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteDeviceInterface. Use the ImportChildBlock CLI with the overwrite parameter to delete Interface-type devices. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.DeleteDeviceInterface DeleteDeviceInterface Overview The DeleteDeviceInterface CLI allows the user to remove device interfaces from multi-homed devices in the system.diamondip. The container must also be specified if the de vice’s IP Address is not unique due to overlapping address space. Yes B Address Type Ignored No C Host Name Ignored No D Device Type Ignored No E Hardware Type Ignored No F MAC Address Ignored No G Resource Record Flag Ignored No H Domain Name Ignored No I Container The name of the container holding the block to which the device belongs. Multiple interfaces to be deleted can be specified. you may specify their IP addresses delimited by ‘|’ (as output by ExportDevice). If multiple interfaces are to be deleted. J Domain Type Ignored No K Description Ignored No L User Defined Fields Ignored No M Aliases Ignored No N Ignore Warning Ignored No O Interface Names Specify the names of the interfaces to be deleted. Yes P Exclude from Discovery Flags Ignored No Com mand Line Interfaces (CLI) 105 . delimited by ‘|’. if overlapping space is in use and the block in which the device resides is ambiguous.DeleteDeviceInterface File Format The input file format for DeleteDeviceInterface is the same as for ExportDevice. but only one IP Address is required to identify the device. Col Field Accepted Values Required A IP Address The IP address of the device. The device is identified by its IP Address. Yes. The interface is identified by its name. txt 106 IPControl CLI and API Guide .DeleteDeviceResourceRecord DeleteDeviceResourceRecord Overview The DeleteDeviceResourceRecord CLI allows the user to delete DNS resource records for a device from IPControl. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.DeleteDeviceResourceRecordCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteDeviceResourceRecord. -e <error messages> No The name of the file that error messages will be reported in.diamondip.ipcontrol.sh –u joe –p joepwd –f delresourcerecs. Usage Example This example deletes resource records described in the delresourcerecs. and reports errors to the importerrors. $INCHOME/etc/cli/DeleteDeviceResourceRecord.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteDeviceResourceRecord.cli.reject –e importerrors.csv file.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV file describing records to be deleted. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.reject file any records that could not be deleted.txt file.csv –r delresroucerecs. See below for the required file format. places into the delresourcerecs. unless IP Address is specified. E IP Address The IP Address of the Device.DeleteDeviceResourceRecord File Format Col Field Accepted Values Required A Domain The name of the domain for this resource record. Yes J Data The text for the DATA area of the resource record. G TTL The Time To Live. Yes B DomainType The domain type of the domain. if IP Address in overlapping space. defaults to IN. unless Host Name is specified. Defaults to “Default” No C Owner The OWNER section of the resource record. Yes D Host Name The device host name. No H Class The value currently supported is IN. Yes. No I Resource Record Type The type of resource record being deleted. F Container The name of the container that holds the device. This is required only if there is overlapping address space in use and the ip address is in overlapping space. Yes. If not specified. Yes. The container is then used to uniquely determine the device. Yes Com mand Line Interfaces (CLI) 107 . $INCHOME/etc/cli/DeleteDomainResourceRecord.DeleteDomainResourceRecord DeleteDomainResourceRecord Overview The DeleteDomainResourceRecord CLI allows the user to delete DNS resource records for a DNS domain from IPControl.txt file.ipcontrol.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteDomainResourceRecord.txt 108 IPControl CLI and API Guide . places into the delresourcerecs.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV file describing records to be deleted. -e <error messages> No The name of the file that error messages will be reported in.cli. Usage Example This example deletes resource records described in the delresourcerecs. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.reject –e deleteerrors. See below for the required file format. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.reject file any records that could not be deleted.diamondip. and reports errors to the deleteerrors.sh –u joe –p joepwd –f delresourcerecs.DeleteDomainResourceRecordCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteDomainResourceRecord.csv –r delresroucerecs.csv file. Yes G Data The text for the DATA area of the resource record. No F Resource Record Type The type of resource record being deleted. If not specified. Yes D TTL The Time To Live. No C Owner The OWNER section of the resource record. Yes Com mand Line Interfaces (CLI) 109 . defaults to IN. No E Class The value currently supported is IN.DeleteDomainResourceRecord File Format Col Field Accepted Values Required A Domain The name of the domain for this resource record. Yes B DomainType The domain type of the domain. Defaults to “Default”. -e <error messages> No The name of the file that error messages will be reported in. places into the netelements.reject –e deleteerrors.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV listing network elements to be deleted See below for the required file format. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.netcontrol.csv –r netelements.diamondip.txt 110 IPControl CLI and API Guide . Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. and reports errors to the deleteerrors.csv file.txt file.reject file any records that could not be deleted. Usage Example This example deletes network elements listed in the netelements.cli. This CLI allows you to specify a file containing a list of network elements to delete.DeleteNetElementCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteNetElement. $INCHOME/etc/cli/DeleteNetElement.sh –u joe –p joepwd –f netelements.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteNetElement.DeleteNetElement DeleteNetElement Overview The DeleteNetElement CLI enables the user to remove individual network elements from the system. the input file format for DeleteNetElement is the same as the format for ImportNetElement and ExportNetElement. If the IP address is not unique. the name must be specified. Specify the name or the IP address of the network element. Yes. one can use the same file to delete a set of network elements and then re-add them without copying data. This way.DeleteNetElement File Format By design. Col Field Accepted Values Required A Name The name of the Network Element. unless the name is specified C Vendor Ignored No D Model Ignored No E Type Ignored No F Global Sync Ignored No G Agent Name Ignored No H Telnet user Ignored No I Telnet password Ignored No J Enable password Ignored No K Read community string Ignored No L Interface List Ignored No M V3 Username Ignored No N V3 Authentication Protocol Ignored No O V3 Authentication Password Ignored No P V3 Privacy Protocol Ignored No Q V3 Privacy Password Ignored No R V3 Context Name Ignored No S V3 Engine ID Ignored No Com mand Line Interfaces (CLI) 111 . unless a unique IP address is specified B IP Address/FQDN The IP address or fully-qualified domain name (FQDN) of the Network Element. Yes. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.ipcontrol.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV file listing the interfaces to be deleted.reject file any records that could not be deleted.diamondip. -r <rejects file> No The name of the file that rejected (not deleted) records will be placed in.csv file.sh –u joe –p joepwd –f netelementinterfaces. See below for the required file format.txt file. -e <error messages> No The name of the file that error messages will be reported in. places into the netelementinterfaces. and reports errors to the deleteerrors. $INCHOME/etc/cli/DeleteNetElementInterface.csv –r netelementinterfaces.reject –e deleteerrors. -v No Produces verbose output.txt 112 IPControl CLI and API Guide .DeleteNetElementInterface DeleteNetElementInterface Overview The DeleteNetElementInterface CLI allows the user to delete network element interfaces from IPControl.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteNetElementInterface. This CLI allows you to specify a file containing a list of network element interfaces to delete.DeleteNetElementInterfaceCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteNetElementInterface. Usage Example This example deletes Network Elements interfaces listed in the netelementinterfaces.cli. Yes C Status The status of the interface. No Com mand Line Interfaces (CLI) 113 . Only the network element name and interface name are required. This way. Col Field Accepted Values Required A Name The name of a Network Element already defined to IPControl. one can use the same file to the delete a set of interfaces and then re-add them without copying data. Yes B Interface Name The name of the interface to delete. This is not used for delete.DeleteNetElementInterface File Format By design. the input file format for DeleteNetElementInterface is the same as for ImportNetElementInterface. sh –u joe –p joepwd –f netservices.DeleteNetService DeleteNetService Overview The DeleteNetService CLI enables the user to remove individual network services from the system. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.csv –r netservices. places into the netservices.txt 114 IPControl CLI and API Guide .csv file.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteNetService.reject –e deleteerrors.diamondip.txt file. Usage Example This example deletes network services listed in the netservices.DeleteNetServiceCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteNetService. $INCHOME/etc/cli/DeleteNetService.netcontrol. This CLI allows you to specify a file containing a list of network services to delete. -e <error messages> No The name of the file that error messages will be reported in. and reports errors to the deleteerrors.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV listing of network services to be deleted See below for the required file format.cli. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.reject file any records that could not be deleted. No D Product name Ignored No E Agent name Ignored No F Global Sync Ignored No G Collection Method Ignored No H User name for collection Ignored No I Password for collection Ignored No J Collection port Ignored No K Container(s) Ignored L VendorInfo Ignored No M WarningThreshold Ignored No Com mand Line Interfaces (CLI) 115 . If the type is not specified. Accepted value is dhcp.DeleteNetService File Format By design. Yes B IP Address/FQDN Ignored No C Type The type of Network Service. This way. If this column is left blank. Col Field Accepted Values Required A Name The name of the Network Service. Specify the name and the type of the network service. the input file format for DeleteNetService is the same as the format for ImportNetService and ExportNetService. it defaults to “DHCP”. dhcp is assumed. one can use the same file to delete a set of network services and then re-add them without copying data. This can be any combination of letters and numbers. DeletePrefixPoolCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeletePrefixPool. $INCHOME/etc/cli/DeletePrefixPool.ipcontrol. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeletePrefixPool. This CLI enables you to specify a file containing a list of prefix pools to delete. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.diamondip.txt 116 IPControl CLI and API Guide .cli.sh –u joe –p joepwd –f prefixpools.txt. See below for the required file format. Usage Example This example deletes the prefix pools listed in the file prefixpools.DeletePrefixPool DeletePrefixPool Overview The DeletePrefixPool CLI allows the user to delete Prefix Pools in the system. -e <error messages> No The name of the file that error messages will be reported in.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <deletet filename> Yes The name of the CSV file listing prefix pools to be deleted. The prefix pool is identified by its Start Address or Name. Multiple prefix pools to be deleted can be specified. Col Field Accepted Values Required A Start Addr The Start address of the prefix pool.DeletePrefixPool File Format The input file format for DeletePrefixPool is the same as for ImportPrefixPool. Yes E Container Ignored No F Delegated Prefix Length Ignored No G Longest Prefix Length Ignored No H Shortest Prefix Length Ignored No I Primary Net Service Ignored No J DHCP Option Set Ignored No K DHCP Policy Set Ignored No L Allow DHCP Client Classes Ignored No M Deny DHCP Client Classes Ignored No Com mand Line Interfaces (CLI) 117 . Yes B Length Ignored No C Prefix Pool Type Ignored No D Name Name of the prefix pool. or –d must be specified.DeleteTaskCLI –u <userId> -p <pswd> [-t <idlist> | –r <retain> | -d <date>] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteTask. For example. -r <retain> One of –t. $INCHOME/etc/cli/DeleteTask. -d <date> One of –t. tasks older than 30 days will be deleted. in the format yyyy/mm/dd. -t “123. One or more task IDs to delete. Tasks older than this date will be deleted. The CLI will print out more information about the request. For example. -r.456”.diamondip. -r. for example.cmd –u <userId> -p <pswd> [-t <idlist> | –r <retain> | -d <date>] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -t <idlist> One of –t.ipcontrol. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u <userId> -p <pswd> [-t <idlist> | –r <retain> | -d <date>] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteTask. Multiple tasks are separated by commas with no spaces. enclose a list of tasks in quotes. In particular. or –d must be specified. This CLI uses command line arguments only. it will print how many tasks were deleted. for a date of 2005/12/31. or –d must be specified.DeleteTask DeleteTask Overview The DeleteTask CLI allows the user to delete tasks from the system.cli. 118 IPControl CLI and API Guide . Usage Example This example deletes tasks older than 60 days. -v No Verbose option.sh –u joe –p joepwd –r 60 -v File Format None. In Windows. all tasks prior to that date will be deleted. -r. The number of days of tasks to retain. if –r 30 is specified. cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <delete filename> Yes The name of the CSV listing zones to be deleted See below for the required file format.txt Com mand Line Interfaces (CLI) 119 .reject –e deleteerrors.csv file. This CLI allows you to specify a file containing a list of zones to delete. Usage Example This example deletes zones listed in the zones. -v <verbose> No Produces verbose output.txt file.reject file any records that could not be deleted.netcontrol.diamondip. -e <error messages> No The name of the file that error messages will be reported in.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteZone. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.DeleteZoneCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteZone. $INCHOME/etc/cli/DeleteZone. and reports errors to the deleteerrors. places into the zones.cli.sh –u joe –p joepwd –f zones.DeleteZone DeleteZone Overview The DeleteZone CLI enables the user to remove zones from the system. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.csv –r zones. one can use the same file to delete a set of zones and then re-add them without copying data. Yes B Zone type Ignored No C Domain Name Domain name already defined to IPControl. the input file format for DeleteZone is the same as the format for ImportZone.DeleteZone File Format By design. No G Filename Ignored No H Automatic Generation of NS/GLUE Records Ignored No I MNAME Ignored No J Allow Zone Transfers to DNS Listener Ignored No K Masters Ignored No L Zone extensions Prior Ignored No M Zone extensions After Ignored No N Template Zone Ignored No O Alias Zone Ignored No P Galaxy Name Ignored No Q Allow Update ACL Ignored No R Update Policy Ignored No S Dynamic Zone Ignored No 120 IPControl CLI and API Guide . 'Default. the “Default” domain type will be used.' will be used. This way. If not specified. No E Update Zone Ignored No F View The name of the view containing the zone to be deleted. Yes D Domain Type Domain type name already defined to IPControl. Col Field Accepted Values Required A Server The network service name of the DNS Server. If not specified. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.txt Com mand Line Interfaces (CLI) 121 .ipcontrol. See below for the required file format. -e <error messages> No The name of the file that error messages will be reported in.txt file. places into the delresourcerecs. Usage Example This example deletes resource records described in the delresourcerecs.DeleteZoneResourceRecord DeleteZoneResourceRecord Overview The DeleteZoneResourceRecord CLI allows the user to delete DNS resource records for a zone from IPControl.cmd –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -f <import filename> Yes The name of the CSV file describing records to be deleted. and reports errors to the importerrors.sh –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DeleteZoneResourceRecord.reject –e importerrors.reject file any records that could not be deleted. $INCHOME/etc/cli/DeleteZoneResourceRecord.sh –u joe –p joepwd –f delresourcerecs.csv file.csv –r delresroucerecs.diamondip. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.cli.DeleteZoneResourceRecordCLI –u <userId> -p <pswd> -f <delete filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/DeleteZoneResourceRecord. Yes E TTL The Time To Live. Yes H Data The text for the DATA area of the resource record. No F Class The value currently supported is IN. Yes B View The name of the view for this zone. If not specified. If specified. If not specified. If supplied the view must exist. must match the value in the record to be deleted. which is the top level domain name. Yes D Owner The OWNER section of the resource record. Yes 122 IPControl CLI and API Guide . defaults to IN. 'Default' will be used. Yes C Zone The name of the zone.DeleteZoneResourceRecord File Format Col Field Accepted Values Required A Server The network service name of the DNS Server. No G Resource Record Type The type of resource record being deleted. cli. -v No Verbose Usage Example This creates a task to perform an ARP discover on a Net Element with IP Address 10. unless –n specified IP Address of the Net Element to discover. the task will ignore duplicate hostname errors when adding new hosts. the task will add new hosts found during discovery. --updatereclaim No If set.23.cmd –u <userId> -p <pswd> [-n <Net Element name> | -i <Net Element name>] [--performnethostadds] [--updatereclaim] [--ignoredups] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -i <IP Address> Yes. Com mand Line Interfaces (CLI) 123 .40.ArpDiscoverNetElement Task Tasks ArpDiscoverNetElement Task Overview The ArpDiscoverNetElement CLI allows the user to create an ARP Discover task on a given Net Element. --performnethostadds No If set. -n <Name> Yes. the task will update the last discovered counters for blocks and hosts defined within the network element. and to perform net host adds as part of the processing.ipcontrol. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.6.ArpDiscoverNetElementCLI –u <userId> -p <pswd> [-n <Net Element name> | -i <Net Element IP address>] [--performnethostadds][--updatereclaim][--ignoredups] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/ArpDiscoverNetElementCLI. --ignoredups No If set.sh –u <userId> -p <pswd> [-n <Net Element name> | -i <Net Element name>] [--performnethostadds] [--updatereclaim] [--ignoredups] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/ArpDiscoverNetElementCLI. unless –i specified Name of the Net Element to discover.diamondip. 6 --performnethostadds Return codes If the task is scheduled successfully.$INCHOME/etc/cli/ArpDiscoveryNetElementCLI.40. the errorlevel returned is a non-zero number. That task number can then be passed to the TaskStatus CLI to obtain the status of that task.sh –u joe –p joepwd –i 10. an errorlevel of 0 is set. and an error message is printed to the console. 124 IPControl CLI and API Guide .23. If the task is NOT scheduled successfully. the task number is printed to the screen. If –v is specified. DhcpConfigurationTaskCLI –u <userId> -p <pswd> [-n <DHCP server name> | -i <DHCP server IP address>] [-a] [-f] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/DhcpConfigurationTask.cli. DHCP Configuration tasks generate and deploy configuration files for DHCP servers.ipcontrol. the task will stop if errors are detected during the configuration generation. unless –i specified Name of Network Service (DHCP server) to configure. unless –n specified IP Address of the DHCP Server to configure.sh –u <userId> -p <pswd> [-n <DHCP server name> | -i <DHCP server IP address>] [-a] [-f] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/DhcpConfigurationTask. if there are any errors. In addition. -n <Name> Yes.cmd –u <userId> -p <pswd> [-n <DHCP server name> | -i <DHCP server IP address>] [-a] [-f] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -i <IP Address> Yes.sh –u joe –p joepwd –n dhcp5 –a -f Com mand Line Interfaces (CLI) 125 . the task will abort. -f No If set. -v No Verbose Usage Example This creates a task to perform a DHCP configuration deployment for the dhcp5 DHCP server. Lastly. $INCHOME/etc/cli/DhcpConfigurationTask.DhcpConfigurationTask Overview The DhcpConfigurationTask CLI allows the user to create a DHCP Configuration task. their configurations are also deployed. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. any associated failover servers will also have their configurations generated and deployed.diamondip. if there are any failover servers associated with dhcp5. -a No If set. If the task is NOT scheduled successfully. along with a string including the task number. and an error message is printed to the console. an errorlevel of 0 is passed. 126 IPControl CLI and API Guide . the errorlevel returned is a negative number. That task number can then be passed to the TaskStatus CLI to obtain the status of that task.DhcpConfigurationTask Return codes If the task is scheduled successfully. providing the task id.cli. That task number can then be passed to the TaskStatus CLI to obtain the status of that task. and an error message will be printed to the console.DHCPUtilization DHCPUtilization Overview The DHCPUtilization CLI allows the user to issue an immediate DHCP Collection task to collect statistics on the utilization of a DHCP server. If the task is NOT scheduled successfully. along with a string including the task number.diamondip. -n <Name> Yes Name of Network Service (DHCP server) to discover.cmd –u <userId> -p <pswd> [-n <network service name> | -i <network service ip address>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -i <IP Address | FQDN> Yes IP Address or fully-qualified domain name (FQDN) of the device to discover. Com mand Line Interfaces (CLI) 127 . Required only if IP Address or FQDN not specified.sh –u <userId> -p <pswd> [-n <network service name> | -i <network service ip address>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DHCPUtilization. an errorlevel of 0 is passed. $INCHOME/etc/cli/DHCPUtilization.netcontrol. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. Usage Example This example creates a task on the queue to perform a DHCP utilization collection for the dhcp5 DHCP server. the errorlevel returned will be a negative number.sh –u joe –p joepwd –n dhcp5 Return codes If the task is scheduled successfully. -v No Produces verbose output. Required only if Network Element Name not specified.DHCPUtilizationCLI –u <userId> -p <pswd> [-n <network service name> | -i <network service ip address>] [-?] Via command script (Unix) $INCHOME/etc/cli/DHCPUtilization. 23.sh –u joe –p joepwd –i corerouter1.diamondip.mycompany.sh –u joe –p joepwd –i 10.com.com This example creates a task to perform a Discover for the IPControl network element named router3.DiscoverNetElement DiscoverNetElement Overview The DiscoverNetElement CLI allows the user to issue an immediate Discover task to discover the interfaces bound to a network element already defined in IPControl. Usage Examples This example creates a task on the queue to perform a Discover for the device found at the IP address 10. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.mycompany.sh –u <userId> -p <pswd> [-n <network element name> | -i <netelement address>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DiscoverNetElement.cmd –u <userId> -p <pswd> [-n <network element name> | -i <netelement address>] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -i <IP Address | FQDN> Yes IP Address or fully-qualified domain name (FQDN) of the device to discover.10. Required only if IP Address or FQDN not specified. -n <Name> Yes Name of Network Element (device) to discover.sh –u joe –p joepwd –n router3 128 IPControl CLI and API Guide . $INCHOME/etc/cli/DiscoverNetElement.4. Required only if Network Element Name not specified.cli.netcontrol.4 This example creates a task to perform a Discover for the device with the DNS name corerouter1.23.DiscoverNetElementCLI –u <userId> -p <pswd> [-n <network element name> | -i <netelement address>] [-?] Via command script (Unix) $INCHOME/etc/cli/DiscoverNetElement. $INCHOME/etc/cli/DiscoverNetElement. $INCHOME/etc/cli/DiscoverNetElement.10. DiscoverNetElement Return codes If the task is scheduled successfully. along with a string including the task number. Com mand Line Interfaces (CLI) 129 . the errorlevel returned will be a negative number. an errorlevel of 0 is passed. If the task is NOT scheduled successfully. That task number can then be passed to the TaskStatus CLI to obtain the status of that task. and an error message will be printed to the console. unless –i specified Name of DNS server to configure. Specify this option to suppress that check.sh –u <userId> -p <pswd> [-n <Name> | -i <IP address>] [-a] [-c] [-d] [-g] [-k] [-s] [-w <View>] [-z <Zone>] [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/DnsConfigurationTask. the generated zone files are checked for errors. Specify this option to suppress that check. Set this option to continue with the deployment in spite of errors. the generated configuration file is checked for errors. while not interfering with the intended scavenging of dynamic records.DnsConfigurationTaskCLI –u <userId> -p <pswd> [-n <Name> | -i <IP address>] [-a] [-c] [-d] [-g] [-k] [-s] [-w <View>] [-z <Zone>] [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/DnsConfigurationTask.cmd –u <userId> -p <pswd> [-n <Name> | -i <IP address>] [-a] [-c] [-d] [-g] [-k] [-s] [-w <View>] [-z <Zone>] [-v] [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -i <IP Address> Yes. With –d. Without –c. -s No Sends only resource records created in IP Control.diamondip. unless –n specified IP Address of the DNS Server to configure. DNS Configuration tasks generate and deploy configuration and zone files for DNS servers. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. creates a task to push only changed zones. the task will abort if errors are detected during the configuration generation. only changed resource records are sent. -v No Verbose 130 IPControl CLI and API Guide . creates a task to send only changed resource records. Use this option to periodically refresh the records in Microsoft AD DNS to prevent their scavenging. -n <Name> Yes. -g No By default. -c No Changes only.DnsConfigurationTask DnsConfigurationTask Overview The DnsConfigurationTask CLI allows the user to create a DNS Configuration task. -a No By default. Without –d.ipcontrol.cli. With –c. all resource records are sent. -k No By default. Dynamic DNS (-d) must be specified. -d No Use Dynamic DNS instead of recreating configuration and zone files. Usage Examples This example creates a task to push any changed zone files to the server dns1.sh –u joe –p joepwd –n dns1 –z acme. Also. Com mand Line Interfaces (CLI) 131 . the zone file is checked for errors. That task number can then be passed to the TaskStatus CLI to obtain the status of that task. instead of the whole server. the errorlevel returned is a negative number. -z <Zone> No.sh –u joe –p joepwd –n dns1 This example creates a task to push any changed zone files to the server dns1.com This example creates a task to send all of resource records for the zone acme. the configuration file and zone files are checked for errors. an errorlevel of 0 is passed.com Return codes If the task is scheduled successfully.com to the server dns1. $INCHOME/etc/cli/DnsConfigurationTask. and an error message is ModifyBlockCLI printed to the console.DnsConfigurationTask Param eter Required Description -w <View> No View name.sh –u joe –p joepwd –c –n dns1 This example creates a task to push the zone file for zone acme. $INCHOME/etc/cli/DnsConfigurationTask.sh –u joe –p joepwd –d –n dns1 –z acme.sh –u joe –p joepwd –c –d –n dns1 –z acme.com This example creates a task to send the changed resource records for the zone acme. the value “Default” is used. along with a string including the task number. $INCHOME/etc/cli/DnsConfigurationTask.com via Dynamic DNS to the server dns1. Also. $INCHOME/etc/cli/DnsConfigurationTask. unless –w specified Zone name. $INCHOME/etc/cli/DnsConfigurationTask. Set this option to generate a configuration for this selected zone. The configuration file is pushed if needed.com via Dynamic DNS to the server dns1. If the task is NOT scheduled successfully. This might be needed when multiple views are in use and a single zone push is desired. The configuration file is pushed if needed. by default. by default. If not specified. months.GlobalRollupCLI –u <userId> -p <pswd> -t <#><period> [-?] Via command script (Unix) $INCHOME/etc/cli/GlobalRollup. where acceptable values are D. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. and an error message will be printed to the console. the errorlevel returned will be a negative number. along with a string including the task number. 132 IPControl CLI and API Guide .sh –u joe –p joepwd –t 90d This example creates a task on the queue to perform a Global Rollup. M. and to use the last 90 days of data when forecasting future growth. and to use the last 6 months of data when forecasting future growth. an errorlevel of 0 is passed. weeks. <#> indicates the number of periods. If the task is NOT scheduled successfully.sh –u joe –p joepwd –t 6m Return codes If the task is scheduled successfully. Y (days. That task number can then be passed to the TaskStatus CLI to obtain the status of that task.netcontrol. <period> indicates the period type.diamondip. W.cli.cmd –u <userId> -p <pswd> -t <#><period> [-?] Parameters Param eter Required Description -u <userId> Yes User Id -p <pswd> Yes Password -? No Print help -t <#><period> Yes Regression time periods. years). $INCHOME/etc/cli/GlobalRollup.GlobalRollup GlobalRollup Overview The GlobalRollup CLI allows the user to issue an immediate Global Rollup task to summarize collected utilization statistics and perform regression analysis.sh –u <userId> -p <pswd> -t <#><period> [-?] Via command script (Windows) %INCHOME%/etc/cli/GlobalRollup. Usage Examples This example creates a task on the queue to perform a Global Rollup. $INCHOME/etc/cli/GlobalRollup. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u joe –p joepwd –t netservice Return codes If the task is scheduled successfully. the errorlevel returned will be a negative number. $INCHOME/etc/cli/GlobalSync. Com mand Line Interfaces (CLI) 133 . along with a string including the task number.netcontrol.GlobalSyncCLI –u <userId> -p <pswd> -t <type> [-?] Via command script (Unix) $INCHOME/etc/cli/GlobalSync. $INCHOME/etc/cli/GlobalSync. If the task is NOT scheduled successfully.sh –u joe –p joepwd –t netelement This example creates a task on the queue to perform a Global Synchronization of all network services that are flagged in IPControl for inclusion in the Global Sync process.diamondip.cmd –u <userId> -p <pswd> -t <type> [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -t <type> Yes Indicates the type of Global Sync to perform. That task number can then be passed to the TaskStatus CLI to obtain the status of that task. Acceptable values are netelement or netservice. an errorlevel of 0 is passed.cli. and an error message will be printed to the console.sh –u <userId> -p <pswd> -t <type> [-?] Via command script (Windows) %INCHOME%/etc/cli/GlobalSync.GlobalSync GlobalSync Overview The GlobalSync CLI allows the user to issue an immediate Global Synchronization task for either network services or network elements. Usage Example This example creates a task on the queue to perform a Global Synchronization of all network elements that are flagged in IPControl for inclusion in the Global Sync process. 0/2003-12-16 10:35:38. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.sh –u joe –p joepwd –t 42 -v Output By default. Usage Example This example queries task 37 and returns a one-word string indicating the status: INPROGRESS $INCHOME/etc/cli/TaskStatus.cli.diamondip. Detailed information about the task will be displayed.netcontrol.TaskStatusCLI –u <userId> -p <pswd> -t <task number> [-v] [-?] Via command script (Unix) $INCHOME/etc/cli/TaskStatus. TaskStatus returns the status of the queried task as: NOTSTARTED QUEUED INPROGRESS COMPLETE 134 IPControl CLI and API Guide .0/00:03:00 $INCHOME/etc/cli/TaskStatus.sh –u joe –p joepwd –t 37 This example queries task 42 and returns detailed information about that task: 42/dhcp5/COMPLETE/2003-12-16 10:32:38.cmd –u <userId> -p <pswd> -t <task number> [-v] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -t <task number> Yes The task number to query.sh –u <userId> -p <pswd> -t <task number> [-v] [-?] Via command script (Windows) %INCHOME%/etc/cli/TaskStatus.TaskStatus TaskStatus Overview The TaskStatus CLI allows the user to query the status of tasks. -v No Verbose output. corresponding to the following table: Status Errorlevel NOTSTARTED 1 QUEUED 2 INPROGRESS 3 COMPLETE 4 COMPLETEWITHERRORS 5 ERROR 6 Com mand Line Interfaces (CLI) 135 .TaskStatus COMPLETEWITHERRORS ERROR Using the ‘-v’ parameter on the command line outputs detailed information about the task in the format: <id> /<scope> /<status> /<starttime> /<completedtime> /<duration> Return codes TaskStatus also returns an errorlevel indicating the task status. $INCHOME/etc/cli/DetachBlock.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [–v] [-?] Via command script (Windows) %INCHOME%/etc/cli/DetachBlock.csv file.reject file any records that could not be deleted.DetachBlock Updates DetachBlock Overview The DetachBlock CLI enables the user to detach blocks from device containers. See below for the required file format.netcontrol.txt 136 IPControl CLI and API Guide .sh –u joe –p joepwd –f blocks. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH task number com. and report errors to the detacherrors.csv –r blocks.cli. This CLI allows you to specify a file containing a list of blocks to detach. -v <verbose> No Produce verbose output. Usage Example This example detaches blocks listed in the blocks.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [–v] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV listing blocks to be detached. places into the blocks.diamondip.DetachBlockCLI –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [–v] [-?] Via command script (Unix) $INCHOME/etc/cli/DetachBlock.txt file.reject –e detacherrors. -e <error messages> No The name of the file that error messages will be reported in. -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in. or its address and size. Yes. unless block address and block size are specified B Block Address The address space of the block to be detached.g.1. that value must be used instead. Names can be in either short or long format. Yes. and the container it is to be detached from.g.255.2.0/24.DetachBlock File Format Specify the name of the block. Long format eliminates ambiguity in cases where there are duplicate container names. Col Field Accepted Values Required A Block Name The name of the block to be detached.0 network). 10. However. Long format example: IPControl/Texas/Dallas. Short format example: Dallas. if the block name was set manually during allocation. unless block name is specified D Container The name of the container from which to detach the block. e.255. This is typically the CIDR address: Address space/Block size.. unless block name is specified C Block Size The size of the block in short-notation (e. Yes. Yes Com mand Line Interfaces (CLI) 137 . 24 for a 255. cli. However. $INCHOME/etc/cli/JoinBlock.0/24 138 IPControl CLI and API Guide . this example assumes that there is only one block with this name in the system.g.2.0/24. -b <block name> Yes The name of the first block to be joined. If this parameter is supplied.ipcontrol.1. -c <container name> Must be specified if the block name is not unique.JoinBlockCLI –u <userId> -p <pswd> -b <block Name> [-c <container name>] [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/JoinBlock.sh –u <userId> -p <pswd> -b <block Name> [-c <container name>] [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/JoinBlock. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. the container is searched for the block to join. Usage Example This example joins the block 10. The name of the container holding the block.JoinBlock JoinBlock Overview The JoinBlock CLI allows the user to join existing. The blocks must be in the same container. and of the same type. forming a larger block. e.2.diamondip. the whole system is searched.1.cmd –u <userId> -p <pswd> -b <block Name> [-c <container name>] [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in. that value must be used instead.2.0/24 to the next adjacent block in the same container.sh –u joe –p joepwd –b 10. This is typically the CIDR address.1. adjacent blocks. This CLI allows you to specify a single block on the command line. 10. -e <error messages> No The name of the file that error messages will be reported in. Otherwise. if the block name was set manually during allocation. As mentioned above. Com mand Line Interfaces (CLI) 139 . The following table lists the available attributes for address pools and also indicates which can be used to locate a record.txt -r updateaddrpools.diamondip. See below for the required file format. Each line in the input file must have a set of attribute-value pairs to locate the address pool to be changed and a second set specifies what fields to change and their new values. -r <rejects file> No The name of the file that rejected records will be placed in.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV listing addrpools to be modified.netcontrol.sh –u joe –p joepwd -f updateaddrpools.err Output If successful.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyAddrpool. -e <error messages> No The name of the file that error messages will be reported in.reject –e updateaddrpool. File Format The ModifyAddrpool CLI uses attribute-value pairs to specify the records and fields to be changed. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.cli.ModifyAddrpoolCLI –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyAddrpool.ModifyAddrpool ModifyAddrpool Overview The ModifyAddrpool CLI alters existing address pools in the system. Usage Example $INCHOME/etc/cli/ModifyAddrpool. the CLI updates the address pools per the input file and exits. No Allow DHCP Client Classes allowClientClasses A list of Client Classes that are allowed in this address pools.ModifyAddrpool Field Attribute Nam e Accepted Values Locator Field Start Address startAddr The IP Address of the first address in the pool. No Deny DHCP Client Classes denyClientClasses A list of Client Classes that are NOT allowed in this address pools. ”Automatic NA DHCPv6”. Required End Address endAddr The IP Address of the last address in the pool. but not required unless Start address is not unique. ”Automatic TA DHCPv6” No Name name Address Pool name. The container is then used to uniquely determine the block that will contain the address pool. “Automatic DHCP”. “Reserved”. No Deprecated 140 IPControl CLI and API Guide . Yes. No Address Pool Type type One of “Dynamic DHCP”. This address must be in a block with an In-Use/Deployed status. No Container container The name of the container that holds the block in which the pool is defined. Defaults to “Start Address-End Address” No Share Name sharename The name used to link address pools together. Separate the list entries with a vertical bar “|”. In addition. Primary Net Service primaryNetService The name of the DHCP server that will serve addresses from this pool No Failover Net Service failoverNetService The name of the failover DHCP server that will serve addresses from this pool No DHCP Option Set dhcpOptionSet The name of an Option Set used with this pool. ”Dynamic TA DHCPv6”. “Static”. No DHCP Policy Set dhcpPolicySet The name of a Policy Set used with this pool. This address must be in the same block as the Start Address. Separate the list entries with a vertical bar “|”. the Start and End addresses must not overlap any other pools. This is required only if there is overlapping address space in use and the start address is in overlapping space. “Dynamic NA DHCPv6”. 3:endAddr=10.1.2.1.2.15 Separate multiple attribute-value pairs with commas. For example.1.3: startAddr=10.3:allowClientClasses=allow3 To update only some of the values in a list use the notation += when specifying the attribute and value.container=Private:endAddr=192.31 Some values are lists.1.3:allowClientClasses= V6 Addresses To specify an IPV6 address.2. to change both the end address and the DHCP Server for the address pool starting at 10.15.3:endAddr=10.1. to replace allow1 and allow2 with allow3 in the example above write: startAddr=10.ModifyAddrpool Each input line specifies the locator attribute-value pairs.2.168.primaryNetService=newserver This applies to the locator fields as well. to change the ending address for the pool starting at address 10.2. may be replaced or merged.168.2.3: startAddr=10. since : is part of the address: startAddr=2001::1:0#primaryNetService=newserver Com mand Line Interfaces (CLI) 141 .2.2. For example. if any.1.3: startAddr=10.0. to allow t wo Client Classes for the pool starting at 10.2. In the example above to allow a client class allow4 while keeping the allow3.3:allowClientClasses=allow1|allow2 For fields that are lists.2.1. For example.1. write: startAddr=10.3: allowClientClasses+=allow4 To remove a value.1.0.1.168. to remove the allowClientClasses from the above pool: startAddr=10. For example.2 in Container Private: startAddr=192.2. for the pool starting at 10. For example. followed by a colon.0.2.3. existing values. Separate the list elements with a vertical bar.1. # must be used as the separator between the locator pairs and the modification pairs. to change the end address for the pool starting at 192. followed by the modification attribute-value pairs.2. For example.1. specify the attribute but leave the value empty. Usage Example $INCHOME/etc/cli/ModifyBlock. Field Attribute Nam e Accepted Values Locator Field/ Modify? Block Address blockAddr The starting address of the block Yes / No 142 IPControl CLI and API Guide . -r <rejects file> No The name of the file that rejected records will be placed in.cli.diamondip.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyBlock. The following table lists the available attributes for blocks.ModifyBlockCLI –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyBlock.netcontrol.reject –e updateblock. See below for the required file format. Each line in the input file must have a set of attribute-value pairs to locate the block to be changed. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.txt -r updateblocks. and also indicates which can be used to locate a record.err Output If successful. the CLI updates the blocks per the input file and exits. -e <error messages> No The name of the file that error messages will be reported in.sh –u joe –p joepwd -f updateblocks.ModifyBlock ModifyBlock Overview The ModifyBlock CLI alters existing blocks in the system. and a second set specifies what fields to change and their new values.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV file describing the updates. File Format The ModifyBlock CLI uses attribute-value pairs to specify the records and fields to be changed. Org ID of the RIR Organization RIR rir Name of the RIR Organization No/ Yes Root Block Type rootBlocktype The Block Type for the block. Each element in the array has the format “name=value” where “name is the UDF tag name.) No / Yes Container container An array of container names Yes/ Yes ignoreErrors ignoreErrors True/false. “Aggregate”. for example. one of “Free”. “24” Yes / No Block Status blockStatus Block Status. No/ Yes SWIP Name swipname SWIP Name for ARIN blocks No/ Yes User Defined Fields userDefinedFields Array of user defined fields. Accepted values are true or false. (Validation associated with modifying a block’s block type will be applied. any errors occurring during a block reparent related to inconsistent user defined field templates will be ignored. Valid only for Deployed blocks. No/ Yes No/ Yes Exclude from Discovery excludeFromDiscovery Organization Id organizationId Flag indicating if this subnet should be included in Host Discovery tasks. “FullyAssigned” Yes / Yes Block Type blocktype A valid block type name. No/Yes Allocation Template Name allocationTemplate Name For a block with blockStatus=Deployed. No/Yes No/ Yes Com mand Line Interfaces (CLI) 143 . moving a block with a container/blocktype information template to a container which does not have the same template will normally cause an error. No/Yes Primary Subnet Flag primarySubnet Flag indicating if this subnet is primary. Use “\n” to separate lines. the name of the allocation template to use to create address pools from the newly created block. “Deployed”. If true. No /Yes Subnet subnet Block subnet policies. For instance. Valid only for Deployed blocks in device containers. To ignore the error (and lose the user defined fields associated with the old container) set the flag to ignoreErrors=true. Valid only for Deployed blocks. No/No Interface Name interfaceName The target interface name during a reparent of a Device Container. Accepted values are true or false. Yes / Yes Description description The block description.ModifyBlock Field Attribute Nam e Accepted Values Locator Field/ Modify? Block Name blockName The Name of the block Yes / Yes Block Size blockSize The CIDR size of the block. See below for syntax. “Reserved”. or if changing the blockStatus to Deployed. a target interface name must also be provided. No/Yes Each input line specifies the locator attribute-value pairs. For example. for the block at 10. followed by the modification attribute-value pairs.2.2.ModifyBlock Field Attribute Nam e Accepted Values Locator Field/ Modify? Address Allocation Details addrDetails Define attributes of any address allocations of the specified allocation template. For example.1. to remove the description from the above block: blockAddr =10. Separate the list elements with a vertical bar. For example.1. followed by a : or # . if any.1. to change the description for the block starting at address 10. to change the block status for a block: blockAddr=10.3:userDefinedFields=”state=PA”|”city=Exton” For values that are lists.1.1. to modify two user defined fields for the block at 10.3:userDefinedFields=”state=PA”|”city=Exton” To update only some of the values in a list use the notation += when specifying the attribute and value. write: blockAddr =10.3:description=”updated description”. In the example above to update the city as Devon without changing or removing the state value. rir=nationalISP This applies to the locator fields as well.2.2. See below for syntax. For example.3:description=”updated description” Separate multiple attribute-value pairs with commas. existing values. use ImportChildBlock with the overwrite option.1. specify the attribute but leave the value empty. # must be used as the separator between the locator pairs and the modification pairs. Reparenting a Block via ModifyBlockCLI The ModifyBlock CLI may also be used to reparent a block by specifying a target container name different than the current parent container name.2.3: blockAddr =10. to change both the description and the Organization Id for the block starting at 10.2.1. In the case of reparenting blocks contained in device containers.2. 144 IPControl CLI and API Guide . For example.3: blockAddr=10.2.2.3 to replace theentire contents of the existing userDefinedFields write: blockAddr =10. since : is part of the address: blockAddr=3FFE:0000:0000:0010::#description="updated V6 description" Updating Interface Addresses To modify a block’s interface address(es).3: description = V6 Addresses To modify an IPV6 block.3:blockStatus=Reserved Some values are lists. For example.1.2. may be replaced or merged.1.1.3:userDefinedFields+=”city=Devon” To remove a value.1.2.3: blockAddr=10. The server name or IP Address is valid.192.134 from a device container to the new device container Router1 on interface routerInterface1: blockAddr=192. Subnet uses a nested data structure syntax.0.168.0. For multiple servers.com.failoverDHCPServer=DHCPFailoverServer.1. No Failover DHCP Server failoverDHCPServer The name or IP Address of the failover DHCP Server for this address space.168.134:container=Router1.168.reverseDomainTypes=Default|Internal} The attributes for subnet are: Field Attribute Nam e Accepted Values Locator Field DHCP Option Set DHCPOptionsSet The name of a DHCP Option Set defined within IPControl that should apply to this subnet.arpa. No DHCP Policy Set DHCPPolicySet The name of a DHCP Policy Set defined within IPControl that should apply to this subnet.196.0:container=MovedTo To reparent the block starting at 192.primaryWINSServer=192.0 Policy Set.fo rwardDomains=test. No Default Gateway defaultGateway The default gateway address for this subnet.80. to update the policies for a block starting at 192. to reparent the block starting at 192. when a new container name different than current parent container has been specified.196. This address is supplied to DHCP clients on this subnet.192.134 (line wrapped for readability): blockAddr=192.0 to the new container MovedTo: blockAddr=192. For example.in-addr.primaryDHCPServer=DHC PServer.subnet={DHCPOptionsSet=Global Option Set.reverseDomains=10.168.defaultGateway=192.inaddr. The attributes of subnet policies are surrounded by braces. Both cannot be performed during the same modify block invocation.interfaceName=routerInterface1 Note: The Modify Block will either reparent.0: description=”modifying policies”.forwardDomainTypes=Default|Internal. No DNS Servers DNSServers The list of default DNS Servers for this subnet.80.arpa.196. separate the server names with a vertical bar (|). No Com mand Line Interfaces (CLI) 145 .168.com|example. This list is supplied to DHCP clients on this subnet. Modifying Block Subnet Policies Use the subnet field to specify changes to block subnet policies.DHCPPolicySet=Standard ISC DHCP 3.false.2.192.|10.168. or modify the block without a reparent.ModifyBlock For example..DNSServers=ServerABC. separated by a vertical bar (|). No Primary DHCP Server primaryDHCPServer The name or IP Address of the primary DHCP server for this address space. No Reverse Domain Types reverseDomainTypes The list of reverse domain types corresponding with the list in the reverseDomains field. Use forwardDomainTypes to specify the corresponding domain types. Multiple WINS servers may be specified. No Cascade Primary DHCP Server cascadePrimaryDHCPS erver If address pool or individual IP address objects within the subnet reference a specific DHCP server.ModifyBlock Field Attribute Nam e Accepted Values Locator Field Forward Domain Types forwardDomainTypes The list of forward domain types corresponding with the list in the forwardDomains field. No Primary WINS Server primaryWINSServer The IP Address of the primary WINS server for this subnet. separated by a vertical bar (|). separated by commas. No 146 IPControl CLI and API Guide . this attribute can be used to allow the ‘primaryDHCPServer’ attribute value to “cascade” to these address pool and IP address objects. No Reverse Domain Names reverseDomains The list of DNS reverse domains for this address space. separated by a vertical bar (|). No Forward Domain Names forwardDomains The list of DNS forward domains for this address space. Use reverseDomainTypes to specify the corresponding domain types. Used to provide this information to DHCP for Dynamic Address types. Not required when using the default domain type. Not required when using the default domain type. Note that address pool and IP address objects that are configured with “Same as Subnet” for the primary DHCP server will be unaffected. separated by a vertical bar (|). Yes Network Service Name netserviceName The name of the network service for this address allocation.168.ModifyBlock Applying an Allocation Template Use the addrDetails field to optionally specify attributes of any address allocations within the allocation template specified by allocationTemplateName.offsetFromBeginningOfSubnet=true:netserviceName=DHCPServer} The attributes for subnet are: Field Attribute Nam e Accepted Values Locator Field Starting Offset startingOffset Identify the address allocation within the template. description=”applying allocation template”. Yes Is the starting offset from the beginning of subnet? offsetFromBeginningOf Subnet Specify true or false. This must match the specification in the Allocation Template. allocationTemplateName=Standard DHCP. The addrDetails uses a nested data structure syntax. You can apply a template and specify address details when changing a block’s status to Deployed. This must match the specification in the Allocation Template. For example (line wrapped for readability): blockAddr=192. so its attributes are surrounded by braces. addrDetails={startingOffset=3. No Com mand Line Interfaces (CLI) 147 .0: blockStatus=Deployed.192. or when modifying a block that is already of status Deployed. 148 IPControl CLI and API Guide . Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. The following table lists the available attributes for containers and also indicates which can be used to locate a record. See below for the required file format.sh –u joe –p joepwd -f updatecontainers. Usage Example $INCHOME/etc/cli/ModifyContainer. then its value is not changed. If an attribute is not included in the modifier set. Each line in the input file uses an attribute-value pair to locate the container to be changed and a set of attribute-value pairs that specifies which attributes to modify.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyContainer.ModifyContainerCLI –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyContainer. the CLI updates the containers per the input file and exits.err Output If successful.diamondip.txt -r updatecontainers.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV file describing the modifications. -e <error messages> No The name of the file that error messages will be reported in. -r <rejects file> No The name of the file that rejected records will be placed in. File Format The ModifyContainer CLI uses attribute-value pairs to specify the records and fields to be changed.cli.reject –e updatecontainers. -v No Produces verbose output.ipcontrol.ModifyContainer ModifyContainer Overview The ModifyContainer CLI alters existing containers in the system. No Parent Container parentName The name of the parent container for this container. No Com mand Line Interfaces (CLI) 149 . the name must be the complete path beginning at the top of the container tree. Long format eliminates ambiguity in cases where there are duplicate container names. Names can be in either short or long format. leave it blank. If using the long format. separated by ‘|’. No Allowed Root Block Types allowedRootBlock Types A list of the block types enabled for root block creation. Yes Container Description description A brief description of the container. the first block type listed in allowedBlockTypes does not use an information template. No Allowed Block Types from Parent allowedAllocFrom ParentBlocktypes A list of the block types that can be used for space allocation from the parent container. Specify the templates in the same order as the block types in the allowedBlockTypes field.ModifyContainer Field Attribute Nam e Accepted Values Locator Field Container Name containerName The name of the container. To specify information templates for block types. No Allowed Block Types allowedBlockTypes A list of the valid block types for this container. No Block Type Information Templates blockTypeInfo Templates A list of the information templates to be used for block types. If no template is to be associated with a particular block type. separated by ‘|’. but include the separator. Short format example: Dallas. separated by ‘|’. Names can be in either short or long format. use the blockTypeInfoTemplates field. No Information Template informationTemplate The name of a pre-existing information template to be associated with this container. Modification indicates the container should be moved to a different parent container. Long format example: IPControl/Texas/Dallas. Use “\n” to separate lines. For example: blockTypeInfoTemplates= |template2 In this example. separated by ‘|’. The history records are created each time the Global Utilization Rollup task is run. If no template is to be associated with a particular device type. To specify information templates for devices. For example: deviceInfoTemplates= |template2 In this example. but include the separator. use “\n” to separate lines. No Maintain History Records maintainHistoryRecs Specify whether or not Container History and Block History records will be kept for all appropriate block types. No 150 IPControl CLI and API Guide . Accepted values are true or false.ModifyContainer Field Attribute Nam e Accepted Values Locator Field Require SWIP Name Block Types requireSWIPName BlockTypes A list of the block types for which SWIP names are required. separated by ‘|’. the valid values are on and off. No User Defined Fields userDefinedFields List of name=value parameters. use the deviceInfoTemplates field. No Allowed Device Types allowedDeviceTypes A list of the valid device types for this container. If not specified. If the UDF type is Checkbox. No Ignore disallowing a block type in use ignoreBlocktypeInUse Set this to “true” when disallowing a block type in use by the container. Specify the templates in the same order as the device types in the allowedDeviceTypes field. separated by ‘|’. indicated by the list in the allowedBlockTypes field. the first block type listed in allowedBlockTypes does not use an information template. separated by ‘|’. If the UDF type is Textarea. leave it blank. separated by ‘|’. defaults to false. No Device Information Templates deviceInfoTemplates A list of the information templates to be used for devices. Replace V6 DHCP Servers replaceDhcpServerV6 This is similar to the above “replaceDHCPServer” field. and when the modify operation involves moving a container. specify the name of a DHCP server which is “valid” for the target container. but will update any dynamic V6 objects and must be a V6 capable DHCP server. and IP Address objects that are moved as a result of the container move may become “invalid” with respect to the DHCP servers attached to the target container or target container’s nearest anscestor. which may have differing DHCP server associations along each container anscestory. when replacing DHCP servers in objects during a container move operation.This attribute applies when moving a logical container with a mulitparented device container along the logical container ancestory. Address Pool. No This will update only dynamic V4 objects and must be a V4 capable DHCP server. In this situation. Note: Multiparented device containers cannot be moved using CLIs. This flag indicates if those changes should affect objects attached to multiparented device containers. No Apply Replace DHCP to Multiparented Device Containers applyDhcpToMultipar entDevContainer This attribute is used only in conjunction with the ‘replaceDhcpServer’ attribute.ModifyContainer Field Attribute Nam e Accepted Values Locator Field Replace DHCP Servers replaceDhcpServer This attribute is used only when utilizing the IPControl feature of attaching DHCP servers to Containers. In order to update these objects’ associated DHCP servers as part of the container move operation. Subnet. No Com mand Line Interfaces (CLI) 151 . specify the list of templates in the same order as the list of block or device types. specify the attribute but leave the value empty. For example. to change both the description and the information template for the container East: containerName=East:description=new description. to set user defined fields for container East: containerName=East:userDefinedFields=”udf1=value1”|”udf2=value2” For fields that are lists. while blocktype1 and blocktype2 use newTemplate. In the example above. For example.ModifyContainer Each input line specifies the locator attribute-value pair. and Switch uses newTemplate. blockTypeInfoTemplates=|newT emplate|newTemplate. if any. may be replaced or merged. followed by the modification attribute-value pairs. write: containerName=East:userDefinedFields+=”city=Devon” To remove a value.deviceInfoTemplates=xTemplate| xtemplate|newTemplate In the above example. existing values. followed by a colon. write: containerName=East:userDefinedFields=”state=PA”|”city=Exton” To update only some of the values in a list use the notation += when specifying the attribute and value. 152 IPControl CLI and API Guide . to remove the description for container East: containerName=East:description= To modify information templates for block and device types. for container East. to change the description for the container East: containerName=East:description=new description Separate multiple attribute-value pairs with commas. For example.allowedDeviceTypes=Printer|Router|Switch. to set block types for the container East: containerName=East:allowedBlockTypes=Any|blocktyp1|blocktyp2 User Defined Fields use a nested attribute=value syntax. For example: containerName=East:allowedBlockTypes=Any|blocktype1|blocktype2. to update the city as Devon without changing or removing the state value.informationTemplate=templateName For fields that are lists. For example. For example. block type Any has no template. Device types Printer and Router use xTemplate. to replace the entire contents of the existing user defined fields. separate the list elements with a vertical bar. For example. Usage Example $INCHOME/etc/cli/ModifyDevice. File Format The ModifyDevice CLI uses attribute-value pairs to specify the records and fields to be changed.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV file describing the modifications. -r <rejects file> No The name of the file that rejected records will be placed in.sh –u joe –p joepwd -f updatedevices.err Output If successful.ModifyDeviceCLI –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyDevice. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.reject –e updatedevices.ModifyDevice ModifyDevice Overview The ModifyDevice CLI alters existing devices in the system.cli. then its value is not changed.diamondip. Com mand Line Interfaces (CLI) 153 . The following table lists the available attributes for devices and also indicates which can be used to locate a record. If an attribute is not included in the modifier set. the CLI updates the devices per the input file and exits. Each line in the input file must have a set of attribute-value pairs to locate the device to be changed and a second set that specifies what attributes to modify.netcontrol. -e <error messages> No The name of the file that error messages will be reported in. See below for the required file format.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyDevice.txt -r updatedevices. the reverse domain must exist in order for the PTR record to be added. No . if IP Address in overlapping space.ModifyDevice Field Attribute Nam e Accepted Values Locator Field IP Address ipAddress The IP Address of the Device. Yes MAC Address MACAddress The Hardware MAC Address of the device. No Device Type deviceType The device type of the device. separated by a vertical bar. Defaults to “Default” No Duplicate Warning dupWarning Set this to “true” if duplicate warnings should be ignored. Should be one of the values defined in the system. Yes Hardware Type hwType Ethernet or Token Ring No Resource Record Flag resourceRecordFlag Accepted values are true or false. Automatic DHCP. the valid values are on and off. use “\n” to separate lines. and Reserved. Yes Address Type addressType The address type of this device. If not specified. No Container container The Container that holds the block for the IP Address. Also. No Domain Type domainType The domain type of the domain. If the UDF type is Checkbox. resource records will be generated for the device. Defaults to “Unspecified” No Domain Name domainName The name of the domain for this device. defaults to false. No The resource records associated with the device will be updated when the hostname or IP Address changes regardless of this setting. Manual DHCP. If the flag is “true” and there are no resource records associated with the device. Dynamic DHCP. If the UDF type is Textarea. No Host Name hostname The device Host name. Use “\n” to separate lines. User Defined Fields 154 IPControl CLI and API Guide userDefinedFields List of name=value parameters. Yes. Accepted values are: Static. Description description Text Description of the device. Note that the domain name must be specified if the block policy has no forward domains. For example.3:hostname=newhostname Separate multiple attribute-value pairs with commas.1.3:userDefinedFields+=”city=Devon” Com mand Line Interfaces (CLI) 155 . to replace entire contents of the existing user defined fields.3: ipAddress=10. write: ipAddress=10.0. to change the hostname for the device at address 10.2.2. if the address type is Dynamic DHCP.0. or Manual DHCP.3:userDefinedFields=”udf1=value1”|”udf2=value2” For fields that are lists. and interfaces values are lists.3: ipAddress=10. separated by a vertical bar.1.1.2. to set two aliases for the device at 10.3. to change the hostname for the device at 192.2. then the DHCP server must be “valid” for the container where the device resides.1. Separate the list elements with a vertical bar.168. In the example above. Only used if the resource record flag is set.2.168.2. write: ipAddress=10. the += notation does not apply to Interfaces when modifying multihome devices.2.2.3: ipAddress=10. Please note.3:aliases=alias1|alias2 User Defined Fields use a nested attribute=value syntax. For example.2.1. existing values. For example. user defined fields.container=Private:hostname=newhostname Aliases. No Primary DHCP Server primaryDhcpServer The name of the Primary DHCP server for this device.1.1. followed by a colon. Automatic DHCP.2. followed by the modification attribute-value pairs.1.3: ipAddress=10.1.1. For example.description=”New Host” This applies to the locator fields as well.2. For example. if any.3:userDefinedFields=”state=PA”|”city=Exton” To update only some of the values in a list use the notation += when specifying the attribute and value. to change both the hostname and the description for the device at 10. See below for syntax. to set a user defined field for IP Address 10.2. for IP Address 10. No Each input line specifies the locator attribute-value pairs.3:hostname=newhostname. Use this to modify a multi-home device. may be replaced or merged.ModifyDevice Field Attribute Nam e Accepted Values Locator Field Aliases aliases List of alias names. For example.2 in Container Private: ipAddress=192.1. If utilizing the IPControl feature of attaching DHCP servers to Containers. No Interfaces interfaces List of interfaces. to update the city as Devon without changing or removing the state value. 4} Note: When adding or updating interfaces.2.ModifyDevice To remove a value. such as: hostname=newhostname:interfaces={name=Default}|{name=eth0. Instead. To update the IP Addresses or MAC Addresses.4} To update the interfaces for the device with hostname newhostname and to ‘add’ new interfaces. all the existing interfaces need to be listed.2. specify the attribute but leave the value empty.1. It is a must. and then specify the new interfaces along with their attributes as given in the table above.ipAddress=10.2.3}| {name=eth1:ipAddress=10.1.1.2. To locate a multi-home device. To do this.1. to include the {name=Default} interface in the syntax.2.2. Interfaces use a nested data structure syntax.1. use commas between the interface attributes (line wrapped for readability): hostname=newhostname:interfaces={name=Default}{name=eth0. to remove the description from the above device: ipAddress=10.1.1.ipAddress=10. specify them as attributes of the interfaces. do NOT use the ipAddress or MACAddress primary attributes. use colons between the interface attributes (line wrapped for readability): hostname=newhostname:interfaces={name=Defau lt}|{name=eth0:ipAddress=10.4} The attributes for interfaces are: Field Attribute Nam e Accepted Values Locator Field Name Name Interface Name Yes IP Address ipaddress IP Address of the interface Yes MAC Address macAddress Hardware MAC Address of the interface Yes Hardware Type hwType Ethernet or Token Ring No Sequence Sequence Reserved No Note: It is possible to convert a single-homed device into a multi-homed device by specifying the interfaces as shown above. or any of its IP Addresses or MAC addresses. V6 Addresses To specify an IPV6 address. specify either the device’s host name.description=”New Host” 156 IPControl CLI and API Guide .3:description= Modifying a Multi-Home Device Working with Multi-Home devices is more complex.3}| {name=eth1. Any interfaces not specified will get deleted. For example.ipAddress=10. For example: To update the interfaces for the device with hostname newhostname and to ‘modify’ their IP Address. since : is part of the address: ipAddress= 2001::2#hostname=newhostname.3}| {name=eth1.2. # must be used as the separator between the locator pairs and the modification pairs. use the device’s hostname or IP Address as a locator.ipAddress=10. diamondip.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyDeviceResourceRecord.txt -r updatedeviceresourcerecs.cli. Com mand Line Interfaces (CLI) 157 .ModifyDeviceResourceRecord –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyDeviceResourceRecord. -r <rejects file> No The name of the file that rejected records will be placed in. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. The following table lists the available attributes for device resource records and also indicates which can be used to locate a record.reject –e updatedeviceresourcerecs.err Output If successful. the CLI updates the device resource records per the input file and exits. -e <error messages> No The name of the file that error messages will be reported in. See below for the required file format.ipcontrol.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV file describing the modifications. Usage Example $INCHOME/etc/cli/ModifyDeviceResourceRecord.ModifyDeviceResourceRecord ModifyDeviceResourceRecord Overview The ModifyDeviceResourceRecord CLI alters existing device resource records in the system.sh –u joe –p joepwd -f updateeviceresourcerecs. File Format The ModifyDeviceResourceRecord CLI uses attribute-value pairs to specify the records and fields to be changed Each line in the input file must have a set of attribute-value pairs to locate the resource record to be changed and a second set specifies what fields to change and their new values. Refer to the appropriate RFC for exact text that should be entered. defaults to IN. Comment comment Text to be appended to the resource record. Note that this section is specific to the type of resource record. The container is then used to uniquely determine the device. Defaults to “Default” Yes/No Owner owner The OWNER section of the resource record. Note that this section is specific to the type of resource record. No/No 158 IPControl CLI and API Guide . Yes/Yes Domain Type domainType The domain type of the domain. unless ipAddress is specified IP Address ipAddress The IP Address of the Device. Refer to the appropriate RFC for exact text that should be entered. Yes/Yes. unless required to uniquely identify the record. Yes/Yes. Yes/Yes Host Name hostname The device host name. Yes/Yes Data data The text for the DATA area of the resource record. This is required only if there is overlapping address space in use and the ip address is in overlapping space.ModifyDeviceResourceRecord Field Attribute Nam e Accepted Values Locator Field/ Required? Domain Name domain The name of the domain for this resource record. Yes/No TTL TTL The Time to Live No/No Class resourceRecClass The value currently supported is IN. Yes/No. Yes/No Resource Record Type resourceRecType The type of resource record being updated. unless hostname is specified Container container The name of the container that holds the device. If not specified. owner=10.hostname=router00001. to remove the description from the above device: domain=40.ModifyDeviceResourceRecord Each input line specifies the locator attribute-value pairs.10 To remove a value.resource RecType=A:comment= V6 Addresses To specify an IPV6 address.hostname=router00001. specify the attribute but leave the value empty.arpa.10.resourceRecClass=IN.10.. For example. # must be used as the separator between the locator pairs and the modification pairs..inaddr. and the device in both spaces have A records with identical owners.arpa.ipAddress=3FFE:0000:0000:0015 ::.inaddr.10.owner=10.resource RecType=A:owner=30.10. to change the owner for a record: domain=40.resourceRecType=AAAA#TTL=2400 Note on overlapping space: If the device is in overlapping space. if the administrator’s role does not indicate “Ignore” for "Allow Duplicate A Record (Owner) Checking".resourceRecClass=IN. Com mand Line Interfaces (CLI) 159 .10.10.inaddr.com".owner=10.ins.domainType=Default.owner=router00015.arpa.hostname=router00001.res ourceRecClass=IN.com.resource RecType=A:data="newDNS.. followed by the modification attribute-value pairs. this CLI will fail with “Duplicate Resource Record”. to change the data and TTL for a record: domain=40.domainType=Default.domainType=Default. followed by a colon.TTL=2400 This applies to the locator fields as well.domainType=Default. since : is part of the address: domain=example. For example. For example.resourceRecClass=IN. -e <error messages> No The name of the file that error messages will be reported in.ModifyDhcpServer ModifyDhcpServer Overview The ModifyDhcpServer CLI alters existing DHCP servers in the system.txt -r updatedhcp. The following table lists the available attributes for DHCP servers and also indicates which can be used to locate a record.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV file describing the modifications. 160 IPControl CLI and API Guide .cli. If an attribute is not included in the modifier set. See below for the required file format.ModifyDhcpServerCLI –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyDhcpServer.reject –e updatedhcp. then its value is not changed.sh –u joe –p joepwd -f updatedhcp. Usage Example $INCHOME/etc/cli/ModifyDhcpServer. Each line in the input file must have a set of attribute-value pairs to locate the DHCP server to be changed and a second set specifies what attributes to change.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyDhcpServer. -r <rejects file> No The name of the file that rejected records will be placed in. File Format The ModifyDhcpServer CLI uses attribute-value pairs to specify the records and fields to be changed.diamondip. the CLI updates DHCP servers per the input file and exits.err Output If successful.ipcontrol. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. No Collection Type collectionType SCP or FTP or CNRSDK No Collection Port collectionPort 1-65535 No Collection User collectionUser No Collection Password collectionPassword Valid account for SCP/FTP on Executive. No Default Threshold defaultThreshold 0-100 No Global Sync globalSync True or False No Configuration Path configPath Valid file name on host system. No Lease Path leasePath Valid file name on host system. No DHCP Client Classes clientClasses Valid DHCP Client Classes defined in IPControl. CLI Command cliCommand Valid file name on host system. No Start Script startScript Valid file name on host system. No Configuration Postextension endExtension Test or file name.ModifyDhcpServer Field Attribute Nam e Accepted Values Locator Field Name name The Name of the DHCP server Yes IP Address ipAddress The IP Address of the DHCP Server. No DHCP Failover IP Address failoverIpAddress Valid IP Address No DHCP Failover Port failoverPort 1-65535 No Configuration PreExtension beginExtension Text or file name. No CLI User Name cliUserName Valid user for collection program. True or False DHCP Option Set optionSet Valid Option Set defined in IPControl No DHCP Policy Set policySet Valid Policy Set defined in IPControl. separated by a vertical bar (“|”). ‘v6’ or ‘both’ No No No Com mand Line Interfaces (CLI) 161 . Yes Product product The DHCP server product name defined in IPControl. No Stop Script stopScript Valid file name on host system. No Agent agent The name of an agent defined in IPControl. No V4V6Both v4v6both ‘v4’. File names must be prefixed by “file:”. Password for collection user. No CLI Password cliPassword Password for collection program No CLI Arguments cliArgs No Dynamic DNS ddns Arguments to pass to collection command. File names must be prefixed by “file:”. if any. write: containerName=East: allowClientClasses+=allow4 Separate multiple attribute-value pairs with commas.2.1. to change both the option set and the client classes for the server at 10.2.3:clientClasses=allow1|allow2|deny3 For fields that are lists separated by vertical bars.1. to replace existing client classes with allow3 in the example above. to use the contents of the file beginext. # must be used as the separator between the locator pairs and the modification pairs.3: ipAddress=10. to allow a client class allow4 while keeping the allow3. In the example above.1.1.2. may be replace d or merged.txt as the extension at the beginning of the configuration file: name=dhcp123. simply omit it from the modification attribute-value pairs.3. followed by a colon.3: ipAddress=10. for the server at address 10.com:beginExtension=file:beginext.3:allowClientClasses=allow3 To update only some of the values in a list use the notation += when specifying the attribute and value.2. write: startAddr=10.clientClasses=allow1|allow2|deny3 The configuration extension fields can directly contain text or can specify a file name. For example.2.txt V6 Addresses To specify an IPV6 address. existing values.2.1. since : is part of the address: ipAddress=3FFE:0000:0000:0015::#clientClasses=allow1|allow2|deny3 162 IPControl CLI and API Guide . to change the Client Classes for the server at address 10.3:optionSet=OptionSet1. For example.ModifyDhcpServer Each input line specifies the locator attribute-value pairs.1. To leave an attribute unchanged. followed by the modification attribute-value pairs. For example.com. For example. cli. Usage Example $INCHOME/etc/cli/ModifyDomainResourceRecord. The following table lists the available attributes for domain resource records and also indicates which can be used to locate a record.diamondip. See below for the required file format.reject –e updatedomainresourcerecs. Com mand Line Interfaces (CLI) 163 .ModifyDomainResourceRecord –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyDomainResourceRecord. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV file describing the modifications. -e <error messages> No The name of the file that error messages will be reported in.sh –u joe –p joepwd -f updatedomainresourcerecs. Each line in the input file must have a set of attribute-value pairs to locate the resource record to be changed and a second set specifies what fields to change and their new values.ModifyDomainResourceRecord ModifyDomainResourceRecord Overview The ModifyDomainResourceRecord CLI alters existing domain resource records in the system. the CLI updates the domain resource records per the input file and exits. -r <rejects file> No The name of the file that rejected records will be placed in.ipcontrol.txt -r updatedomainresourcerecs.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyDomainResourceRecord. File Format The ModifyDomainResourceRecord CLI uses attribute-value pairs to specify the records and fields to be changed.err Output If successful. specify the attribute but leave the value empty.inaddr..10. defaults to IN.resourceRecClass=IN. Note that this section is specific to the type of resource record.10 To remove a value. followed by a colon.arpa. TTL=2400 This applies to the locator fields as well.resourceRecType=A:data="newDNS. Refer to the appropriate RFC for exact text that should be entered.10. to change the data and TTL for a record: domain=40. Yes/Yes Domain Type domainType The domain type of the domain.10.owner=10. Yes/Yes TTL TTL The Time to Live No/No Class resourceRecClass The value currently supported is IN.resourceRecType=A:comment= 164 IPControl CLI and API Guide .10.arpa.. If not specified. Refer to the appropriate RFC for exact text that should be entered.ins. followed by the modification attribute-value pairs.domainType=Default.inaddr. No/No Each input line specifies the locator attribute-value pairs. Yes/No Comment comment Text to be appended to the resource record.resourceRecClass=IN. resourceRecClass=IN.domainType=Default.domainType=Default.. Defaults to “Default” Yes/No Owner owner The OWNER section of the resource record. Yes/Yes Data data The text for the DATA area of the resource record. For example.com".10. Note that this section is specific to the type of resource record. For example. For example.arpa.resourceRecType=A:owner=30.in-addr.owner=10. to remove the description from the above device: domain=40. to change the owner for a record: domain=40. Yes/No Resource Record Type resourceRecType The type of resource record being updated.owner=10.ModifyDomainResourceRecord Field Attribute Nam e Accepted Values Locator Field/Required Domain Name domain The name of the domain for this resource record.10. ModifyDomainResourceRecord Note on overlapping space: If there are A records in overlapping space with identical owners, if the administrator’s role does not indicate “Ignore” for "Allow Duplicate A Record (Owner) Checking", this CLI will fail with “Duplicate Resource Record”. V6 Addresses To specify an IPV6 address, # must be used as the separator between the locator pairs and the modification pairs, since : is part of the address: domain=example.com,domainType=Default,owner=router00015,data=3FFE:0000:0000:0015 ::,resource RecClass=IN,resourceRecType=AAAA#TTL=2400 Com mand Line Interfaces (CLI) 165 ModifyNetElementInterface ModifyNetElementInterface Overview The ModifyNetElementInterface CLI alters existing Network Element Interfaces in the system. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.diamondip.ipcontrol.cli.ModifyNetElementInterfaceCLI –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyNetElementInterfaceCLI.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyNetElementInterfaceCLI.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV file describing the modifications. See below for the required file format. -r <rejects file> No The name of the file that rejected records will be placed in. -e <error messages> No The name of the file that error messages will be reported in. Usage Example $INCHOME/etc/cli/ModifyNetElementInterfaceCLI.sh –u joe –p joepwd -f updatenei.txt -r updatenei.reject –e updatenei.err Output If successful, the CLI updates Network Element Interfaces per the input file and exits. File Format The ModifyNetElementInterface CLI uses attribute-value pairs to specify the records and fields to be changed. Each line in the input file must have a set of attribute-value pairs to locate the Network Element Interface to be changed and a second set that specifies what attributes to change. If an attribute is not included in the modifier set, then its value is not changed. The following table lists the available attributes for Network Element Interfaces and also indicates which can be used to locate a record. 166 IPControl CLI and API Guide ModifyNetElementInterface Field Attribute Nam e Accepted Values Locator Field/ Required Network Element Name netElementName The Name of the Network Element Yes/Yes Interface Name interfaceName The name of the interface Yes/Yes Status status The interface status. This can be one of “Disabled”, “Enabled”, or “Deployed”. No/No Each input line specifies the locator attribute-value pairs, followed by a colon, followed by the modification attribute-value pairs. To leave an attribute unchanged, simply omit it from the modification attribute-value pairs. Separate multiple attribute-value pairs with commas. For example, to change a network element’s interface name and status: netElementName=RouterOne,interfaceName=Ethernet1:interfaceName=NewName,status =Enabled Com mand Line Interfaces (CLI) 167 ModifyPendingApproval ModifyPendingApproval Overview The ModifyPendingApproval CLI enables the approval or rejection of changes submitted to the administrator’s pending approval queue. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.diamondip.ipcontrol.cli.ModifyPendingApprovalCLI –u <userId> -p <pswd> -f < update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyPendingApproval.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyPendingApproval.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV file containing modify instructions. See below for the required file format. -r <rejects file> No The name of the file that rejected records will be placed in. -e <error messages> No The name of the file that error messages will be reported in. Usage Example $INCHOME/etc/cli/ModifyPendingApproval.sh –u joe –p joepwd -f pendingapprovals.csv -r pendingapprovals.reject –e pendingapprovals.err Output If successful, the CLI approves and rejects changes per the input file and exits. File Format The ModifyPendingApproval CLI uses attribute-value pairs to specify the records and action to be taken. Each line in the input file must have an attribute-value pair to locate the pending approval record to be resolved followed by a set that specifies the action to be taken. The following table lists the available attributes for this CLI. 168 IPControl CLI and API Guide ModifyPendingApproval Field Attribute Nam e Accepted Values Locator Field Workflow id workflowId The id of the pending approval request retrieved using an ExportItemPendingApprovalCLI, for example, ExportResourceRecordPendingApproval. Yes Action action Specify “Approve” or “Reject”. (required) No Reason reason Reason for rejection (optional) No Each input line specifies the locator attribute-value pair, followed by a colon, followed by the optional modification attribute-value pairs. For example, to reject a pending approval: workflowId=1018:action="Reject",reason=”change not appropriate at this time” Com mand Line Interfaces (CLI) 169 ModifyPrefixPool ModifyPrefixPool Overview The ModifyPrefixPool CLI alters existing prefix pools in the system. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com.diamondip.ipcontrol.cli.ModifyPrefixPoolCLI –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/ModifyPrefixPool.sh –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/ModifyPrefixPool.cmd –u <userId> -p <pswd> -f <update filename> [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -f <update filename> Yes The name of the CSV file containing modify instructions. See below for the required file format. -r <rejects file> No The name of the file that rejected records will be placed in. -e <error messages> No The name of the file that error messages will be reported in. Usage Example $INCHOME/etc/cli/ModifyPrefixPool.sh –u joe –p joepwd -f updateprefixpools.txt -r updateprefixpools.reject –e updateprefixpool.err Output If successful, the CLI updates the prefix pools per the input file and exits. File Format The ModifyPrefixPool CLI uses attribute-value pairs to specify the records and fields to be changed. Each line in the input file must have a set of attribute-value pairs to locate the prefix pool to be changed and a second set specifies what fields to change and their new values. The following table lists the available attributes for prefix pools and also indicates which can be used to locate a record. 170 IPControl CLI and API Guide ModifyPrefixPool Field Attribute Nam e Accepted Values Locator Field Start Address startAddr The IP Address of the first address in the pool. This address must be in a block with an In-Use/Deployed status. Required Length length The length of the prefix pool No Address Pool Type type One of “Dynamic PD DHCPv6”, “Automatic PD DHCPv6”. No Name name Address Pool name. Defaults to “Start Address/Length” No Container container The name of the container that holds the block in which the pool is defined. This is required only if there is overlapping address space in use and the start address is in overlapping space. The container is then used to uniquely determine the block that will contain the address pool. Yes, but not required unless Start address is not unique. Delegated Prefix Length delegatedPrefixLen gth Length of the delegated prefixes. No Shortest Prefix Length shortestPrefixLengt h Shortest possible prefix to delegate. CNR only. No Longest Prefix Length longestPrefixLengt h Longest possible prefix to delegate. CNR only. No Primary Net Service primaryNetService The name of the DHCP server that will serve addresses from this pool No DHCP Option Set dhcpOptionSet The name of an Option Set used with this pool. No DHCP Policy Set dhcpPolicySet The name of a Policy Set used with this pool. No Allow DHCP Client Classes allowClientClasses A list of Client Classes that are allowed in this prefix pool. Separate the list entries with a vertical bar “|”. No Deny DHCP Client Classes denyClientClasses A list of Client Classes that are NOT allowed in this prefix pool. Separate the list entries with a vertical bar “|”. No Com mand Line Interfaces (CLI) 171 to allow two Client Classes for the pool starting at 2001:db8:0:1:: startAddr=2001:db8:0:1::#allowClientClasses=allow1|allow2 For fields that are lists. write: startAddr=2001:db8:0:1::#allowClientClasses+=allow4 To remove a value. For example. For example. followed by a pound sign. if any. For example. to change the length for the pool starting at 2001:db8:0:1:: in Container Private: startAddr=2001:db8:0:1::. specify the attribute but leave the value empty. Separate the list elements with a vertical bar. In the example above to allow a client class allow4 while keeping the allow3. For example. to change both the length address and the DHCP Server for the address pool starting at 2001:db8:0:1:: startAddr=2001:db8:0:1::#length=66. may be replaced or merged. to remove the allowClientClasses from the above pool: startAddr=2001:db8:0:1::#allowClientClasses= 172 IPControl CLI and API Guide . For example. followed by the modification attribute-value pairs. to replace allow1 and allow2 with allow3 in the example above write: startAddr=2001:db8:0:1::#allowClientClasses=allow3 To update only some of the values in a list use the notation += when specifying the attribute and value.ModifyPrefixPool Each input line specifies the locator attribute-value pairs.container=Private#length=66 Some values are lists. to change the length for the pool starting at address 2001:db8:0:1:: startAddr=2001:db8:0:1::#length=66 Separate multiple attribute-value pairs with commas. for the pool starting at 2001:db8:0:1::. For example.primaryNetService=newserver This applies to the locator fields as well. existing values. -q <equal sizes> No Specify true or false.cli.ipcontrol. This parameter works in conjunction with the “equalSizes” parameter. the start address of the block being split will be used. -b <block name> Yes The name of the block to be split. If no start address is specified. If true. -e <error messages> No The name of the file that error messages will be reported in. that value must be used instead. e. -c <container name> Must be specified if the block name is not unique. This is typically the CIDR address. Note that splitting a block attached to multiple containers is not supported via the CLI.SplitBlockCLI –u <userId> -p <pswd> -b <block Name> [-c <container name>] [-t <target start address>] [-s <target size>] [-q <equal sizes>] [-r <rejects file>] [-e <error messages>] [-?] Via command script (Unix) $INCHOME/etc/cli/SplitBlockCLI. However. Otherwise. The name of the container holding the block. If this parameter is supplied. the container is searched for the block to join. 10.0/24.2. If false.1. The default is false. if the block name was set manually during allocation. the block is split such that the fewest number of new blocks is created.g. the whole system is searched. -s <target size> Yes The desired CIDR block size after the split. the block is split such that all resulting blocks have the “target size” CIDR size. This CLI allows you to specify a single block on the command line.SplitBlock SplitBlock Overview The SplitBlock CLI allows the user to split an existing block into smaller blocks.sh –u <userId> -p <pswd> -b <block Name> [-c <container name>] [-t <target start address>] [-s <target size>] [-q <equal sizes>] [-r <rejects file>] [-e <error messages>] [-?] Via command script (Windows) %INCHOME%/etc/cli/SplitBlockCLI. This is useful for creating a block using the specified start address and target block size.cmd –u <userId> -p <pswd> -b <block Name> [-c <container name>] [-t <target start address>] [-s <target size>] [-q <equal sizes>] [-r <rejects file>] [-e <error messages>] [-?] Parameters Param eter Required Description -u <userId> Yes Username -p <pswd> Yes Password -? No Print help -r <rejects file> No The name of the file that rejected (non-deleted) records will be placed in.diamondip. Com mand Line Interfaces (CLI) 173 . Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. -t <target start address> No The start address of the target block. along with two blocks of “targetSize”. 0/24 –s 27 –q true 174 IPControl CLI and API Guide . the result would be one /25.1.1. one /26 and two /27 blocks.2.SplitBlock Usage Example This example splits the block 10.0/24 into 8 /27 blocks.sh –u joe –p joepwd –b 10. $INCHOME/etc/cli/SplitBlock.2. If –e were false. The next lowest or highest IP address within the range will be assigned a type of “Static” and a status of “in-use”. When “true”. there should be a range of addresses with a type of “Reserved” and a status of “reserved” for the given device type. Defaults to “false”. If a hostname is specified.ipcontrol. In addition.cmd –u <userId> -p <pswd> -b <blockaddress> –d <devicetype> [-h <hostname>] [-r <rr flag>] [-?] Parameters Param eter Required Description -u <Username> Yes Username -p <pswd> Yes Password -? No Print help -b <block address> Yes The address of an “In Use/Deployed” block containing “reserved” type addresses. -r <resource record flag> No. for the specified device type. of the device type specified in the –d parameter. it will be applied to the device associated with the IP Address. not in address pools. there is an option to add resource records for the device.diamondip.UseNextReservedIPAddress –u <userId> -p <pswd> -b <blockaddress> –d <devicetype> [-h <hostname>] [-r <rr flag>] [-?] Via command script (Unix) $INCHOME/etc/cli/UseNextReservedIPAddress.UseNextReservedIPAddress UseNextReservedIPAddress Overview The UseNextReservedIPAddress CLI is used to mark the next reserved IP Address in the specified block. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. to in-use. will be applied to the device associated with the IP Address. Within this block. The block must have a status of “In Use/Deployed”. This CLI should not be used with address pools with a status of “reserved”. resource records will be added for the device.sh –u <userId> -p <pswd> -b <blockaddress> –d <devicetype> [-h <hostname>] [-r <rr flag>] [-?] Via command script (Windows) %INCHOME%/etc/cli/UseNextReservedIPAddress. -d <device type> Yes Device type of address to mark in-use. -h <host name> No If specified.cli. Com mand Line Interfaces (CLI) 175 . Specify “true” or “false”. 10. 176 IPControl CLI and API Guide . The DhcpRelease CLI is used to force the release of a DHCP lease. Usage Examples This example releases the lease for IP address 10.0.DhcpRelease Utilities DhcpRelease Overview Please note that the DhcpRelease CLI is applicable only for DHCPv4 environments.1) -m <macaddr> Yes Client MAC address formatted as hexadecimal characters separated by colons – e. this CLI will create a DHCP Release packet identifying the client’s hardware address and IP address.cli.diamondip. See below for the required file format.10. The DHCP server will then free the lease as if the release was sent from the actual client. This CLI can be used in lieu of performing a release of the lease from the client itself.g.cmd [–s <server>] -m <macaddr> -i <ipaddr> [-f <filename>] [-?] Parameters Param eter Required Description -s <server> No DHCP Server IP Address (default = 127. This then makes the freed IP address available for lease assignment to another client on the subnet. -? No Print help -f <filename> No The name of the CSV file which defines leases to be released. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. This IP address should be associated with a lease for the client identified by the ‘macaddr’ parameter. and send the request to the DHCP server. a1:b2:c3:d4:e5:f6 -i <ipaddr> Yes The IP address to be released by the DHCP server.DhcpReleaseCLI [–s <server>] -m <macaddr> -i <ipaddr> [-f <filename>] [-?] Via command script (Unix) $INCHOME/etc/cli/DhcpRelease. Instead.1.ipcontrol. A DHCP lease is a contract for the use of an IP address between the DHCP server and client for a specific amount of time.sh [–s <server>] -m <macaddr> -i <ipaddr> [-f <filename>] [-?] Via command script (Windows) %INCHOME%/etc/cli/DhcpRelease.101 for the client with MAC address de:ad:be:ef:ca:fe on the DHCP server at IP address 10.10.0.10. releasing an active lease for a client that is still on the network could lead to duplicate IP address situations.1 for MAC=de:ad:be:ef:ca:fe and IP=10.10. making it impossible to detect if the server even received the release message. the results of releasing an active lease are unpredictable. then the client may not be able to obtain network connectivity on the subnet for which the lease was released. In addition.10. Due to the different DHCP client implementations. Using this CLI to simulate client behavior is potentially dangerous.10.506 ()[main] INFO DHCPRelease .sh –s 10.606 ()[main] INFO DHCPRelease . If the client is actively using the IP address when the lease is released. For example.Building DHCP Release packet 16:10:02. Therefore. a corresponding entry for the DHCP release appears in the appropriate syslog output file (/var/log/daemon. the CLI cannot verify that the release was successful.10. If the client maintains the lease offline when the lease is released.10.10.10. These log entries can be found in the CLI logfile ($INCHOME/etc/cli/log/ns_webservice. Com mand Line Interfaces (CLI) 177 . this CLI should only be used when it can be guaranteed by the network administrator that the lease(s) are no longer in use by the client .DhcpRelease $INCHOME/etc/cli/DhcpRelease. Caveats Reliability It is important to note that there is no reply message from the DHCP server to the client in response to the DHCP Release. A lease is a contract between a DHCP server and a DHCP client.10. $INCHOME/etc/cli/DhcpRelease.101 This example issues a release for each lease identified in the dhcprelease. the packet is sent via UDP.101 If successful.Sending DHCP Release to server=10.10. Therefore.csv file.1 –m de:ad:be:ef:ca:fe –i 10.log for Sapphire Appliances) on the DHCP server: Jan 2 16:11:16 sapphire dhcpd: DHCPRELEASE of 10.sh –f dhcprelease.log) when the appropriate logging level is configured: 16:10:02.10.csv Output The output from the CLI indicates the specific parameters used to issue the DHCP Release.101 from de:ad:be:ef:ca:fe (client hostname) via eth0 (found) File Format Col Field Accepted Values Required A Server IP Address The IP Address of the DHCP Server Yes B Client MAC Address The MAC Address of the client Yes Format: a1:b2:c3:d4:e5:f6 C Client IP Address The IP Address to be released Yes Notes This CLI should be used with extreme caution. the client may immediately loose network connectivity. Only authorized network administrators should attempt to run this CLI. 0. CLI must be run remotely. Solaris – not supported. Additionally. to avoid network connectivity issues noted above. inclusive.0. ISC DHCP v4. the DhcpRelease CLI will not function from the localhost. If you are running a Sapphire Appliance or a Linux distribution with a kernel version in this range. Each IPControl platform has different behavior with respect to running the CLI locally. contain a bug that creates a bad UDP checksum for packets sent on the localhost. ephemeral. the appropriate statement is automatically added to the dhcpd.255. the server must be configured with the loopback subnet in the dhcpd.18-2. Windows – no known issues.1 netmask 255.6.26. 178 IPControl CLI and API Guide . Linux kernel versions 2. Select the Extensions tab and insert the above loopback subnet declaration to be appended to the end of the configuration file. Specifically.conf file. subnet 127.255 { } If the server’s configuration does not include this statement.6. Localhost Usage In many cases.0. Once the server has been restarted using the modified dhcpd_start script and is configured with the loopback subnet. After making these changes.conf file when a DHCP Configuration task is performed.255. it is convenient to run the CLI from the same host as the DHCP server and specify a server IP address of 127. the CLI will open a high numbered (1025+).x does not support listening on the loopback address. Router and firewall rules must allow such traffic.DhcpRelease Network Connectivity This CLI must be run from a network host which allows DHCP traffic to the DHCP server. Sapphire/Linux – supported only with ISC DHCP v3. By default. You can verify your kernel version by running uname –a in a console window. modify the DHCP server’s configuration via Topology Network Services Edit DHCP Server. then the DhcpRelease CLI can be run from the localhost of the DHCP server itself.x. push the new configuration to the DHCP server via Management Configuration/Deployment DHCP Configuration – All Files.1. port on the local host and direct UDP packets to port 67 on the specified DHCP server.0. sh [-p] [-v] [-i] [-q] [-b size] [-t table.purge [-p] [-v] [-i] [-q] [-b size] [-t table. Usage Direct $INCHOME/jre/bin/java –cp $CLASSPATH com. suspends user prompting and progress reporting. specify a date ( c) or number of days from today (-d).] -c YYYY-MM-DD | -d days [-?] Parameters Param eter Required Description -p No Preview mode. To configure the date constraint from which all older records will be deleted. -q No Quiet mode.properties found in the product CLASSPATH. writes dry run report to stdout.. -i No Interactive mode. NOTE: a date constraint is required to operate the utility.] -c YYYY-MM-DD | -d days [-?] Via command script (Unix) $INCHOME/etc/purge. -v No Verbose mode.ipcontrol..] -c YYYY-MM-DD | -d days [-?] Via command script (Windows) %INCHOME%/etc/cli/purge.Purge Purge Overview The Purge utility will delete records from the set of IPControl tables listed below that are older than the specified date constraint (-c or –d) in batches of 1000 records...cmd [-p] [-v] [-i] [-q] [-b size] [-t table. prompts user for SQL execution permission. To limit the tables to purge.diamondip... use the –t parameter which is constrained to the following tables: ADDRPOOLHISTORY ALERTLOG AUDITLOG BLOCKHISTORY CONTAINERHISTORY EVENTLOG If the performance of the individual delete statements becomes an issue. Database connection information is automatically derived from the IPControl jdbc..cli.. 179 . writes verbose output to stdout. the batch size can be changed using the –b parameter.. + DELETESQL = DELETE FROM ADDRPOOLHISTORY WHERE LOGDATE < TO_DATE('2013-05-01'. deleted 33 recs.properties [ + + + + JDBC Properties ] jdbc.+ Recs found: 33 2013-05-15 15:54:56 . 17ms 180 IPControl CLI and API Guide . -c <YYYY-MM-DD> Yes. All records older than this date will be deleted.OracleDriver jdbc:oracle:thin:@localhost:1521:ipam incadmin4 ******** [ Job Properties ] + Preview = false + Verbose = false + Interactive = false + Quiet Mode = false -----------------------------------------------2013-05-15 15:54:56 2013-05-15 15:54:56 . $INCHOME/etc/cli/purge.Batch 4 deleted 5 recs 2013-05-15 15:54:56 .+ Purge recs older then: 2013-05-01 2013-05-15 15:54:56 . All older records will be deleted.Purge complete.driverClassName jdbc.username jdbc. 'YYYY-MM-DD') AND ROWNUM <= 5 2013-05-15 15:54:56 . -t <table. if –c not specified.33 ADDRPOOLHISTORY records will be deleted in 7 batches.Purge -b <size> No Overwrites default batch size (1000).Batch 6 deleted 5 recs 2013-05-15 15:54:56 .Batch 2 deleted 5 recs 2013-05-15 15:54:56 .Processing completed.Batch 7 deleted 3 recs 2013-05-15 15:54:56 ..#JOB# .Batch 5 deleted 5 recs 2013-05-15 15:54:56 .#DONE# .jdbc..+ Batch size: 5 2013-05-15 15:54:56 . if –d not specified.password = = = = oracle. 2013-05-15 15:54:56 .Execute purge ADDRPOOLHISTORY by LOGDATE 2013-05-15 15:54:56 .2 (2013) Runtime: Wed May 15 15:54:55 EDT 2013 [ Utility Property File Summary ] + Logging properties file = C:/ bin/IPControl/etc/support/purge_log4j.driver.Copyright BT Diamond IP Version: v0. Number of days from the current date to keep.sh -b 5 -c 2013-05-01 -t addrpoolhistory -----------------------------------------------IPControl DB Purge CLI .url jdbc.Batch 3 deleted 5 recs 2013-05-15 15:54:56 .#JOB# .> No Comma separated list of tables to purge. -? No Print help Usage Example This example will delete all records older then 2013-05-01 in a batch size of 5 for the addrpoolhistory table. -d <days> Yes. Purge date.properties + JDBC properties file = C:/ bin/IPControl/jdbc. 16ms 2013-05-15 15:54:56 – 2013-05-15 15:54:56 ..Batch 1 deleted 5 recs 2013-05-15 15:54:56 . Purge Output Unless quiet mode (-q ) in invoked the utility will write out its operating environment parameters and a running summary of its execution results to stdout. For this reason it’s recommended to first run the purge utility in preview mode (e.g.properties for every run.log.g. Notes This utility should be used with caution as deleted records can not be restored without a database backup.sh -p) to get an idea of the scope of the work that will be done.sh -i) to force a user to confirm each table aggregate delete operation. $INCHOME/etc/cli/purge. A full execution report will also be logged to the location specified in $INCHOME/etc/support/purge_log4j. $INCHOME/etc/cli/purge. By default the log will be found under ${INCX_HOME}/log/purge. 181 . followed by interactive mode (e. IPControl will then validate that this is a valid combination. Tasks.org/axis/java/user-guide. Invoke the API by implementing web service clients. Note that the stubs used in the example are generated by Axis’ wsdl2Java tool. To view the complete WSDL for each of the services.Application Program Interfaces (API) Using the API IPControl provides its API as a set of Web Services. In order to use web services.apache. Updates and Deletes. Exports. The interfaces are grouped into Imports. and that the administrator is authorized to use web services (via the Allow Command Line Interface Access checkbox on the Administrator Policies screen).html 182 IPControl CLI and API Guide . using the client technology of your choice. Gets. using authentication handlers that are invoked before the web service request is called. see: Imports: http://localhost:8080/inc-ws/services/Imports?wsdl Gets: http://localhost:8080/inc-ws/services/Gets?wsdl Tasks: http://localhost:8080/inc-ws/services/TaskInvocation?wsdl Exports: http://localhost:8080/inc-ws/services/Exports?wsdl Updates: http://localhost:8080/inc-ws/services/IncUseNextReservedIPAddress?wsdl Deletes: http://localhost:8080/inc-ws/services/Deletes?wsdl Invoking the web service and authentication IPControl uses HTTP Basic Authentication (BASIC_AUTH). the client must pass the IPControl login name and password. Below is a sample code fragment of a client using Java and Axis to invoke the importDevice operation of the Imports web service. For more information on Axis and wsdl stubs. see http://ws. Each service is explained in detail. in the sections that follow. including the WSDL applicable to each interface. WriteLine(otherErr. "". stub. wsdevice.NET to invoke the findNetService operation of the Exports web service: Public Dim Dim Dim Dim Shared Sub findNetService() myCred As New NetworkCredential("incadmin".Length .Url = "http://localhost:8081/inc-ws/services/Exports" Try myNS = myWS. // Setup for authorization handlers ImportsSoapBindingStub stub = (ImportsSoapBindingStub)locator. "".Credentials = myCred myWS. "incadmin") myWS As New localhost. "") For i = 0 To myNS. myNS(i).findNetService("".setPassword(“incadmin”).setIpAddress(blockName).importDevice(wsdevice).name.setResourceRecordFlag(resourceRecordFlag).WSNetService() i As Integer myWS. // Use Axis-generated class to call the web service String address = stub.1 Console. // Set up input parameter structure WSDevice wsdevice = new WSDevice().ExportsService() myNS As localhost.getImports(url). stub. "".setDeviceType(deviceType). "". wsdevice. myNS(i).setUsername(“incadmin”). Below is an example of a client using .// Axis-generated class ImportsServiceLocator locator = new ImportsServiceLocator().ToString) End Try End Sub Application Program Interfaces (API) 183 . "". wsdevice.WriteLine("Name={0} IP={1} Type={2}".ipAddress. wsdevice. myNS(i).type) Next Catch myErr As SoapException dumpError(myErr) Catch otherErr As Exception Console.setHostname(hostName). // Error handling shown in next section return address. err.println("Exception .println("AxisFault returned:").err.w3.getFirstChild().Error Processing Error Processing When the web service finds an error during processing.getTagName()).getFaultString()). } } Other SOAP toolkits (e. Below is a sample of the XML that will be sent to the client. along with additional information in the detail element..org/soap/envelope/ xmlns:xsd=http://www.org/2001/XMLSchema xmlns:xsi="http://www.getMessage().getFaultCode()).err. System.1. System. it uses the fault codes defined in SOAP 1. } else { ex. to convey the nature of the error.println(" faultdetail node value: " + elements[0].getNodeValue()). System.err.println(" faultstring: "+fault. if (ex instanceof AxisFault) { // Retrieve Axis Fault detail AxisFault fault = (AxisFault) ex. System. or ignore those tags if that level of detail about the exception is not required for the application. Element[] elements =fault.NET and Perl) can parse the XML for the details.println(" faultcode: " + fault.err. System.err. Available Application Program Interface Matrix Object Address Pool Import X Aggregate Block X Block X 184 IPControl CLI and API Guide Modify X Delete X Export X X X X ." + errMsg). System.org/2001/XMLSchema -instance"> <soapenv:Body> <soapenv:Fault> <faultcode>soapenv:Server</faultcode> <faultstring>Unknown root block type: 0</faultstring> <faultactor>http://localhost:8080/nc/services/RootBlockImport</faultactor> <faultDetail> <returnCode>-14</returnCode> </faultDetail> </soapenv:Fault> </soapenv:Body> </soapenv:Envelope> Java clients can catch the error as an Exception and access the message.getFaultDetails().println(" faultdetail tag: " + elements[0]. . Below is a sample code fragment of a client using Java and Axis to retrieve the information in the detail element of the XML: try { Invoke web service } catch (Exception ex) { String errMsg = "Line " + inputLine + ": " +ex. <soapenv:Envelope xmlns:soapenv=http://schemas.printStackTrace().g.w3.xmlsoap. Available Application Program Interface Matrix Object Container Device Import X Modify X Delete X Export X X X X X Device Interface X Device RR X X DHCP Server X X Domain X Domain RR X Galaxy Domain X NetElement X NetElementInterface X Netservice X PrefixPool X RootBlock X Zone X Zone RR X Next Available IP X JoinBlock Site (multiple block allocation) X X X X X X X X X X X X X X X (see ImportZone) X X X X N/A N/A N/A Delete X Export X X X X GlobalRollup X X DiscoverNetElement X X DhcpUtilization X X GetTask X Split Block X Detach Block X Task GlobalNetElementSync GlobalNetServiceSync Import X Modify ImportElementSnapshot ImportServiceSnapshot Application Program Interfaces (API) 185 . Available Application Program Interface Matrix GetTask Status 186 IPControl CLI and API Guide X . 0. <complexType name="WSSite"> <sequence> <element name="container" nillable="true" type="soapenc:string"/> <element maxOccurs="unbounded" name="siteBlockDetails" nillable="true" type="tns2:WSSiteBlockDetails"/> <element name="siteTemplateName" nillable="true" type="soapenc:string"/> </sequence> </complexType> Application Program Interfaces (API) 187 . Parameters WSSite Below is the portion of Imports.1. Each of these services is available as an operation in the Imports web service. “10. for example.0.0/25”. < wsdl:message name="addSiteResponse"> <wsdl:part name="addSiteReturn" type="soapenc:string"/> </wsdl:message> < wsdl:message name="addSiteRequest"> <wsdl:part name="site" type="tns2:WSSite"/> </wsdl:message> Response The string returned in the response contains a comma-separated list of block names added. is described in the next section.wsdl that describes WSSite. The elements are described in the table that follows.0/24. Request The complex type WSSite. the parameter structure passed to addSite.0. 10. which is passed as input from the client to the web service.wsdl that describes the addSite request and response messages. Request and Response Messages Below is the portion of Imports.AddSite Imports Overview This section explains the web services available for importing information to IPControl. You can see t he complete WSDL at: http://localhost:8080/inc-ws/services/Imports?wsdl AddSite Overview The AddSite API enables the web service client to add a site to a container using an existing Site Template. The elements are described in the table that follows. See below for details. included in WSSite described above. no -214 Block details do not match site template details The name of the site template to be used in creating the site. siteBlockDetails A repeating structure of parameters used in creating the blocks from the template. The site block details must be specified in the order matching the sequence of the Site Template Detail records in the IPControl GUI. <complexType name="WSSiteBlockDetails"> <sequence> <element maxOccurs="unbounded" name="addrDetails" nillable="true" type="tns2:WSAllocationTemplateDetails"/> <element name="allocationReason" nillable="true" type="soapenc:string"/> <element name="allocationReasonDescription" nillable="true" type="soapenc:string"/> <element name="interfaceName" nillable="true" type="soapenc:string"/> <element name="swipName" nillable="true" type="soapenc:string"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string"/> </sequence> </complexType> 188 IPControl CLI and API Guide . yes -42 Container required -5 Container name not found Short format example: Dallas Long format example: IPControl/Texas/Dallas Long format eliminates ambiguity in cases where there are duplicate container names.Elem ent Description and accepted values Required Return Code Faultstring container The name of the container in which to create the site. Names can be in either short or long format.wsdl that describes WSSiteBlockDetails. yes -211 Site template name required -212 Site template name not found siteTemplateName -213 -215 Site template type does not match container type (logical/device) type exception applying site template: message WSSiteBlockDetails Below is the portion of Imports. Elem ent Description and accepted values Required addrDetails Define attributes of any address allocations of the allocation template specified by the site allocation template for this block. this field is skipped. Wrap the statement in "quotes" if it contains any commas. yes. if required by template -63 -61 SWIPname is required for this container/blocktype SWIPname is not allowed for this container/blocktype Invalid UDF: udf Missing required UDF: udf Application Program Interfaces (API) 189 . no allocationReasonDescription A description of the reason for the allocation. Each element in the array has the format "name=value" where "name is the UDF tag name. If Allocation Reason is not currently in IPControl. This is a locator field. yes. no interfaceName The target interface name. if required for this container/blocktype allocationReason swipName Return Code Faultstring -22 Invalid allocation reason allocReason -19 No interface found -20 Interface name is required for device containers -66 -70 userDefinedFields Array of user defined fields. See below for syntax. no The name of a preexisting Allocation Reason. for a device container SWIP name yes. This must match the specification in the Allocation Template. The elements are described in the table that follows.WSAllocationTemplateDetails Below is the portion of Imports. no -185 Invalid network service name: name Specify true or false. <complexType name="WSAllocationTemplateDetails"> <sequence> <element name="netserviceName" nillable="true" type="soapenc:string"/> <element name="offsetFromBeginningOfSubnet" type="xsd:boolean"/> <element name="sharename" nillable="true" type="soapenc:string"/> <element name="startingOffset" type="xsd:long"/> </sequence > </complexType> Elem ent Description and accepted values Required Return Code Faultstring netserviceName The name of the network service for this address allocation. no Identify the address allocation within the template. This must match the specification in the Allocation Template. yes -173 Block details do not match site template details offsetFromBeginningOfSubnet sharename Deprecated startingOffset 190 IPControl CLI and API Guide -174 Invalid starting offset: offset for allocation template: template name . yes The name used to link address pools together.wsdl that describes WSAllocationTemplateDetails. included in WSSiteBlockDetails described above. wsdl that describes the detachBlock request and response messages. <complexType name="WSChildBlock"> <sequence> <element name="SWIPname" nillable="true" type="xsd:string" /> <element name="allocationReason" nillable="true" type="xsd:string" /> <element name="allocationReasonDescription" nillable="true" type="xsd:string" /> <element name="allocationTemplate" nillable="true" type="xsd:string" /> <element name="blockAddr" nillable="true" type="x sd:string" /> <element name="blockName" nillable="true" type="xsd:string" /> <element name="blockSize" nillable="true" type="xsd:string" /> <element name="blockStatus" nillable="true" type="xsd:string" /> <element name="blockType" nillable="true" type="xsd:string" /> <element name="container" nillable="true" type="xsd:string" /> <element name="createReverseDomains" nillable="true" type="xsd:string" /> <element name="description" nillable="true" type="xsd:string" /> <element name="domainType" nillable="true" type="xsd:string" /> <element name="interfaceAddress" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="interfaceName" nillable="true" type="xsd:string" /> <element name="ipv6" type="xsd:boolean"/> <element name="primarySubnet" type="xsd:boolean"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_xsd_string" /> <element name="excludeFromDiscovery" nillable="true" type="xsd:string" /> </sequence> </complexType> Application Program Interfaces (API) 191 . Request The complex type WSChildBlock. The elements are described in the table that follows. which is passed as input from the client to the web service. Request and Response Messages Below is the portion of Imports. for example.wsdl that describes WSChildBlock.DetachBlock DetachBlock Overview The DetachBlock API enables the web service client detach blocks from device containers in IPControl.0.128/28. is described in the next section. Parameters WSChildBlock Below is the portion of Imports. 10.0. the parameter structure passed to detachBlock. <wsdl:message name="detachBlockResponse "> <wsdl:part name="detachBlockReturn" type="soapenc:string" /> </wsdl:message> <wsdl:message name="detachBlockRequest"> <wsdl:part name=" name="childBlock" type="tns1:WSChildBlock" /> </wsdl:message> Response The string returned in the response contains the name of the block detached. DetachBlock Elem ent Description and accepted values Required SWIPname Ignored no allocationReason Ignored no allocationReason Description Ignored no allocationTemplate Ignored no blockAddr The address of the block to detach yes. if blockAddr is not specified -36 Block blockName not found blockSize The size of the block in short-notation (e.0 network). Long format eliminates ambiguity in cases where there are duplicate container names. Names can be in either short or long format. Short format example: Dallas.. createReverseDomains Ignored no Description Ignored no domainType Ignored no interfaceAddress Ignored no interfaceName Ignored no ipv6 Ignored no userDefinedFields Ignored no excludeFromDiscovery Ignored no primarySubnet Ignored no 192 IPControl CLI and API Guide . yes. 24 for a 255. Use delete. Long format example: /IPControl/Texas/Dallas.g.255. yes -42 Container required -5 Container container not found -184 Block is only attached to one container. if blockName is not specified Return Code Faultstring -183 Blockname or address space/block size required -26 Invalid IpAddress: blockAddr -36 Block blockAddr not found blockName The name of the block to detach yes.255. if blockAddr is used -15 Invalid block size: blockSize blockStatus Ignored no blockType Ignored no container The name of the container from which to detach block. Request and Response Messages Below is the portion of Imports. which is passed as input from the client to the web service.wsdl that describes WSAddrpool. <complexType name="WSAddrpool"> <sequence> <element name="allowClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="denyClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="dhcpOptionSet" nillable="true" type="soapenc:string"/> <element name="dhcpPolicySet" nillable="true" type="soapenc:string"/> <element name="endAddr" nillable="true" type="soapenc:string"/> <element name="failoverNetService" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soa penc:string"/> <element name="name" nillable="true" type="soapenc:string"/> <element name="primaryNetService" nillable="true" type="soapenc:string"/> <element name="sharename" nillable="true" type="soapenc:string"/> <element name="startAddr" nillable="true" type="soapenc:string"/> <element name="type" nillable="true" type="soapenc:string"/> <element name="prefixLength" nillable="true" type="soapenc:string"/> </sequence> </complexType> Application Program Interfaces (API) 193 . Request The complex type WSAddrpool. The elements are described in the table that follows. is described in the next section. Parameters WSAddrpool Below is the portion of Imports.wsdl that describes the importAddressPool request and response messages. <wsdl:message name="importAddressPoolRequest"> <wsdl:part name="addrpool" type="tns2:WSAddrpool"/> </wsdl:message> <wsdl:message name="importAddressPoolResponse"/> Response There is no data in the response. the parameter structure passed to importAddressPool.Im portAddressPool ImportAddressPool Overview The ImportAddressPool API enables the web service client to import or modify containers in IPControl. “Dynamic NA DHCPv6”. Defaults to “Start Address-End Address” No sharename The name used to link address pools together. No container The name of the container that holds the block in which the pool is defined. This address must be in the same block as the Start Address. when a DHCP server is not defined for the subnet. a new address pool is created. No. Yes for updates. -117 Addrpool ID=<id> not found The IP Address of the first address in the pool. If this is set. -36 Block not found in container primaryNet Service The name of the DHCP server that will serve addresses from this pool Yes. “Reserved”. If this is not set. This is required only if there is overlapping address space in use and the start address is in overlapping space. “Manual DHCP”. “Automatic DHCP”. Yes for IPv4 pools. This address must be in a block with an InUse/Deployed status. “Static”. The container is then used to uniquely determine the block that will contain the address pool. unless startAddr is not unique. Yes -115 Missing Start or End IP Address -36 Block Not Found -97 Block Not Unique -115 Invalid Start Address -115 Missing Start or End IP Address -26 End Address outside of block -26 End address must be after Start Address -115 Invalid End Address -73 Invalid Address Type startAddr endAddr Invalid ID <id> on addrpool object The IP Address of the last address in the pool.Im portAddressPool Elem ent Description and accepted values Required Return Code Faultstring id The internal identifier for this address pool object. In addition. ”Automatic NA DHCPv6”. the address pool with the matching identifier is updated. ”Automatic TA DHCPv6” Yes name Address Pool name. -94 DHCP Server not found Deprecated 194 IPControl CLI and API Guide . ”Dynamic TA DHCPv6”. No for creates. type One of “Dynamic DHCP”. the Start and End addresses must not overlap any other pools. For “Dynamic DHCP” and “Automatic DHCP” type pools: An array of Client Classes that are NOT allowed in this address pools. dhcpPolicySet The name of a Policy Set used with this pool. For “Dynamic DHCP” and “Automatic DHCP” type pools: An array of Client Classes that are allowed in this address pools. Each array element names a different Client Class. Each element of the array names a different Client Class. the DHCP policy set applies only to non-CNR DHCP servers. dhcpOptionSet For IPV4 address pools. For IPV6 address pools. the DHCP policy set applies only to CNR DHCP servers. -258 Missing Prefix length.Im portAddressPool Elem ent Description and accepted values Required Return Code Faultstring failoverNet Service The name of the failover DHCP server that will serve addresses from this pool. No -94 DHCP Server not found -96 Failover not valid without a primary The name of an Option Set used with this pool. To use this field. the DHCP option set applies only to CNR DHCP servers. primaryNetService must also be specified. allowClient Classes denyClientClas ses prefixLength For IPV6 address pools. Application Program Interfaces (API) 195 . This element is ignored for an IPv4 address pool. No -67 DHCP Option Set not found No -68 DHCP Policy Set not found No -116 DHCP Client Class not found No -116 DHCP Client Class not found Yes for IPv6 pools. For IPV4 address pools. CIDR size of an IPv6 pool. the DHCP option set applies only to non-CNR DHCP servers. wsdl that describes WSAggregateBlock. target block. Request and Response Messages Below is the portion of Imports. is described in the next section. which is passed as input from the client to the web service. the service will handle validating and inserting the desired aggregate block. the parameter structure passed to importAggregateBlock. <wsdl:message name="importAggregateBlockRequest"> <wsdl:part name="aggregateBlock" type="tns2:WSAggregateBlock"/> </wsdl:message> <wsdl:message name="importAggregateBlockResponse"> Response There is no data in the response. Request The complex type WSAggregateBlock.wsdl that describes the importAggregateBlock request and response messages. <complexType <sequence> <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element name="WSAggregateBlock"> name="SWIPname" nillable="true" type="soapenc:string"/> name="allocationReason" nillable="true" type="soapenc:string"/> name="allocationReasonDescription" nillable="true" type="soapenc:string"/> name="blockAddr" nillable="true" type ="soapenc:string"/> name="blockName" nillable="true" type="soapenc:string"/> name="blockSize" nillable="true" type="soapenc:int"/> name="blockType" nillable="true" type="soapenc:string"/> name="container" nillable="true" type="soapenc:string"/> name="createReverseDomains" type="xsd:boolean"/> name="description" nillable="true" type="soapenc:string"/> name="domainType" nillable="true" type="soapenc:string"/> name="interfaceAddress" nillable="true" type="soapenc:string"/> name="interfaceName" nillable="true" type="soapenc:string"/> name="parentBlockAddr" nillable="true" type="soapenc:string"/> name="parentBlockContainer" nillable="true" type="soapenc:string"/> name="parentBlockSize" nillable="true" type="soapenc:int"/> name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string"/> 196 IPControl CLI and API Guide . The service will also adjust the parent block assignments of any would-be child blocks. and a container. By specifying a parent block. The elements are described in the table that follows. Parameters WSAggregateBlock Below is the portion of Imports.Im portAggregateBlock ImportAggregateBlock Overview The ImportAggregateBlock API enables the web service client to insert an intermediate level aggregate block between existing blocks in the block hierarchy. Yes. No Interface Name If this block is being added to a device container.g. Yes -42 Missing container name -5 Could not find container: <container> -99 Admin is not authorized to add blocks to this container The start address of the new aggregate block. DEPRECATED. No description A description of the block.Im portAggregateBlock </sequence> </complexType> Elem ent Description and accepted values Required Return Code Faultstring container The name of the container into which to insert the new aggregate block. This field will be ignored. Wrap the statement in “quotes” if it contains any commas. if required by container rules -66 SWIPname is required for this container/blocktype -70 SWIPname is not allowed for this container/blocktype -22 Invalid allocation reason: <reason> -20 Missing interface name -19 No interface found -5 Could not find containerID=<id> Allocation Reason The name of a pre-existing Allocation Reason. Names can be in either short or long format.. Yes -127 Block start and parent block address both required -12 Could not convert <address> to ipAddress blockAddr blockSize The size of the block in shortnotation (e. no.0 network). 24 for a 255. the name of the interface to attach the block to. No SWIPname SWIP name for the block. Yes. Long format eliminates ambiguity in cases where there are duplicate container names. Long format example: IPControl/Texas/Dallas. No Interface Address Application Program Interfaces (API) 197 . if block is being added to device container. Otherwise .255. a block type of Any is assumed. No -13 Invalid block type <type> blockName A name for the block. No Allocation Reason Description A description of the reason for the allocation. Yes -15 Block size invalid: <size> blockType The Block Type for the block If not specified.255. Short format example: Dallas. Defaults to system supplied name of Address space/Block size. Accepted values are true or false.0 network). 24 for a 255. Multiple pairs can be specified by separating each pair with the “|” character. If not specified. where the name is the UDF name and the value is desired value.. 198 IPControl CLI and API Guide Yes Yes . No -2 Exception retrieving domain type: <type> -81 Domain type not found: <type> A series of name=value pairs. Yes -42 Missing container name -5 Could not find container: <container> -99 Admin is not authorized to add blocks to this container -127 Block start and parent block address both required -12 Could not convert <address> to ipAddress -15 Block size invalid: <size> userDefined Fields parentBlock Container parentBlock Addr parentBlock Size The address of the parent block The size of the parent block in short-notation (e. If the UDF type is Checkbox. for UDFs defined as required fields.g. Yes.Im portAggregateBlock Elem ent Description and accepted values Required Return Code Faultstring Create Reverse Domains Whether or not to automatically create reverse DNS domain(s) for this block. -53 SQL Exception retrieving valid UDF list -63 -64 Invalid UDF list or button selection: <value> or Invalid UDF: <name> or There are no UDFs defined for this container and block type Missing required UDF: <name> The name of the container where the parent block resides.255. UDFone=value one |UDFtwo=value two. defaults to false. For example. If not specified.255. the valid values are “on” or “off”. No -82 createReverseDomains must be true or false: value domainType Specify the domain type for the reverse DNS domain(s) to be created when Create Reverse Domains is “true”. defaults to “Default”. 10. for example.Im portChildBlock ImportChildBlock Overview The ImportChildBlock API enables the web service client to import child blocks into IPControl.0. the first parameter structure passed to importChildBlock. taken from parent address space.wsdl that describes WSChildBlock. The elements are described in the table that follows. and then marked with the status that is specified in the request. This space is allocated from the parent. The name of the block allocated is returned to the client application in the response. <complexType <sequence> <element <element <element <element <element <element <element <element <element <element name="WSChildBlock"> name="SWIPname" nillable="true" type="xsd:string" /> name="allocationReason" nillable="true" type="xsd:string" /> name="allocationReasonDescription" nillable="true" type="xsd:string" /> name="allocationTemplate" nillable="true" type="xsd:string" /> name="blockAddr" nillable="true" type="xsd:string" /> name="blockName" nillable="true" type="xsd:string" /> name="blockSize" nillable="true" type="xsd:string" /> name="blockStatus" nillable="true" type="xsd:string" /> name="blockType" nillable="true" type="xsd:string" /> name="container" nillable="true" type="xsd:string" /> Application Program Interfaces (API) 199 .wsdl that describes the importChildBlock request and response messages. This API is used to define sub-allocations of address space. which are passed as input from the client to the web service.128/28. This API can also be used to attach existing blocks to another container by specifying an existing blockAddr. <wsdl:message name="importChildBlockResponse"> <wsdl:part name="importChildBlockReturn" type="soapenc:string" /> </wsdl:message> <wsdl:message name="importChildBlockRequest"> <wsdl:part name="inpChildBlock" type="tns1:WSChildBlock" /> <wsdl:part name="inpBlockPolicy" type="tns1:WSSubnetPolicy" /> </wsdl:message> Response The string returned in the response contains the name of the block allocated. are described in the next section. Parameters WSChildBlock Below is the portion of Imports. Request and Response Messages Below is the portion of Imports.0. Request The complex types WSChildBlock and WSSubnetPolicy. space will be auto-allocated. for containers with rules requiring it -66 SWIP name required for this block -70 SWIP name not allowed for this block -22 Invalid reason code allocationReason The name of a pre-existing Allocation Reason. no blockSize The size of the block in shortnotation (e. If no address block is specified. the block will be attached to the specified container. no allocationTemplate If this block is being added to a device container with blockStatus=Deployed.. no blockName A name for the block. Defaults to system supplied name of Address space/Block size. the name of the allocation template to use to create address pools from the newly created block.g. Reserved. no blockAddr The address block to allocate. no allocationReason Description A description of the reason for the allocation.255. If the address is specified and already exists. no -13 Invalid block type: blockType . Accepted values are: Deployed.0 network). If Allocation Reason is not currently in IPControl. blockStatus blockType 200 IPControl CLI and API Guide No validation required -65 Invalid allocation template: template -69 Allocation template offsets invalid for this block -71 Address pool creation failed.Im portChildBlock <element name="createReverseDomains" nillable="true" type="xsd:s tring" /> <element name="description" nillable="true" type="xsd:string" /> <element name="domainType" nillable="true" type="xsd:string" /> <element name="interfaceAddress" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="interfaceName" nillable="true" type="xsd:string" /> <element name="ipv6" type="xsd:boolean"/> <element name="primarySubnet" type="xsd:boolean"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_xsd_string" /> <element name="excludeFromDiscovery" nillable="true" type="xsd:string" /> </sequence> </complexType> Elem ent Description and accepted values Required Return Code Faultstring SWIPname SWIP name for this block yes.255. Aggregate. 24 for a 255. a block type of Any is assumed. -12 Invalid block address: blockAddr yes -15 Invalid block size: blockSize The current status of the block. yes -17 Invalid block status: blockStatus The Block Type for the block If not specified. this field is skipped. FullyAssigned. no -18 Invalid interface address: interfaceAddress -21 Invalid interface offset: interfaceAddress -20 -19 Missing interface name -24 No interface name specified. createReverseDomains Whether or not to automatically create reverse DNS domain(s) for this block.xxx.Im portChildBlock Elem ent Description and accepted values Required Return Code Faultstring container The name of the container that will hold the block. interfaceName If this block is being added to a device container. defaults to “Default”. Accepted values are true or false. No validation required This can also be the string “from-start” or “from-end” if you are attaching a block to a device container and wish IPControl to determine the first available address from the start or the end of the block. for device containers only Invalid interface name: interfaceName Application Program Interfaces (API) 201 . Short format example: Dallas.e. Use “\n” to separate lines. for the interface IP address(es).xxx. Long format example: /IPControl/Texas/Dallas. If an IP address is specified. If not specified. defaults to false. Names can be in either short or long format.xxx. yes -5 Container not found: containerName -6 Invalid container name: containerName -7 Container name ambiguous: containerName -1 -8 Database error -82 createReverseDomains must be true or false: value Could not attach block to this container. or offsets from the beginning.xxx. An offset of 1 is assumed if none is specified.2). an offset of 2 in a /24 block will create an interface xxx. no -81 Domain type not found: domainType interfaceAddress The specific addresses. could not attach to device container. If not specified. If an integer is specified. Long format eliminates ambiguity in cases where there are duplicate container names. no domainType Specify the domain type for the reverse DNS domain(s) to be created when Create Reverse Domains is “true”. no Description A description of the block. it should be in the form xxx. it will be interpreted as an offset from the beginning of the block (i. yes.xxx. the name of the interface to attach the block to. Accepted values are true or false. <complexType name="WSSubnetPolicy"> <sequence> <element name="DHCPOptionsSet" nillable="true" type="soapenc:string"/> <element name="DHCPPolicySet" nillable="true" type="soapenc:string"/> <element name="DNSServers" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="defaultGateway" nillable="true" type="soapenc:string"/> <element name="failoverDHCPServer" nillable="true" type="soapenc:string"/> <element name="forwardDomainTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="forwardDomains" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="networkLinks" nillable="true" type="soapenc:string"/> <element name="primaryDHCPServer" nillable="true" type="soapenc:string"/> <element name="primaryWINSServer" nillable="true" type="soapenc:string"/> <element name="reverseDomainTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="reverseDomains" nillable="true" type="impl:ArrayOf_soapenc_string"/> </sequence> </complexType> Elem ent Description and accepted values Required Return Code Faultstring DHCPOptionsS et The name of a previously defined DHCP Options set. If not specified. If not specified. No primarySubnet Flag indicating if this subnet is primary. the second parameter structure passed to importChildBlock. No -17 importBlock set primary subnet failed: flag supported only for In-Use/Deployed blocks A string array containing one or more name=value pairs. Accepted values are true or false. defaults to false. for UDFs defined as required fields -63 Invalid UDF: udf -64 Missing required UDF: udf Whether or not to exclude this subnet from Host Discovery tasks.Im portChildBlock Elem ent Description and accepted values Required Return Code Faultstring ipv6 True if this is an IPV6 block. userDefinedFields excludeFromDiscovery value -13 Invalid Block Type: flag supported for Deployed blocks (Subnets) WSSubnetPolicy Below is the portion of Imports. where the name is the UDF name and the value is the desired value.wsdl that describes WSSubnetPolicy. If not specified. no -67 DHCP Option set set not found 202 IPControl CLI and API Guide . State=PA. The elements are described in the table that follows. yes. for example. no -82 excludeFromDiscovery must be true or false: Valid only for Deployed blocks in device containers. defaults to false. defaults to false. Application Program Interfaces (API) 203 . Accepted value is an IP address. no -26 Invalid IP Address: ipaddress reverseDomains The reverse domain names that will available to the user when adding an IP address to the system. Only required for non-default domain types. no -95 Invalid reverse DNS Domain domain reverseDomain Types The domain types corresponding to the domains listed in reverseDomains. no -26 Invalid IP Address: ipaddress failover DHCPServer The name of the DHCP server that will act as failover for this subnet. The administrator does not have rights to add any blocks OR the administrator does not have rights to add blocks to the specified container. no -81 Domain type not found: domainType networkLinks Reserved no primaryDHCP Server The name of the DHCP server that will act as primary for this subnet. no -94 DHCP Server server not found primaryWINS Server The IP address of the Microsoft WINS server for clients in this subnet. no -81 Domain type not found: domainType Other returnCodes and faultstrings Return Code Faultstring -2 Allocation failed -3 Invalid arguments missing xxx parameter -8 Exception attaching block: msg -9 Subnet policy record creation failed -23 Candidate block not found -53 SQL Exception -96 Failover DHCP specified without primary -96 Failover must be different than Primary -99 Access Denied. no -68 DHCP Policy set set not found DNSServers The name of previously defined DNS servers to be sent as an IP address to the client. Only required for non-default domain types. The first forward domain in the list will be used when there is a domain name DHCP option. no -94 DHCP Server server not found Forward Domains The forward domain names that will available to the user when adding an IP address to the system. no -95 Invalid forward DNS Domain domain forwardDomain Types The domain types corresponding to the domains listed in forwardDomains. This cannot be the same as the primary DHCP server.Im portChildBlock Elem ent Description and accepted values Required Return Code Faultstring DHCPPolicySet The name of a previously defined DHCP policy set. no -93 DNS Server server not found defaultGateway The default gateway that DHCP clients on this subnet will use. The elements are described in the table that follows. Parameters WSContainer Below is the portion of Imports. It can also be used to modify existing containers Request and Response Messages Below is the portion of Imports. is described in the next section.Im portContainer ImportContainer Overview The ImportContainer API enables the web service client to import containers into IPControl.wsdl that describes WSContainer. These can be logical containers or device containers. the parameter structure passed to importContainer. Request The complex type WSContainer.wsdl that describes the importContainer request and response messages. <complexType name="WSContainer"> <sequence> <element name="allowedAllocFromParentBlocktypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="allowedBlockTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="allowedDeviceTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="allowedRootBlockTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="blockTypeInfoTemplates" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="containerName" nillable="true" type="soapenc:string"/> <element name="containerType" nillable="true" type="soapenc:string"/> <element name="description" nillable="true" type="soapenc:string"/> <element name="deviceInfoTemplates" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="ignoreBlocktypeInUse" type="xsd:boolean"/> <element name="informationTemplate" nillable="true" type="soapenc:string"/> 204 IPControl CLI and API Guide . <wsdl:message name="importContainerResponse" /> <wsdl:message name="importContainerRequest"> <wsdl:part name="inpContainer" type="tns1:WSContainer" /> </wsdl:message> Response There is no data in the response. which is passed as input from the client to the web service. no -3 Error occurred while updating device info templates for container -78 Invalid Information Template: templateName Application Program Interfaces (API) 205 . no -13 Invalid blocktype rule 1: blocktype allowedDevice Types A string array containing a listing of the device types enabled for Rule 5: “Container may contain devices of type”. To specify that no device types should be allowed.Im portContainer <element name="maintainHistoryRecs" type="xsd:boolean"/> <element name="parentName" nillable="true" type="soapenc:string"/> <element name="replaceDHCPServer" nillable="true" type="soapenc:string"/> <element name="replaceDHCPServerV6" nillable="true" type="soapenc:string"/> <element name="requireSWIPNameBlockTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string"/> </sequence> </complexType> Elem ent Description and accepted values Required Return Code Faultstring allowedAllocFrom ParentBlocktypes A string array containing a listing of the block types enabled for Rule 3: “Allow space allocation from Parent container for block type”. use ALL as the first element in the array. If a blocktype does not have a template associated with it. The order must match the blocktypes listed in the allowedBlockTypes parameter. ALL is the default. no -13 Invalid blocktype rule 2: blocktype blockTypeInfo Templates A string array containing the list of information templates to be associated with each of the blocks allocated to this container according to their blocktype. To specify that all device types should be allowed. and the length of this array is the same as that parameter. no -58 Invalid device type: devicetype allowedRootBlock Types A string array containing a listing of the block types enabled for Rule 2: “Allow Root Blocks to be added to this container of block type”. no -13 Invalid blocktype rule 3: blocktype allowedBlock Types A string array containing a listing of the block types enabled for Rule 1: “Container may contain blocks of type”. set that array element to null or blank. use NONE. no -43 Blocktype in use by container: container The name of the information template to be associated with this container. yes description A brief description of the container. as provided by the getContainerByName call. no -1 DB error retrieving information template -78 Invalid Information Template: templateName 206 IPControl CLI and API Guide . ignoreBlocktypeIn Use Information Template -143 the name provided is ambiguous -158 the new parent has a container with the same name -3 Invalid arguments: container name. parent container name. no deviceInfo Templates A string array containing the list of information templates to be associated with each of the devices allocated to this container according to their device type. If a device type does not have a template associated with it. this container name must match exactly the name of a network element already in the database or the request will be rejected. set that array element to null or blank. the container is updated instead of added. no id The internal ID of this container. yes -3 Invalid arguments: container name. indicated by the list in the allowedBlockTypes field. parent container name. or container type is null -4 Duplicate container name: containerName -9 Invalid device container: containerName -2 Exception finding network element: exception message Invalid argument If you are creating a device container. -132 containerType Either logical or device. or container type is null -8 Invalid container type: type No validation required -3 Error occurred while updating blocktype info templates for container -78 Invalid Information Template: templateName Yes. The order must match the device types listed in the allowedDeviceTypes parameter. and the length of this array is the same as that parameter. If this is set. for modify only -5 Could not find container for modify: id Set this to “true” when disallowing a block type in use by the container.Im portContainer Elem ent Description and accepted values Required Return Code Faultstring containerName The name of the container. Use “\n” to separate lines. specify the name of a DHCP server which is “valid” for the target container. no no Application Program Interfaces (API) 207 . A string array containing a listing of the block types enabled for Rule 4: “Require SWIP Names on blocks of type”. but will update any dynamic V6 objects and must be a V6 capable DHCP server. In order to update these objects’ associated DHCP servers as part of the container move operation. Address Pool. no parentName The name of the parent container for this container. Accepted values are true or false.Im portContainer Elem ent Description and accepted values Required Return Code maintainHistory Recs Specify whether or not Container History and Block History records will be kept for all appropriate block types. Short format example: Dallas. If not specified. yes replaceDHCPServ er This attribute is used only when utilizing the IPControl feature of attaching DHCP servers to Containers. defaults to false. Long format eliminates ambiguity in cases where there are duplicate container names. and when the modify operation involves moving a container. replaceDHCPServ erV6 requireSWIPName BlockTypes This is similar to the above “replaceDHCPServer” field. Subnet. parent container name. and IP Address objects that are moved as a result of the container move may become “invalid” with respect to the DHCP servers attached to the target container or target container’s nearest anscestor. Long format example: IPControl/Texas/Dallas. The history records are created each time the Global Utilization Rollup task is run. Names can be in either short or long format. In this situation. no Faultstring -3 Invalid arguments: container name. or container type is null -10 Parent container not found: containerName -11 -1 Parent container name is ambiguous: containerName Database error -132 Invalid argument -143 the name provided is ambiguous -94 DHCP Server not valid for this container or the user does not have write access -13 The DHCP server was not found -94 DHCP Server not valid for this container or the user does not have write access -13 The DHCP server was not found -13 Invalid blocktype rule 4: blocktype This field will update any dynamic V4 objects and must be a V4 capable DHCP server. Move failed. Specify as a string array containing one or more name=value pairs. for example.Im portContainer Elem ent Description and accepted values Required Return Code userDefinedFields The user defined fields associated with this container. for UDFs defined as required fields Faultstring -63 Invalid UDF: udf -64 Missing required UDF: udf Other returnCodes and faultstrings Return Code Faultstring -1 various unexpected DB errors -2 Allocation failed -3 Invalid arguments missing xxx parameter -41 Container move failed. ) -99 access denied 208 IPControl CLI and API Guide . (Root container not moveable. yes. as listed in the container information template specified in parameter informationTemplate. where the name is the UDF name and the value is the desired value. State=PA. the new parent is a descendant of the container. the parameter structure passed to importDevice.wsdl that describes WSDevice. Request The complex type WSDevice. Parameters WSDevice Below is the portion of Imports. The elements are described in the table that follows.wsdl that describes the importDevice request and response messages. which is passed as input from the client to the web service. <complexType name="WSDevice"> <sequence> <element name="MACAddress" nillable="true" type="soapenc:string"/> <element name="addressType" nillable="true" type="soapenc:string"/> <element name="aliases" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="description" nillable="true" type="soapenc:string"/> <element name="deviceType" nillable="true" type="soapenc:string"/> <element name="domainName" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="duid" nillable="true" type="soapenc:string"/> <element name="dupWarning" nillable="true" type="soapenc:string"/> <element name="hostname" nillable="true" type="soapenc:string"/> <element name="hwType" nillable="true" type="soapenc:string"/> <element name="ipAddress" nillable="true" type="soapenc:string"/> <element name="resourceRecordFlag" nillable="true" type="soapenc:string"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element maxOccurs="unbounded" name="interfaces" nillable="true" type="tns2:WSInterface"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="excludeFromDiscovery" nillabl e="true" type="soapenc:string"/ </sequence> </complexType> <complexType <sequence> <element <element <element name="WSInterface"> name="addressType" nillable="true" type="impl:ArrayOf_soapenc_string"/> name="container" nillable="true" type="impl:ArrayOf_soapenc_string"/> name="excludeFromDiscovery" nillable="true" type="soapenc:string"/> Application Program Interfaces (API) 209 . is described in the next section. Request and Response Messages Below is the portion of Imports. <wsdl:message name="importDeviceResponse" /> <wsdl:message name="importDeviceRequest"> <wsdl:part name="inpDevice" type="tns2:WSDevice" /> </wsdl:message> Response There is no data in the response.Im portDevice ImportDevice Overview The ImportDevice API enables the web service client to import devices into IPControl. When fully qualified. everything that is after the first qualifier is interpreted as a domain name. To use this element. However. When not fully qualified. For DHCP V6: Dynamic NA DHCPv6. The alias may be fully qualified (contains a trailing dot). or not. Yes. the CNAME record will be created in the same domain as the device. Dynamic DHCP. Manual DHCP and Reserved. When you specify an alias. Dynamic TA DHCPv6 and Automatic TA DHCPv6. Accepted values are: Static. there must be a DHCP server defined in the subnet policies for this IP Address. you must also specify resourceRecordFlag as true. 210 IPControl CLI and API Guide No Cannot change the ipaddress of an interface Cannot change the address type to/from 'Interface' . but they can be modified using overwrite. -77 MAC Address must be specified when using Hardware Type or Hardware address must be specified for address type Manual DHCP addressType The address type of this device. Aliases A string array containing the alias or list of aliases for this hostname. a CNAME record is created. Note that if Dynamic. Yes -73 Invalid address type: type Invalid Address Type for IPv4| IPv6: type -260 -261 Devices of type Interface may not be imported. Automatic DHCP. the addressType and ipAddress cannot be updated. Use ImportChildBlock to modify or delete Interface IP addresses. Automatic NA DHCPv6.Im portDevice <element name="hwType" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="ipAddress" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="macAddress" nillable="true" type="soapenc:string"/> <element name="name" nillable="true" type="soapenc:string"/> <element name="sequence" nillable="true" type="soapenc:int"/> <element name="virtual" nillable="true" type="impl:ArrayOf_soapenc_boolean"/> </sequence> </complexType> Elem ent Accepted Values Required Return Code Faultstring MACAddress The hardware MAC address of the device. Automatic or Manual DHCP is specified. if hwtype is specified or if address type is Manual DHCP. Manual NA DHCPv6. -58 Device type not found: type -75 Device type required when using naming policy Yes. -2 Could not find container: container -6 Invalid container name -7 Ambiguous container name -5 Container not found -1 Database error description A description of the device. the “Default” domain type will be used. if resource Record Flag is “true” and the block policy has no forward domains. If not specified. for Address Type “Manual NA DHCPV6” . if overlappin g space is in use and the block name is ambiguous . Accepted values are true or false. -47. if hostname specifies use of naming policy. defaults to false. No -80 Duplicate hostname for hostname hostname Valid host name or APPLYNAMINGPOLICY. If not specified. DHCP Unique Identifier No -59 Domain type not found: view Yes.Im portDevice Elem ent Accepted Values Required Return Code Faultstring container The name of the container that contains the device. Use “\n” to separate lines. the warning will be ignored and the device added with the duplicate hostname when this field is true. Yes. Yes domainName domainType duid Domain name already defined to IPControl Application Program Interfaces (API) 211 . No deviceType The name of a device type configured in IPControl. -60 Domain not found: domain -71 Domain required when adding resource records Domain type already defined to IPControl. -259 DUID required for Manual NA DHCPV6 dupWarning If the administrator policy of the user indicates “Warn” for the “Allow Duplicate Hostnames Checking” option. Yes. the valid values are on and off. If MACAddress is specified. State=PA. If not specified as true. Invalid IP Address: address Invalid direction IPV6 not supported Block out of space -53 store UDFs failed: SQL exception message -63 Invalid UDF -64 Missing required UDF: udf -18 Interface required when modifying a device -19 IP Address missing or invalid -20 Interface name missing. .name: Interface Name (Required) . for mulithomed devices interfaces . Yes. When hwtype is specified. No -72 Invalid Hardware type: type ipAddress The IP Addresses of the Device. for example.container: reserved . Yes -26 -226 To modify devices with multiple IP Addresses on a single interface use the interfaces element. Their accepted values are the same as in the WSDevice structure. where the name is the UDF name and the value is the desired value. not used . Each element in the array corresponds to one interface for a multi-homed device or to the only interface for a single-homed device. -260 Cannot change the ipaddress of an interface -261 Cannot change the address type to/from 'Interface' .virtual: reserved 212 IPControl CLI and API Guide Yes. unless otherwise noted: Yes. No userDefinedFields A string array containing one or more name=value pairs. MACAddress must also be specified.addressType . defaults to false. use the interfaces element.macAddress .hwType .ipAddress . for all modify requests. If the UDF type is Checkbox.Im portDevice Elem ent Accepted Values Required Return Code Faultstring hwType Specify Ethernet or Token Ring. this will default to Ethernet.excludeFromDiscovery . -227 To indicate that IPControl should use the next available address in an IPV4 block.0/from-start -228 resourceRecordFlag Whether or not to add resource records for this device. Required for modify requests.30. The fields in the WSInterface structure are described below. for example: 10. To create multi-homed devices. specify the block address. An array of WSInterface structures. for UDFs defined as required fields.id: The internal ID provided by a GetDeviceBy call.0. followed by “/from-start” or “/fromend”.sequence: Provided by GetDeviceBy call. the flag must be specified for each IP/Interface via the WSInterface structure. If this is set. Accepted values are true or false. Other returnCodes and faultstrings Return Code Faultstring -2 Import device failed (allocation failure) -36 More than one block for address: address Specify Container -62 Subnet not found for: ip address -47 System error -79 CNAME record could not be created Application Program Interfaces (API) 213 . the device is updated instead of added. defaults to false. for modify excludeFrom Discovery Flag indicating if this device should be included in Host Discovery tasks. If not specified. No Return Code Faultstring For multihomed devices.Im portDevice Elem ent Accepted Values Required id The internal ID of this device. as provided by a GetDeviceBy call. Yes. the parameter structure passed to importDeviceResourceRecord. <complexType name="WSDeviceResourceRecord"> <sequence> <element name="TTL" nillable="true" type="soapenc:string"/> <element name="comment" nillable="true" type="soapenc:string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="data" nillable="true" type="soapenc:string"/> <element name="domain" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="hostname" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="ipAddress" nillable="true" type="soapenc:string"/> <element name="owner" nillable="true" type="soapenc:string"/> <element name="resourceRecClass" nillable="true" type="soapenc:string"/> <element name="resourceRecType" nillable="true" type="soapenc:string"/> </sequence> </complexType> 214 IPControl CLI and API Guide . which is passed as input from the client to the web service.wsdl that describes WSDeviceResourceRec.Im portDeviceResourceRecord ImportDeviceResourceRecord Overview The ImportDeviceResourceRecord API enables the web service client to import DNS resource records for a device into IPControl. is described in the next section. Parameters WSDeviceResourceRec Below is the portion of Imports.wsdl that describes the importDeviceResourceRecord request and response messages. The elements are described in the table that follows. Request and Response Messages Below is the portion of Imports. Request The complex type WSDeviceResourceRec. <wsdl:message name=" importDeviceResourceRecordResponse" /> <wsdl:message name="importDeviceResourceRecordRequest"> < <wsdl:part name="inpRR" type="tns2:WSDeviceResourceRec"/> </wsdl:message> Response There is no data in the response. -121 Hostname not unique: hostname -120 No device with hostname: Yes. The container is then used to uniquely determine the device. -28 IP Address not unique: ipAddress -120 No device with ipAddress Yes -89 Owner not specified -106 Invalid character in owner -92 Invalid Type -91 Data Required resourceRecClass The Class of the Resource Record. No domainType Domain type already defined to IPControl. Return Code Faultstring No -108 Domain not found: domainType/domain Yes. the “Default” domain type will be used. Yes comment Comment text associated with the resource record. This is required only if there is overlapping address space in use and the ip address is in overlapping space. unless Host Name is specified. No data The data portion of the resource record. unless IP Address is specified. Yes TTL The Time To Live for the record. -108 Domain not found: domainType/domain -135 Domain required N/A Not authorized Yes.Im portDeviceResourceRecord Elem ent Accepted Values Required container The name of the container that holds the device. No Application Program Interfaces (API) 215 . hostname ipAddress owner The device host name. domain Domain name where resource records are to be added. The owner field of the resource record. The IP Address of the Device. The format is dependent on the type specified above. Defaults to “IN”. No resourceRecord Type The Type of the resource Record. If not specified. Request The complex type WSDhcpServer.Im portDhcpServer ImportDhcpServer Overview The ImportDhcpServer API enables the web service client to create or DHCP servers in IPControl. <complexType <sequence> <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element name="WSDhcpServer"> name="agent" nillable="true" type="soapenc:string"/> name="beginExtension" nillable="true" type="soapenc:string"/> name="cliArgs" nillable="true" type="soapenc:string"/> name="cliCommand" nillable="true" type="soapenc:string"/> name="cliPassword" nillable="true" type="soapenc:string"/> name="cliUserName" nillable="true" type="soapenc:string"/> name="clientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> name="collectBackupSubnets" type="xsd:boolean"/> name="collectionPassword" nillable="true" type="soapenc:string"/> name="collectionPort" nillable="true" type="soapenc:int"/> name="collectionType" nillable="true" type="soapenc:string"/> name="collectionUser" nillable="true" type="soapenc:string"/> name="configPath" nillable="true" type="soapenc:string"/> name="ddns" type="xsd:boolean"/> name="defaultThreshold" nillable="true" type="soapenc:int"/> name="endExtension" nillable="true" type="soapenc:string"/> name="failoverIpAddress" nillable="true" type="soapenc:string"/> name="failoverPeers" nillable="true" type="impl:ArrayOf_soapenc_string"/> name="failoverPort" nillable="true" type="soapenc:int"/> name="globalSync" type="xsd:boolean"/> name="id" nillable="true" type="soapenc:int"/> name="ipAddress" nillable="true" type="soapenc:string"/> name="leasePath" nillable="true" type="soapenc:string"/> name="name" nillable="true" type="soapenc:string"/> 216 IPControl CLI and API Guide . which is passed as input from the client to the web service. Parameters WSDhcpServer Below is the portion of Imports. The elements are described in the table that follows.wsdl that describes WSDhcpServer. the parameter structure passed to importDhcpServer. Request and Response Messages Below is the portion of Imports. is described in the next section. <wsdl:message name="importDhcpServerResponse" /> <wsdl:message name="importDhcpServerRequest"> <wsdl:part name="dhcpServer" type="tns2:WSDhcpServer" /> </wsdl:message> Response There is no data in the response.wsdl that describes the importNetService request and response messages. No -116 Invalid Client Class: class collectBackup Subnets Set to TRUE if the collection should also process backup subnets from the server. Yes -29 Invalid agent: agent beginExtension The text to be inserted at the start of the configuration file. Defaults to FALSE. No Application Program Interfaces (API) 217 . No collectionPassword The password used by the collection method (scp or ftp) to log in to the remote server. if the server is a CNR DHCP agent. No cliCommand Command to collect DHCP statistics. Accepted values are scp or ftp. No -32 Invalid collection port: port collectionType The method by which the IPControl Agent will collect data from the Network Service. If no value is specified. Yes ddns Set to TRUE to enable DDNS updates from this DHCP Server. Used in conjunction with the ‘User name for collection’. Yes configPath The path to the configuration file of the DHCP server. this will default to 22 if the collection method is scp. which is hexadecimal 0x0D followed by 0x0A. No cliPassword Password used by the cliCommand to access the DHCP Server No cliUserName User Name used by the cliCommand to access the DHCP Server No clientClasses This is an array of DHCP client class names to be used by the DHCP Server. No cliArgs Arguments for the command executed to collect statistics. Separate lines with the sequence “\r\n”. and 21 if the collection method is ftp. Yes collectionPort The port number the collection method (scp or ftp) is listening on. Yes -31 Invalid collection type: type collectionUser The username used by the collection method (scp or ftp) to log in to the remote server. this value should contain the cluster name.Im portDhcpServer <element name="optionSet" nillable="true" type="soapenc:string"/> <element name="policySet" nillable="true" type="soapenc:string"/> <element name="primaryPeers" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="product" nillable="true" type="soapenc:string"/> <element name="startScript" nillable="true" type="soapenc:string"/> <element name="stopScript" nillable="true" type="soapenc:string"/> <element name="v4V6Both" nillable="true" type="soapenc:string"/> </sequence> </complexType> Elem ent Accepted Values Required Return Code Faultstring Agent The name of the IPControl Agent that is responsible for contacting this server. Defaults to false. In particular. No stopScript The full path of the script that stops the server. No -67 Option Set name not found policySet No -68 Policy Set name not found primaryPeers The name of a DHCP policy set defined in the system to be used by this server. Yes -123 Unknown DHCP Product: name startScript The full path of the script that starts the server. No ipAddress The IP address or fully-qualified domain name (FQDN) of the Network Service. Accepted values are True or False (case insensitive). or a fully-qualified host name. Provide warnings when usage of a pool assigned to this service is exceeded. respectively. If no value is specified. This can be any combination of letters and numbers. failoverIpAddress IP Address used by this DHCP Server for failover communications. If this is set.Im portDhcpServer Elem ent Accepted Values Required Return Code Faultstring defaultThreshold Default scope utilization warning threshold. which is hexadecimal 0x0D and 0x0A. No failoverPort Port used by this DHCP Server for failover communications. This must be a valid IPv4 or IPv6 IP address. the server is updated instead of added. No -57 Invalid alert threshold: value endExtension The text to be appended to the configuration file. No globalSync Whether or not to include this server in the Global Sync process. Separate lines with “\r\n”. this will default to 90. No 218 IPControl CLI and API Guide . Not used product The type of DHCP server being defined. as provided by the getDhcpServer call. Yes -26 Invalid IP address: address -112 Duplicate IP Address name The name of the Network Service. Yes -112 Duplicate name optionSet The name of a DHCP option set defined in the system to be used by this server. No id The internal ID of this server. Additional information will appear in the web service log.Im portDhcpServer Elem ent Accepted Values Required Return Code Faultstring v4V6Both ‘v4’.Vali d values are 'V4'. Application Program Interfaces (API) 219 . ‘v6’ or ‘both’ Yes -191 Invalid value v4V6Both specified for V4V6Both. 'V6' or 'Both' Or Product product does not support IP version ‘v4V6Both’ Other returnCodes and faultstrings Return Code Faultstring -1 Unable to obtain session or Rollback failed. Request and Response Messages Below is the portion of Imports. The elements are described in the table that follows. <wsdl:message name="importDomainResponse" /> <wsdl:message name="importDomainRequest"> <wsdl:part name="inpDomain" type="tns1:WSDomain" /> </wsdl:message> Response There is no data in the response. the parameter structure passed to importDomain.wsdl that describes the importDomain request and response messages. Parameters WSDomain Below is the portion of Imports. <complexType name="WSDomain"> <sequence> <element name="contact" nillable="true" type="soapenc:string"/> <element name="defaultTTL" nillable="true" type="soapenc:string"/> <element name="delegated" type="xsd:boolean"/> <element name="derivative" nillable="true" type="soapenc:string"/> <element name="domainName" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="expire" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="infoTemplate" nillable="true" type="soapenc:string"/> <element name="managed" type="xsd:boolean"/> <element name="negativeCacheTTL" nillable="true" type="soap enc:string"/> <element name="refresh" nillable="true" type="soapenc:string"/> <element name="retry" nillable="true" type="soapenc:string"/> <element name="reverse" type="xsd:boolean"/> <element name="serialNumber" nillable="true" type="soapenc:long"/> <element name="templateDomain" nillable="true" type="soapenc:string"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string"/> </sequence> </complexType> 220 IPControl CLI and API Guide . is described in the next section.wsdl that describes WSDomain. which is passed as input from the client to the web service.Im portDomain ImportDomain Overview The ImportDomain API enables the web service client to import domains into IPControl. Request The complex type WSDomain. defaults to false.'. no Zone negative cache time to live. Accepted values are true or false. The internal ID of this domain. Zone refresh interval. If not specified.arpa domain. The default is “STANDARD”. Indicates that this domain is fully defined in IPControl. This can be one of “STANDARD”. Indicates that this domain is a reverse inaddr. ignored if Managed is “False”. If not specified. ignored if Managed is “False”. If not specified. Accepted values are true or false. or “ALIAS”. If not specified.com'. defaults to true. If not specified. ignored if Managed is “False”. If not specified. Default time to live. no The name of the information template to be associated with this container. defaults to “3600”. Required Return Code Faultstring no no no no -92 Invalid derivative type: derivativeType yes -95 Invalid domain name -135 Domain name required -157 Domain already exists -81 Domain type not found: domainType -113 Information template not found: infoTemplateName Domain type name already defined to IPControl. for future use. Accepted values are true or false.ins. If not specified. ignored if Managed is “False”.Im portDomain Elem ent contact defaultTTL delegated derivitive domainName domainType expire id infoTemplate managed negativeCacheTTL refresh retry reverse Description and accepted values The contact email address in dotted format. defaults to “86400”. Zone expire time.ins. If not specified a default contact name will be formed by prepending 'dnsadmin' to the domain name as in 'dnsadmin. the “Default” domain type will be used. defaults to “86400”. no no no no no no no Application Program Interfaces (API) 221 . “TEMPLATE”. Zone retry interval. If not specified.com. The name of the domain being created. Specify the role of this domain. would be represented as 'root. defaults to “604800”. For example. Indicates that this domain will be associated directly with a zone file. defaults to “10800”. an email address of 'root@ins. defaults to true.com'. ignored if Managed is “False”. If not specified. Specify as a string array containing one or more name=value pairs. If not specified. State=PA. Other returnCodes and faultstrings Return Code Faultstring -1 various unexpected DB errors -2 Allocation failed -3 Invalid arguments missing xxx parameter -99 access denied 222 IPControl CLI and API Guide Required Return Code Faultstring no yes. The user defined fields associated with this domain. defaults to “1”.Im portDomain Elem ent serialNumber templateDomain userDefinedFields Description and accepted values Zone serial number. for example. as listed in the domain information template specified in parameter infoTemplate. where the name is the UDF field name/tag and the value is the desired value. for UDFs defined as required fields -61 -63 -64 Template domain not found: templateDomainName Template domain name required Information Template UDF not found: udf Invalid UDF: udf Missing required UDF: udf . ignored if Managed is “False”. if -60 Derivative is “ALIAS” -135 yes. Name of template domain. The elements are described in the table that follows. the parameter structure passed to importDomainResourceRecord. <wsdl:message name=" importDomainResourceRecordResponse" /> <wsdl:message name="importDomainResourceRecordRequest"> < <wsdl:part name="inpRR" type="tns2:WSDomainResourceRec"/> </wsdl:message> Response There is no data in the response. Parameters WSDomainResourceRec Below is the portion of Imports.Im portDomainResourceRecord ImportDomainResourceRecord Overview The ImportDomainResourceRecord API enables the web service client to import resource records into IPControl that are not bound to a device. Request The complex type WSDomainResourceRec. <complexType name="WSDomainResourceRecord"> <sequence> <element name="TTL" nillable="true" type="soapenc:string" /> <element name="data" nillable="true" type="soapenc:string" /> <element name="owner" nillable="true" type="soapenc:string" /> <element name="resourceRecClass" nillable="true" type="soapenc:string" /> <element name="resourceRecType" nillable="true" type="soapenc:string" /> <element name="domain" nillable="true" type="soapenc:string" /> <element name="domainType" nillable="true" type="soapenc:string" /> <element name="comment" nillable="true" type="soapenc:string" /> </sequence> </complexType> Application Program Interfaces (API) 223 .wsdl that describes the importDomainResourceRecord request and response messages. is described in the next section.wsdl that describes WSDomainResourceRec. which is passed as input from the client to the web service. but still appear in a zone file. Request and Response Messages Below is the portion of Imports. the “Default” domain type will be used.Im portDomainResourceRecord Elem ent Accepted Values Required Return Code Faultstring domainType Domain type already defined to IPControl. Yes. If not specified. No resourceRecord Type The Type of the resource Record. No 224 IPControl CLI and API Guide . -108 Domain not found: domainType/domain -107 Domain not specified N/A Not authorized -89 Owner not specified -106 Invalid character in owner -92 Invalid Type -91 Data Required owner The owner field of the resource record. No data The data portion of the resource record. Yes resourceRecClass The Class of the Resource Record. Defaults to “IN”. The format is dependent on the type specified above. No -108 Domain not found: domainType/domain domain Domain name where resource records are to be added. Yes TTL The Time To Live for the record. Yes comment Comment text associated with the resource record. which is passed as input from the client to the web service. Request The complex type WSGalaxyDomain. The elements are described in the table that follows. is described in the next section. <wsdl:message name=" importGalaxyDomainResponse" /> <wsdl:message name="importGalaxyDomaiRequest"> < <wsdl:part name="inpGalaxyDomain" type="tns2:WSGalaxyDomain"/> </wsdl:message> Response There is no data in the response. the parameter structure passed to importGalaxyDomain. <complexType name="WSGalaxyDomain"> <sequence> <element name="domainName" nillable="true" type="soapenc:string" /> <element name="domainType" nillable="true" type="soapenc:string" /> <element name="galaxyName" nillable="true" type="soapenc:string" /> <element name="view" nillable="true" type="soapenc:string" /> </sequence> </complexType> Application Program Interfaces (API) 225 .wsdl that describes WSGalaxyDomain.wsdl that describes the importGalaxyDomain request and response messages. Request and Response Messages Below is the portion of Imports.Im portGalaxyDomain ImportGalaxyDomain Overview The ImportGalaxyDomain API enables the web service client to assign domains to galaxies in IPControl. Parameters WSGalaxyDomain Below is the portion of Imports. Yes. to assign to the specified galaxy. No -81 Domain type not found: domainType galaxyName Name of the galaxy to which to assign this domain. the “Default” domain type will be used. If not specified. -157 Domain view combination already exists in this galaxy domainType The name of the domain type to which the domain belongs. Either remove the server from the GalaxyProfile or remove the Zone from the Server. already defined in IPControl. Yes -153 Galaxy not found: galaxy -154 Galaxy must have profile defined -156 Galaxy name required -58 View not found: view for galaxy: galaxy view The name of the galaxy view to which to assign this domain.Im portGalaxyDomain Elem ent Accepted Values Required Return Code Faultstring domainName Domain name. 226 IPControl CLI and API Guide No . -60 Domain not found: domain for domainType: domainType -71 Domain Name is required -155 Exception saving galaxy domain galaxyName -157 Found problem with profile master server : Cannot have the same zone on both the server and the galaxy. Vendor must be predefined in IPControl. Yes 1 IP Address The IP address or fullyqualified domain name (FQDN) of the Network Element. Request and Response Messages Below is the portion of Imports. with the faultstrings shown below.userException. When an error occurs. Elem ent Description Accepted Values Required 0 Name The name of the Network Element. Note that the returnCode tag is not used for this call. Request The string array that is passed as input from the client to the web service is described in the next section.Im portNetElement ImportNetElement Overview The ImportNetElement API enables the web service client to import network elements into IPControl. Parameters String Array The elements of the string array are described below. Return Code Faultstring Duplicate name for Netelement: name no models found for given description: description deviceName: name. <wsdl:message name="importNetElementRequest"> <wsdl:part name="elementArray" type="impl:ArrayOf_soapenc_string" /> </wsdl:message> <wsdl:message name="importNetElementResponse"> <wsdl:part name="importNetElementReturn" type="soapenc:string" /> </wsdl:message> Response The string returned in the response contains the name of the network element allocated.wsdl that describes the importNetElement request and response messages. for example. “Saved netelement: name”. vendorName: Application Program Interfaces (API) 227 . If not specified. Yes when Model is specified. or a full-qualified host name. the faultcode will be Server. defaults to Unknown. Yes 2 Vendor The vendor of the Network Element. This can be any combination of letters and numbers. This must be a valid IPv4 or IPv6 IP address. No 11 Interface List Separated by vertical bars (“|”). router. switch or vpn. No 10 Read community string The community string used by SNMP to read details from this network element. No 12 V3 Username Required if using SNMP V3. If not specified. if needed. No 9 Enable password Password used to enter “enabled” or “privileged” mode on the device. No SNMP V3 Username required 13 V3 Authentication Protocol Either MD5 or SHA1. No 17 V3 Context Name SNMP V3 Context name. Accepted values are cmts.Im portNetElement Elem ent Description Accepted Values Required Return Code Faultstring 3 Model The model name of the Network Element. No 18 V3 Engine ID SNMP V3 Engine ID. Leave blank or set to NONE if no authentication. defaults to Unknown. No Unknown authentication protocol: protocol 14 V3 Authentication Password Required if field N is set to either MD5 or SHA1 No Authentication Password required 15 V3 Privacy Protocol Only DES supported at this time. Yes 7 Telnet User A user name used to telnet to this device. Model must be predefined in IPControl. Leave blank or set to NONE if no privacy. Yes same as above 5 Global Sync Whether or not to include this Network Element in the Global Sync process. No 228 IPControl CLI and API Guide Privacy Password required . No Unknown privacy protocol: protocol vendor Privacy not allowed without authentication 16 V3 Privacy Password Required if field P is set to DES. No 8 Telnet password A password used by the telnet user to telnet to this device. if needed. Accepted values are True or False (case insensitive). Yes when Vendor is specified same as above 4 Type The type of Network Element. Yes 6 Agent Name The exact name of the IPControl Agent that is responsible for contacting this Network Service. Request The complex type WSNetElementInterface. the parameter structure passed to importNetElementInterface. is described in the next section.Im portNetElementInterface ImportNetElementInterface Overview The ImportNetElementInterface API enables the web service client to import Network Element Interfaces into IPControl. <complexType name="WSNetElementInterface"> <sequence> <element name="id" nillable="true" type="soapenc:int"/> <element name="interfaceName" nillable="true" type="soapenc:string"/> <element name="netElementName" nillable="true" type="soapenc:string"/> <element name="status" nillable="true" type="soapenc:string"/> </sequence> </complexType> Elem ent Accepted Values Required id The internal identifier for this network element interface object. <wsdl:message name="importNetElementInterfaceResponse" /> <wsdl:message name="importNetElementInterfaceRequest"> <wsdl:part name="inpNetElementInterface" type="tns2:WSNetElementInterface" /> </wsdl:message> Response There is no data in the response.wsdl that describes the importNetElementInterface request and response messages. the interface with the matching identifier is updated. If this is not set. Parameters WSNetElementInterface Below is the portion of Imports. a new interface is created. Request and Response Messages Below is the portion of Imports. The elements are described in the table that follows. If this is set.wsdl that describes WSNetElementInterface. which is passed as input from the client to the web service. No Return Code Faultstring Application Program Interfaces (API) 229 . or “Deployed”. Yes -37 Interface already exists with this name: name for netelement: netelement -20 Interface name is required -33 Network element not found: netelement -35 Element name required -34 Invalid interface status: status netElementName status The name of a Network Element already defined to IPControl. “Enabled”. The default on an import is “Enabled”. The status of the interface. 230 IPControl CLI and API Guide . Yes No Other returnCodes and faultstrings Return Code Faultstring -2 Exception occurred trying to read the network element. This can be one of “Disabled”.Im portNetElementInterface Elem ent Accepted Values Required Return Code Faultstring interfaceName The name of the interface being added or modified. Use the ImportDhcpServer API instead. the parameter structure passed to importNetService. The elements are described in the table that follows. Request The complex type WSNetService. ImportNetService support will be removed in a future release. is described in the next section. which is passed as input from the client to the web service.0.Im portNetService ImportNetService Overview The ImportNetService API enables the web service client to import DHCP network services into IPControl. <complexType name="WSNetService"> <sequence> <element name="agentName" nillable="true" type="soapenc:string" /> <element name="collectionMethod" nillable="true" type="soapenc:string" /> <element name="collectionPort" nillable="true" type="soapenc:string" /> <element name="container" nillable="true" type="impl:ArrayOf_soapenc_string" /> <element name="globalSync" nillable="true" type="soapenc:string" /> <element name="ipAddress" nillable="true" type="soapenc:string" /> <element name="name" nillable="true" type="soapenc:string" /> <element name="threshold" nillable="true" type="soapenc:string" /> <element name="type" nillable="true" type="soapenc:string" /> <element name="userName" nillable="true" type="soapenc:string" /> <element name="userPassword" nillable="true" type="soapenc:string" /> <element name="vendor" nillable="true" type="soapenc:string" /> <element name="vendorInfo" nillable="true" type="impl:ArrayOf_soapenc_string"/> </sequence> </complexType> Application Program Interfaces (API) 231 . <wsdl:message name="importNetServiceResponse" /> <wsdl:message name="importNetServiceRequest"> <wsdl:part name="inpNetService" type="tns1:WSNetService" /> </wsdl:message> Response There is no data in the response. Request and Response Messages Below is the portion of Imports. Parameters WSNetService Below is the portion of Imports. Note: This API has been deprecated as of IPControl 6.wsdl that describes the importNetService request and response messages.wsdl that describes WSNetService. If no value is specified. INS DHCP or CNR DHCP. and 21 if the collection method is ftp. This can be any combination of letters and numbers. Yes -29 Invalid network service agent: agent collectionMethod The method by which the IPControl Agent will collect data from the Network Service. Accepted value is dhcp. Yes -47 productAction failed -99 Product not found -28 Unrecognized collection type: type 232 IPControl CLI and API Guide . Yes threshold Default scope utilization warning threshold. Used in conjunction with the ‘User name for collection’. If this column is left blank. This must be a value already defined in IPControl. If no value is specified. This must be a valid IPv4 or IPv6 IP address.Im portNetService Elem ent Accepted Values Required Return Code Faultstring agentName The name of the IPControl Agent that is responsible for contacting this Network Service. dhcp is assumed. Accepted values are scp or ftp. or a fully-qualified host name. No -27 Invalid network service type: type userName The username used by the collection method (scp or ftp) to log in to the remote server. No -31 Invalid network service collection method: method collectionPort The port number the collection method (scp or ftp) is listening on. this will default to 90. this will default to 22 if the collection method is scp. If no value is specified. for example. No vendor The Network Service product name. Provide warnings when usage of a pool assigned to this service is exceeded. No -57 Invalid alert threshold: value type The type of Network Service. No userPassword The password used by the collection method (scp or ftp) to log in to the remote server. globalSync Whether or not to include this Network Service in the Global Sync process. Accepted values are True or False (case insensitive). No -32 Invalid network service collection port: port container No longer used. this will default to False. Yes -26 Invalid network service address: address name The name of the Network Service. No -30 Invalid network global sync option: option ipAddress The IP address or fully-qualified domain name (FQDN) of the Network Service. Im portNetService Elem ent Accepted Values Required vendorInfo A string array containing vendor specific information for the product’s collection type. For collection types qip,adc, msft and isc, the information includes the DHCP Configuration file pathname and DHCP Active Lease file pathname. For example, No Return Code Faultstring /opt/qip/dhcp/dhcpd.conf /opt/qip/dhcp/dhcp.db or c:\qip\dhcp\dhcpd.conf c:\qip\dhcp\dhcp.db For collection type cnr, the information includes the Path/Executable of NRCD command, the NRCMD user id, the NRCMD password and the Cluster Name. For example, /opt/cnr/bin/nrcmd|myuserid|mypass cluster1 Other returnCodes and faultstrings Return Code Faultstring -1 Unable to obtain session or Rollback failed. Additional information will appear in the web service log. Application Program Interfaces (API) 233 Im portPrefixPool ImportPrefixPool Overview The ImportPrefixPool API enables the web service client to import or modify prefix pools in IPControl. Request and Response Messages Below is the portion of Imports.wsdl that describes the importPrefixPool request and response messages. <wsdl:message name="importPrefixPoolRequest"> <wsdl:part name="prefixPool" type="tns2:WSPrefixPool"/> </wsdl:message> <wsdl:message name="importPrefixPoolResponse"/> Response There is no data in the response. Request The complex type WSPrefixPool, which is passed as input from the client to the web service, is described in the next section. Parameters WSPrefixPool Below is the portion of Imports.wsdl that describes WSPrefixPool, the parameter structure passed to importPrefixPool. The elements are described in the table that follows. <complexType name="WSPrefixPool"> <sequence> <element name="allowClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="delegatedPrefixLength" nillable="true" type="soapenc:int"/> <element name="denyClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="dhcpOptionSet" nillable="true" type="soapenc:string"/> <element name="dhcpPolicySet" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="length" nillable="true" type="soapenc:int"/> <element name="longestPrefixLength" nillable="true" type="soapenc:int"/> <element name="name" nillable="true" type="soapenc:string"/> <element name="primaryNetService" nillable="true" type="soapenc:string"/> <element name="shortestPrefixLength" nillable="true" type="soapenc:int"/> <element name="startAddr" nillable="true" type="soapenc:string"/> <element name="type" nillable="true" type="soapenc:string"/> </sequence> </complexType> 234 IPControl CLI and API Guide Im portPrefixPool Elem ent Description and accepted values Required Return Code Faultstring id The internal identifier for this address pool object. If this is not set, a new prefix pool is created. If this is set, the prefix pool with the matching identifier is updated. No for creates, Yes for updates. -117 PrefixPool ID=<id> not found The IP Address of the first address in the pool. This address must be in a block with an InUse/Deployed status. Yes -115 Missing Start or Length -36 Block Not Found -97 Block Not Unique -115 Invalid Start Address -258 Missing Prefix Length Bad Prefix Length -26 End Address is Outside of Block -73 Invalid Address Type startAddr Length Length of the prefix pool Yes Invalid ID <id> on prefixPool object type One of “Dynamic PD DHCPv6”,” Automatic PD DHCPv6” Yes name Address Pool name. Defaults to “Start Address/Length” No container The name of the container that holds the block in which the pool is defined. This is required only if there is overlapping address space in use and the start address is in overlapping space. The container is then used to uniquely determine the block that will contain the address pool. No, unless startAddr is not unique. -36 Block not found in container delegatedPrefi xLength Specifies the default length of the delegated prefix Yes -258 Missing Delegated Prefix Length Bad Delegated Prefix Length shortestPrefix Length Specifies the shortest length of the delegated prefix. CNR only. No longestPrefixL ength Specifies the longest length of the delegated prefix. CNR only. No primaryNet Service The name of the DHCP server that will serve prefixes from this pool No -94 DHCP Server not found dhcpOptionSe t The name of an Option Set used with this pool No -67 DHCP Option Set not found dhcpPolicySet The name of a Policy Set used with this pool. No -68 DHCP Policy Set not found DHCP Server not valid for this container Application Program Interfaces (API) 235 Im portPrefixPool Elem ent Description and accepted values Required Return Code Faultstring allowClient Classes An array of Client Classes that are allowed in this address pools. Each element of the array names a different Client Class. No -116 DHCP Client Class not found denyClientClas ses An array of Client Classes that are NOT allowed in this address pools. Each array element names a different Client Class. No -116 DHCP Client Class not found 236 IPControl CLI and API Guide Im portRootBlock ImportRootBlock Overview The ImportRootBlock API enables the web service client to import root blocks into IPControl. Request and Response Messages Below is the portion of Imports.wsdl that describes the importRootBlock request and response messages. <wsdl:message name="importRootBlockResponse" /> <wsdl:message name="importRootBlockRequest"> <wsdl:part name="inpRootBlock" type="tns1:WSRootBlock" /> </wsdl:message> Response There is no data in the response. Request The complex type WSRootBlock, which is passed as input from the client to the web service, is described in the next section. Parameters WSRootBlock Below is the portion of Imports.wsdl that describes WSRootBlock, the parameter structure passed to importRootBlock. The elements are described in the table that follows. <complexType name="WSRootBlock"> <sequence> <element name="RIR" nillable="true" type="soapenc:string" /> <element name="SWIPname" nillable="true" type="soapenc:string" /> <element name="allocationReason" nillable="true" type="soapenc:string" /> <element name="allocationReasonDescription" nillable="true" type="soapenc:string" /> <element name="allowOverlappingSpace" nillable="true" type="soapenc:string" /> <element name="blockAddr" nillable="true" type="soapenc:string" /> <element name="blockName" nillable="true" type="soapenc:string" /> <element name="blockSize" nillable="true" type="soapenc:string" /> <element name="blockType" nillable="true" type="soapenc:string" /> <element name="container" nillable="true" type="soapenc:string" /> <element name="createReverseDomains" nillable="true" type="soapenc:string" /> <element name="description" nillable="true" type="soapenc:string" /> <element name="domainType" nillable="true" type="soapenc:string" /> <element name="organizationId" nillable="true" type="soapenc:string" /> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string" /> </sequence> </complexType> Application Program Interfaces (API) 237 Im portRootBlock Elem ent Accepted Values Required Return Code Faultstring RIR The Regional Internet Registry this space was obtained from. Accepted values are: Generic, RFC1918, ARIN, RIPE, APNIC, LACNIC, and AFRINIC. If not specified, Generic is assumed. No -14 Unknown root block type (RIR): type SWIPname SWIP/Net name for the block. Yes, if required by Container rules -66 SWIPname is required for this container/ blocktype -70 SWIPname is not allowed for this container/ blocktype -22 Invalid allocation reason: reason allocationReason The name of a pre-existing Allocation Reason. No allocationReason Description A description of the reason for the allocation. No allowOverlapping Space Whether or not to allow duplicate (overlapping) address space in this block. Accepted values are true or false. If not specified, defaults to false. No -159 Overlapping Public Address Space is not allowed. blockAddr The IP block to create. This should be in the format of a network address (e.g., 10.0.0.0). Yes -12 Invalid block address: exception blockName A name for the block. Defaults to system supplied name of Address space/Block size. No blockSize The size of the block in shortnotation (e.g., 24 for a 255.255.255.0 network). Yes -16 Invalid block size mask: exception -15 Invalid block size: exception blockType The Block Type of the block. If not specified, a block type of Any is assumed. No -13 Unknown block type container The name of the logical container that will hold the block. Names can be in either short or long format. Short format example: Dallas. Long format example: IPControl/Texas/Dallas. Long format eliminates ambiguity in cases where there are duplicate container names. Yes -2 Could not find container: container Invalid container name 238 IPControl CLI and API Guide -6 -7 Ambiguous container name -5 -1 Container not found -5 Unable to lookup container -148 Container does not allow root block creation. -277 Cannot add root block to device container Database error Im portRootBlock Elem ent Accepted Values Required Return Code Faultstring createReverse Domains Whether or not to automatically create reverse DNS domain(s) for this block. Accepted values are true or false. If not specified, defaults to false. No -82 createReverseDomains must be true or false: value description A description of the block. Use “\n” to separate lines. No domainType Specify the domain type for the reverse DNS domain(s) to be created when Create Reverse Domains is “true”. If not specified, defaults to “Default”. No -81 Domain type not found: domainType organizationId The organization id for the Regional Internet Registry this space was obtained from. This id must be predefined in IPControl. No -84 Invalid Organization Id: id userDefinedFields A string array containing one or more name=value pairs, where the name is the UDF name and the value is the desired value, for example, State=PA. If the UDF type is Checkbox, the valid values are on and off. Yes, for UDFs defined as required fields. -53 store UDFs failed: SQL exception message Other returnCodes and faultstrings Return Code Faultstring -24 Duplicate or overlapping root block: blockname -25 Duplicate or overlapping root block in container tree: blockname -99 Access Denied. Either the administrator does not have rights to add blocks in general OR the administrator does not have rights to add blocks to the specified container. Application Program Interfaces (API) 239 <complexType name="WSDnsZone"> <sequence> <element name="MNAME" nillable="true" type="soapenc:string"/> <element name="acceptZoneTransfers" nillable="true" type="soapenc:string"/> <element name="aliasZone" type="xsd:boolean"/> <element name="allowUpdateACL" nillable="true" type="soapenc :string"/> <element name="autogenNSGlue" nillable="true" type="soapenc:string"/> <element name="domainName" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="dynamicZone" type="xsd:boolean"/> <element name="filename" nillable="true" type="soapenc:string"/> <element name="galaxyName" nillable="true" type="soapenc:string"/> <element name="masters" nillable="true" type="soapenc:string"/> <element name="server" nillable="true" type="soapenc:string"/> <element name="templateZone" type="xsd:boolean"/> <element name="updatePolicy" nillable="true" type="soapenc:string"/> <element name="updateZone" nillable="true" type="soapenc:string"/> <element name="view" nillable="true" type="soapenc:string"/> <element name="zoneExtensionsAfter" nillable="true" type="soapenc:string"/> <element name="zoneExtensionsPrior" nillable="true" type="soapenc:string"/> <element name="zoneType" nillable="true" type="soapenc:string"/> </sequence> </complexType> 240 IPControl CLI and API Guide .wsdl that describes WSDnsZone. The elements are described in the table that follows. Parameters WSDnsZone Below is the portion of Imports. <wsdl:message name="importDnsZoneResponse" /> <wsdl:message name="importDnsZoneRequest"> <wsdl:part name="inpZone" type="tns1: WSDnsZone" /> </wsdl:message> Response There is no data in the response.Im portZone ImportZone Overview The ImportDnsZone API enables the web service client to import zones into IPControl. the parameter structure passed to importDnsZone. Request The complex type WSDnsZone. which is passed as input from the client to the web service. is described in the next section. Request and Response Messages Below is the portion of Imports.wsdl that describes the importDnsZone request and response messages. specified: value Yes -60 Domain not found: domainType/domain -71 Domain Name is required -81 Domain type not found: domainType No Application Program Interfaces (API) 241 . Required Return Code Faultstring No -236 MNAME valid only for master zones -238 Domain is not an alias: domain No No Yes. Accepted values are true or false. Indicates if the imported zone is intended to be a alias zone. If not specified. If not specified. when -252 Dynamic Zone is true. domainName Domain name already defined to IPControl domainType Domain type name already defined to IPControl. defaults to false. one of Allow Update ACL or Update Policy must be specified. Accepted values are true or false. This field only applies to master zones. Setting this field value to “!BLANK!” on a zone update will serve to completely remove the ‘allow -update’ option from the zone. Update option invalid for non-dynamic zone No -241 autogenNSGlue must be true or false. If not specified. If not specified. defaults to true. It will be ignored for all other zone types and any zone designated as an Alias zone. If not specified. The linked template zone will be chosen by using the zone assigned to the template domain to which the alias domain is linked. Accepted values are true or false. It will be ignored for all other zone types. the “Default” domain type will be used. defaults to true. no MNAME will be used. Specifies the DNS ‘allow -update’ address match list a BIND based server uses to filter DDNS update requests against. This field only applies to master zones. acceptZoneTransfers aliasZone allowUpdateACL This free text field only applies to master zone types and is accepted without input validation. autogenNSGlue This field is ignored for non-master zones.Im portZone Elem ent Description and accepted values MNAME Specifies an alternative name for the primary or “master” DNS server that DDNS requests should be sent to for this zone. Im portZone Elem ent dynamicZone Description and accepted values Accepted values are true or false. If not specified, defaults to false. true indicates that this is a dynamic zone. Applicable only for master zones and BIND based servers. When true, you must specify either Update Policy or Allow Update ACL. Required Return Code Faultstring No -250 Dynamic zones must be master zones -251 Update option required for dynamic zone -253 Only zones associated with BIND servers can be dynamic -255 Cannot specify both allow update and update policy filename The name of the zone file that will be generated by IPControl. If not specified, will default to a systemgenerated value based on zone type. No galaxyName Future use. No masters For zone types slave and stub only, specify the master server. This field is not valid for other zone types. Yes for zone types slave and stub -237 Masters only valid for slave and stub zones server The network service name of the DNS Server. Yes, if GalaxyNa me is not supplied. -235 Server name required templateZone Indicates if the imported zone is intended to be a template zone. Accepted values are true or false. If not specified, defaults to false. No -239 Template Zone not found: templateDomain for server: server -240 Domain is not a template: domain Specifies an update policy, already defined in IPControl, for a dynamic master zone. Setting this field value to “!BLANK!” on a zone update will serve to completely remove the update policy option from the zone. Yes, when -252 Dynamic Zone is -254 true, one of Allow Update ACL or Update Policy must be specified. Update option invalid for non-dynamic zone updatePolicy This field is ignored for non-master and non-dynamic zones. updateZone Specify true to update an existing zone, false to import a new zone. If not specified, defaults to false. When true, specify all fields as you would for an import. Any field not specified on an update is cleared or set to its default value. 242 IPControl CLI and API Guide No Update policy not found: policy Im portZone Elem ent Description and accepted values Required Return Code Faultstring -58 View not found: view for server: server -85 Zone type is required -86 Invalid zone type: zonetype view The name of the view in which the new zone will be created. If specified, the view must exist. If not specified, the new zone will be created in the view named 'Default.' No zoneExtensionsAfter Specifies the name of the file containing text lines that will be inserted following the resource records for this zone. No zoneExtensionsPrior Specifies the name of the file No containing text lines that will be inserted prior to the resource records for this zone. Specifies the type of zone being Yes imported. Accepted values are master, slave, forward or stub. zoneType Other returnCodes and faultstrings Return Code Faultstring -2 Various - Allocation failed due to unexpected exception -99 Access denied -157 Zone domainName already exists. Specify 'Update Zone' to change Application Program Interfaces (API) 243 JoinBlock JoinBlock Overview The JoinBlock API enables the web service client to join existing, adjacent blocks into a larger block. Request and Response Messages Below is the portion of Imports.wsdl that describes the joinBlock request and response messages. <wsdl:message name="joinBlockRequest"> <wsdl:part name="blockName" type="soapenc:string"/> <wsdl:part name="container" type="soapenc:string"/> </wsdl:message> <wsdl:message name="joinBlockResponse"> </wsdl:message> Response There is no data in the response. Request Parameters blockName Specify the name of the block, for example, 10.0.0.0/24. The system searches for nonfree blocks by this name. container The container name must be specified if the block name is not unique, due to overlapping space or naming conventions. Return Codes and Fault Strings Return Code Fault String -12 Invalid Block Address -17 Invalid Block Status -36 Block not found -97 Block not unique -138 Block exists in multiple containers -139 No valid adjoining block -140 Block is not on bit boundary -141 Blocks are not contiguous -142 Block join size different -199 Container not found -53 SQL Exception pinning connection -99 Access Denied 244 IPControl CLI and API Guide ModifyBlock ModifyBlock Overview The ModifyBlock API enables the web service client to update certain fields in an existing Block. To modify a block, use this call in conjunction with the GetBlock API (Page 258) calls. First, retrieve the block using a GetBlock call. Then, modify the returned structure (see below). Lastly, pass that modified structure to the ModifyBlock API. Request and Response Messages Below is the portion of Imports.wsdl that describes the modifyBlock request and response messages. <wsdl:message name="modifyBlockRequest"> <wsdl:part name="block" type="tns2:WSGenericBlock"/> <wsdl:part name="container" type="soapenc:string"/> </wsdl:message> <wsdl:message name="modifyBlockResponse"> </wsdl:message> Response There is no data in the response. Request The complex type WSGenericBlock, which is passed as input from the client to the web service, is described in the next section. Parameters Container The container name must be specified if the block is attached to multiple containers. This enables the User Defined Field updates to be processed correctly. WSGenericBlock Below is the portion of Imports.wsdl that describes WSGenericBlock, the parameter structure passed to modifyBlock. The elements are described in the table that follows. Application Program Interfaces (API) 245 ModifyBlock <complexType name="WSGenericBlock"> <sequence> <element maxOccurs="unbounded" name="addrDetails" nillable="t rue" type="tns2:WSAllocationTemplateDetails"/> <element name="allocationReason" nillable="true" type="soapenc:string"/> <element name="allocationReasonDescription" nillable="true" type="soapenc:string"/> <element name="allocationTemplateName" nillable="true" type="soapenc:string"/> <element name="allowOverlappingSpace" type="xsd:boolean"/> <element name="blockAddr" nillable="true" type="soapenc:string"/> <element name="blockName" nillable="true" type="soapenc:string"/> <element name="blockSize" type="xsd:int"/> <element name="blockStatus" nillable="true" type="soapenc:string"/> <element name="blockType" nillable="true" type="soapenc:string"/> <element name="container" nillable="true" type="impl:ArrayOf_soapenc_st ring"/> <element name="createadmin" nillable="true" type="soapenc:string"/> <element name="createdate" nillable="true" type="xsd:dateTime"/> <element name="description" nillable="true" type="soapenc:string"/> <element name="excludeFromDiscovery" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="inheritDiscoveryAgent" nillable="true" type="soapenc:int"/> <element name="interfaceAddress" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="interfaceName" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="ipv6" type="xsd:boolean"/> <element name="lastadminid" type="xsd:int"/> <element name="lastupdate" nillable="true" type="xs d:dateTime"/> <element name="numaddressablehosts" type="xsd:long"/> <element name="numallocatedhosts" type="xsd:long"/> <element name="numassignedhosts" type="xsd:long"/> <element name="numdynamichosts" type="xsd:long"/> <element name="numleasablehosts" type="xsd:long"/> <element name="numlockedhosts" type="xsd:long"/> <element name="numreservedhosts" type="xsd:long"/> <element name="numstatichosts" type="xsd:long"/> <element name="numunallocatedhosts" type="xsd:long"/> <element name="organizationId" nillable="true" type="soapenc:string"/> <element name="primarySubnet" type="xsd:boolean"/> <element name="rir" nillable="true" type="soapenc:string"/> <element name="rootBlock" type="xsd:boolean"/> <element name="rootBlocktype" nillable="true" type="soapenc:string"/> <element name="subnet" nillable="true" type="tns1:WSSubnetPolicy"/> <element name="subnetlosshosts" type="xsd:long"/> <element name="swipname" nillable="true" type="soapenc:string"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="ignoreErrors" type="xsd:boolean"/> </sequence> </complexType> Elem ent Description Modify? addrDetails Define attributes of any address allocations of the specified allocation template. See below. Yes allocationReason The architected code for block creation No allocationReason Description The text entered at creation for the allocation reason. No. 246 IPControl CLI and API Guide Return Code Fault String ModifyBlock Elem ent Description Modify? Return Code Fault String allocationTemplateName For a block with blockStatus=Deployed, or if changing the blockStatus to Deployed, the name of the allocation template to use to create address pools from the newly created block. Yes -17 Allocation Template supported only for In-Use/Deployed blocks -21 allowOverlappingSpace If true, the block can overlap other blocks in the system. No blockAddr The starting address of the block No blockName The Name of the block Yes blockSize The CIDR size of the block No blockStatus Block Status, one of “Free”, “Reserved”, “Aggregate”, “Deployed”, “FullyAssigned” Yes blockType The name of the block type. No container An array of container names No createadmin The name of the administrator that created the block No createdate The date and time when this block was created No description The block Description. Use “\n” to separate lines. Yes Invalid offset -65 Invalid allocation template: name -177 Address Pool Template detail overlaps interface address. -182 No domain set, create resource records failed. -189 Default Gateway(s) have been defined in the Subnet Policies. Address pool templates with default gateway option are not allowed. -207 Range conflicts with pool pool in Block block name in Container container name -17 Invalid Block Status Application Program Interfaces (API) 247 ModifyBlock Elem ent Description Modify? Return Code Fault String excludeFromDiscovery Flag indicating if this subnet should be included in Host Discovery tasks. Accepted values are true or false. If not specified, defaults to false. Yes -13 BlockModify set exclude from discovery failed: flag supported only for InUse/Deployed blocks Valid only for Deployed blocks. -241 id The block ID. This MUST be supplied in order to update the block. No inheritDiscoveryAgent Setting to indicate if the block inherits the discover agent from the container or not No interfaceAddress Array of IP Addresses where this block connects to a network element. No Note that you can modify or delete an Interface type address, but you cannot add one. -36 Block not found -273 Error saving interface address: address -275 Note that you cannot modify or delete a virtual interface address. interfaceName Array of Interface Names attached to this block True if this is an IPV6 block No lastadminid ID of the last administrator to update this block. Updated automatically by this call. No lastupdate Time of last update to this block. Updated automatically by this call. No numaddressablehosts Number of Addressable hosts No numallocatedhosts Number of Allocated hosts No numassignedhosts Number of Assigned hosts No numdynamichosts Number of Dynamic hosts No numleasablehosts Number of hosts that can be leased No numlockedhosts Number of locked hosts No numreservedhosts Number of reserved hosts No numstatichosts Number of static hosts No numunallocatedhosts Number of Unallocated Hosts No organizationId Org ID of the RIR Organization Yes ipv6 248 IPControl CLI and API Guide BlockModify set exclude from discovery must be true or false Modifying or deleting a virtual address interface is not supported No -84 Unknown RIR Organization Each element in the array has the format “name=value” where “name” is the UDF tag name. First. use this call in conjunction with the GetBlock API (page 258) calls. Yes -17 Subnet policies supported only for In-Use/Deployed blocks subnetlosshosts Number of hosts lost due to subnetting No swipname SWIP Name for ARIN blocks Yes -137 Duplicate SWIP Name -66 SWIP Name Required -70 SWIP Name not allowed -63 Invalid UDF -64 Missing Required UDF userDefinedFields ignoreErrors Array of user defined fields. Yes -17 modifyBlock set primary subnet failed: flag supported only for In-Use/Deployed blocks rir Name of the RIR Organization Yes -84 Unknown RIR Organization rootBlock True if this is a root block No rootBlocktype Name of the internet registry Yes -14 Invalid Root Block Type subnet Subnet parameters. Lastly. or modifies the block without a reparent. when set to true will cause the system to ignore any errors associated with reparenting a block from a container with a container/blocktype information template to a container without. Yes Flag. Then. a target interface name must also be provided. the new interface name. Note: ModifyBlock either reparents. No Reparenting a Block via Modify Block API A block may be reparented by specifying a target container name different than the current parent container name. modify the returned structure. Valid only for Deployed blocks in device containers. In the case of reparenting blocks contained in device containers. Accepted values are true or false. pass that modified structure to the ModifyBlock API. retrieve the block using a GetBlock call. To reparent a block.ModifyBlock Elem ent Description Modify? Return Code Fault String primarySubnet Flag indicating if this subnet is primary. Application Program Interfaces (API) 249 . setting the new container name and in the case of device container. when a new container name different than the current parent container has been specified. Both cannot be performed during the same modify block invocation. See below. yes -68 DHCP Policy Set name not found DNSServers The name of previously defined DNS servers to be sent as an IP address to the client. The elements are described in the table that follows. Note that address pool and IP address objects that are configured with “Same as Subnet” for the primary DHCP server will be unaffected. yes defaultGateway The default gateway that DHCP clients on this subnet will use. yes -67 DHCP Option Set name not found DHCPPolicySet The name of a previously defined DHCP policy set. -99 Admin does not have read access to server: name cascadePrimary DhcpServer If address pool or individual IP address objects within the subnet reference a specific DHCP server. yes -93 DNS Server name not found. yes -26 Invalid IP Address address 250 IPControl CLI and API Guide . the structure passed in WSGenericBlock as “subnet”.wsdl that describes WSSubnetPolicy. Accepted value is an IP address.ModifyBlock Modifying Block Subnet Policies Use the subnet field and WSSubnetPolicy structure to specify changes to block subnet policies. WSSubnetPolicy Below is the portion of Imports. this attribute can be used to allow the ‘primaryDHCPServer’ attribute value to “cascade” to these address pool and IP address objects. <complexType name="WSSubnetPolicy"> <sequence> <element name="DHCPOptionsSet" nillable="true" type="soapenc:string" /> <element name="DHCPPolicySet" nillable="true" type="soapenc:string" /> <element name="DNSServers" nillable="true" type="impl:ArrayOf_soapenc_string" /> <element name="cascadePrimaryDhcpServer" nillable="true" type="xsd:boolean" /> <element name="defaultGateway" nillable="true" type="soapenc:string" /> <element name="failoverDHCPServer" nillable="true" type="soapenc:string" /> <element name="forwardDomainTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="forwardDomains" nillable="true" type="impl:ArrayOf_soapenc_string" /> <element name="networkLinks" nillable="true" type=" soapenc:string"/> <element name="primaryDHCPServer" nillable="true" type=" soapenc:string" /> <element name="primaryWINSServer" nillable="true" type=" soapenc:string" /> <element name="reverseDomainTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="reverseDomains" nillable="true" type="impl:ArrayOf_ soapenc_string" /> </sequence> </complexType> Elem ent Description Modify ? Return code Fault String DHCPOptionsS et The name of a previously defined DHCP Options set. wsdl that describes WSAllocationTemplateDetails. WSAllocationTemplateDetails Below is the portion of Imports. yes -94 DHCP name not found -99 Admin does not have write access to server: name forwardDomains The forward domain names that will available to the user when adding an IP address to the system. You can apply a template and specify address details when changing a block’s status to Deployed. yes -95 Invalid reverse DNS Domain name Applying an Allocation Template Use the addrDetails field to optionally specify attributes of any address allocations within the allocation template specified by allocationTemplateName. The elements are described in the table that follows. This cannot be the same as the primary DHCP server. yes -95 Invalid forward DNS Domain name networkLinks Reserved no primaryDHCP Server The name of the DHCP server that will act as primary for this subnet. yes -26 Invalid IP Address address reverseDomains The reverse domain names that will available to the user when adding an IP address to the system. Only required for non-default domain types. Only required for non-default domain types. The first forward domain in the list will be used when there is a domain name DHCP option. yes -95 Invalid forward DNS Domain name forwardDomain Types The domain types corresponding to the domains listed in forwardDomains. <complexType name=" WSAllocationTemplateDetails"> <sequence> <element name="netserviceName" nillable="true" type="soapenc:string"/> <element name="offsetFromBeginningOfSubnet" type="xsd:boolean"/> <element name="sharename" nillable="true" type="soapenc:string"/> <element name="startingOffset" type="xsd:long"/> </sequence> </complexType> Application Program Interfaces (API) 251 .ModifyBlock Elem ent Description Modify ? Return code Fault String failover DHCPServer The name of the DHCP server that will act as failover for this subnet. the structure passed in WSGenericBlock as addrDetails. yes -94 DHCP name not found -99 Admin does not have write access to server: name primaryWINS Server The IP address of the Microsoft WINS server for clients in this subnet. or when modifying a block that is already of status Deployed. yes -95 Invalid reverse DNS Domain name reverseDomain Types The domain types corresponding to the domains listed in reverseDomains. Yes/No sharename The name used to link address pools together. If not specified. No Identify the address allocation within the template. This must match the specification in the Allocation Template. This must match the specification in the Allocation Template. defaults to false..ModifyBlock Elem ent Description Locator/ Modify? Return Code Fault String netserviceName The name of the network service for this address allocation No/Yes -185 Invalid network service name: name offsetFrom BeginningOf Subnet Specify true or false. Yes/No -174 Invalid starting offset: offset for allocation template: templateName Deprecated startingOffset 252 IPControl CLI and API Guide . wsdl that describes the modifyPendingApproval request and response messages. the parameter structure passed to modifyPendingApproval. No -276 Applicable only when Resource record workflow is turned on Specify “Approve” or “Reject”. No -161 Input action null! Invalid action: action Application Program Interfaces (API) 253 .ModifyPendingApproval ModifyPendingApproval Overview The ModifyApproval API enables the web service client to approve or reject changes submitted to the administrator’s pending approval queue. is described in the next section. Parameters WSPendingApproval Below is the portion of Imports. Request The complex type WSPendingApproval. The elements are described in the table that follows. Request and Response Messages Below is the portion of Imports. <complexType name=" WSPendingApproval"> <sequence> <element name="action" nillable="true" type="soapenc:string"/> <element name="reason" nillable="true" type="soapenc:string"/> <element name="workflowId" nillable="true" type="soapenc:int"/> </sequence> </complexType> Elem ent action Description Modify? Return Code Fault String Only approvers can use this CLI No -99 Access denied This API is applicable only when Resource record workflow is turned on. which is passed as input from the client to the web service. <wsdl:message name="modifyPendingApprovalRequest"> <wsdl:part name="approval" type="tns2:WSPendingApproval"/> </wsdl:message> <wsdl:message name="modifyPendingApprovalResponse"> </wsdl:message> Response There is no data in the response.wsdl that describes WSPendingApproval. No. for example. workflowId The id of the pending approval request retrieved using an ExportItemPendingApproval.ModifyPendingApproval Elem ent Description Modify? reason The text entered at creation for the allocation reason. ExportResourceRecordPendingA pproval. No 254 IPControl CLI and API Guide Return Code Fault String -162 Workflow id not found: id . for example. If false.SplitBlock SplitBlock Overview The SplitBlock API enables the web service client to split an existing block into smaller blocks. 10.0. If no start address is specified. along with two blocks of targetSize. container The container name must be specified if the block name is not unique.0/24. Request Parameters blockName Specify the name of the block. targetSize Specify the desired CIDR block size after the split. <wsdl:message name="splitBlockRequest"> <wsdl:part name="blockName" type="soapenc:string"/> <wsdl:part name="container" type="soapenc:string"/> <wsdl:part name="targetStartAddress" type="soapenc:string"/> <wsdl:part name="targetSize" type="xsd:int"/> <wsdl:part name="equalSizes" type="xsd:boolean"/> </wsdl:message> <wsdl:message name="splitBlockResponse"> </wsdl:message> Response There is no data in the response. the start address of the block being split will be used. equalSizes If true. This is useful for creating a block using the specified start address and target block size.0. This parameter works in conjunction with the equalSizes parameter. targetStartAddress Specify the start address of the target block. due to overlapping space or naming conventions.wsdl that describes the splitBlock request and response messages. the block is split such that all resulting blocks have the targetSize CIDR size. the block is split such that the fewest number of new blocks is created. Request and Response Messages Below is the portion of Imports. Application Program Interfaces (API) 255 . The system searches for nonfree blocks by this name. SplitBlock For example. the result will be one /25. if a /24 is split with a target size of /27 with equalSizes set to true. If a /24 is split with a target size of /27 with equalSizes set to false. one /26 and two /27 blocks. the result will be eight /27 blocks. Return Codes and Fault Strings Return Code Fault String -36 Block not found -97 Block not unique -15 Invalid Target Block Size -17 Invalid Block Status -12 Invalid Block Address -9 Subnet creation error -104 Address pool cleanup error -99 Access Denied 256 IPControl CLI and API Guide . Use this call to retrieve an address pool based on its starting address. Return Codes If the address pool is not found. ImportAddressPool will perform an update instead of a create due to the presence of an ID element in the address pool structure. Only if startAddr is not unique due to overlapping blocks. You can see the complete WSDL at: http://localhost:8080/inc-ws/services/Gets?wsdl getAddressPool This operation retrieves information about an address pool from IPControl. Application Program Interfaces (API) 257 . This structure is also used by the ImportAddressPool API call. <wsdl:message name="getAddressPoolResponse"> <wsdl:part name="getAddressPoolReturn" type="tns2:WSAddrpool"/> </wsdl:message> <wsdl:message name="getAddressPoolRequest"> <wsdl:part name="startAddress" type="soapenc:string"/> <wsdl:part name="container" type="soapenc:string"/> </wsdl:message> Response If the address pool is found. This call can be used in conjunction with the ImportAddressPool call to modify an existing address pool. Request and Response Messages Below is the portion of Gets.getAddressPool Gets Overview This section explains the web services available for retrieving individua l objects from IPControl. Request There are two parameters in the request. Each of these services is available as an operation in the Gets web service. Param eter Description Required startAddr The starting address of the Address Pool Yes Container The container holding the block in which the address pool resides. Modify the returned structure as needed and pass the modified structure to ImportAddressPool.wsdl that describes the getAddressPool request and response messages. the call will fail with an error code of -117. These services can be used in conjunction with Imports to modify IPControl objects. a WSAddrpool structure is filled in with its information. Param eter Nam e Description Required Name The Name of the block. these calls differ in how the block is located. e.getBlock getBlock There are two calls to retrieve blocks: getBlockByName getBlockByIpAddress Both calls return a WSGenericBlock data structure.0. <wsdl:message name="getBlockByNameRequest"> <wsdl:part name="name" type="soapenc:string"/> <wsdl:part name="container" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getBlockByNameResponse"> <wsdl:part name="getBlockByNameReturn" type="tns2:WSGenericBlock"/> </wsdl:message> <wsdl:message name="getBlockByIpAddressRequest"> <wsdl:part name="ipAddress" type="soapenc:string"/> <wsdl:part name="container" type="soapenc:string"/> <wsdl:part name="size" type="xsd:int"/> <wsdl:part name="status" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getBlockByIpAddressResponse"> <wsdl:part name="getBlockByIpAddressReturn" type="tns2:WSGenericBlock"/> </wsdl:message> Response If the block is found. See the ModifyBlock API call for more information.0/24 Yes Container The container holding the block.g. Modify the returned structure as needed and pass the modified structure to ModifyBlock.0. Request and Response Messages Below is the portion of Gets.) As their names suggest. 10. 258 IPControl CLI and API Guide . Use one of the above calls in conjunction with the ModifyBlock call to update an existing block. getBlockByName Request This request has two parameters.wsdl that describes the getBlockByName and getBlockByIpAddress request and response messages. Only if name is not unique. a WSGenericBlock structure is filled in with its information. (See the ModifyBlock call for a description of WSGenericBlock. Note that the complete container path will be returned in the WSGenericBlock. Param eter Nam e Description Required ipAddress The starting IP Address of the block Yes container The container holding the block Only if the IP Address is not unique due to overlapping space.getBlock getBlockByIpAddress Request This request has four parameters. “Reserved”.0/8 (aggregate) and 10. size The block’s CIDR size. This can occur for aggregates where there is a free block with the same starting address and size. Only if there are multiple blocks with the same starting address.g. e. “FullyAssigned” Only if there are multiple blocks with the same starting address. status The block’s status. Valid values are “Free”. “Aggregate”. “Deployed”. Return Codes Condition Return Code Container Not Found -5 Block not Unique -97 Invalid IP Address -26 Block not Found -36 Invalid Block Status -17 Application Program Interfaces (API) 259 .0.0.0.0/24 (child block). 10.0. This structure is also used by the ImportContainer API call. Yes Return Codes Condition Return Code Container not found -5 260 IPControl CLI and API Guide . <wsdl:message name="getContainerByNameRequest"> <wsdl:part name="containerName" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getContainerByNameResponse"> <wsdl:part name="getContainerByNameReturn" type="tns1:WSContainer"/> </wsdl:message> Response If the Container is found. Use this call in conjunction with the ImportContainer call to modify an existing container. Param eter Nam e Description Required containerName The name of the container. Request and Response Messages Below is the portion of Gets. This call returns a WSContainer data structure.getContainer getContainer There is one call to retrieve a container: getContainerByName.wsdl that describes the getContainerBy request and response messages. Modify the returned structure as needed and pass the modified structure to ImportContainer. getContainerByName Request There is one parameter in the request. ImportContainer will update the container based on the presence of an ID element in the WSContainer structure. a WSContainer structure is filled in with its information. Only if ipAddress is not unique due to overlapping blocks. As their names suggest. getDeviceByIPAddr Request There are two parameters in the request. This structure is also used by the ImportDevice API call. a WSDevice structure is filled in with its information.wsdl that describes the getDeviceBy request and response messages. Request and Response Messages Below is the portion of Gets. Param eter Nam e Description Required ipAddress The IP address of the device Yes container The container holding the block in which the address pool resides. <wsdl:message name="getDeviceByIPAddrRequest"> <wsdl:part name="ipAddress" type="soapenc:string"/> <wsdl:part name="container" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getDeviceByIPAddrResponse"> <wsdl:part name="getDeviceByIPAddrReturn" type="tns2:WSDevice"/> </wsdl:message> <wsdl:message name="getDeviceByHostnameRequest"> <wsdl:part name="hostname" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getDeviceByHostnameResponse"> <wsdl:part name="getDeviceByHostnameReturn" type="tns2:WSDevice"/> </wsdl:message> <wsdl:message name="getDeviceByMACAddressRequest"> <wsdl:part name="macAddress" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getDeviceByMACAddressResponse"> <wsdl:part name="getDeviceByMACAddressReturn" type="tns2:WSDevice"/> </wsdl:message> Response If the Device is found. Modify the returned structure as needed and pass the modified structure to ImportDevice. Use any of the three calls in conjunction with the ImportDevice call to modify an existing device. they differ in how the device is located. ImportDevice will update the device based on the presence of an ID element in the WSDevice structure. Application Program Interfaces (API) 261 .getDevice getDevice There are three calls to retrieve a device: getDeviceByIPAddr getDeviceByMACAddress getDeviceByHostname All three calls return a WSDevice data structure. Param eter Nam e Description Required macAddress The MAC address of the device Yes getDeviceByHostname Request There is one parameter in the request.getDevice getDeviceByMACAddress Request There is one parameter in the request. Param eter Nam e Description Required hostname The hostname address of the device Yes Return Codes Condition Return Code Device Not Found -120 Multiple IP Addresses found -28 Invalid IP Address -26 Invalid MAC Address -122 Multiple Devices Found -121 Missing Hostname -80 262 IPControl CLI and API Guide . <wsdl:message name="getDeviceResourceRecResponse"> <wsdl:part name="getDeviceResourceRecReturn" type="tns2:WSDeviceResourceRec"/> </wsdl:message> <wsdl:message name=" getDeviceResourceRecRequest"> <wsdl:part name="domainName" type="soapenc:string"/> <wsdl:part name="domainTypeName" type="soapenc:string"/> <wsdl:part name="owner" type="soapenc:string"/> <wsdl:part name="type" type="soapenc:string"/> <wsdl:part name="classtype" type="soapenc:string"/> <wsdl:part name="rdata" type="soapenc:string"/> <wsdl:part name="hostname" type="soapenc:string"/> <wsdl:part name="ipAddress" type="soapenc:string"/> <wsdl:part name="container" type="soapenc:string"/> </wsdl:message> Response If the resource record is found. Yes classtype The value currently supported is IN. container The name of the container that holds the device. Yes. if ipAddress is in overlapping space.wsdl that describes the getDeviceResourceRec request and response messages. Use this call to retrieve a resource record based on its device. Modify the returned structure as needed and pass the modified structure to ImportDeviceResourceRecord. No Application Program Interfaces (API) 263 . ipAddress The IP address of the device.getDeviceResourceRec getDeviceResourceRec This operation retrieves information about a DNS resource record from IPControl. ImportDeviceResourceRecord will perform an update instead of a create due to the presence of an ID element in the resource record structure. Yes. Request These are the request parameters: Param eter Nam e Description Required domainName The name of the domain Yes domainNameType No owner The name of the domain type to which the domain belongs. a WSDeviceResourceRec structure is filled in with its information. This structure is also used by the ImportDeviceResourceRecord API call. Request and Response Messages Below is the portion of Gets. No hostname The device host name. This call can be used in conjunction with the ImportDeviceResourceRecord call to modify an existing DNS resource record. unless hostname is specified. Defaults to “Default”. Yes. No rdata The text for the data area of the record. type The type of resource record. unless IpAddress is specified. The OWNER section of the resource record. getDeviceResourceRec Return Codes Condition Return Code Exception reading from db -2 Invalid IP Address -26 IP Address not unique -28 Domain not found -60 No device with ipaddress or hostname -120 Hostname not unique -121 DNS resource record not found -124 DNS resource record not unique -125 264 IPControl CLI and API Guide . Modify the returned structure as needed and pass the modified structure to ImportDhcpServer. getDhcpServerByName Request There is one parameter in the request. Param eter Nam e Description Required Name The name of the DHCP Server Yes getDhcpServerByIpAddress Request There is one parameter in the request. Param eter Nam e Description Required ipAddress The IP Address of the DHCP Server Yes Return Codes Condition Return Code DHCP Server not found -94 Invalid IP Address -26 Application Program Interfaces (API) 265 . they differ in how the server is located. Use either of the calls in conjunction with the ImportDhcpServer call to modify an existing DHCP Server. As their names suggest. <wsdl:message name="getDhcpServerByNameRequest"> <wsdl:part name="name" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getDhcpServerByNameResponse"> <wsdl:part name="getDhcpServerByNameReturn" type="tns2:WSDhcpServer"/> </wsdl:message> <wsdl:message name="getDhcpServerByIpAddressRequest"> <wsdl:part name="ipAddress" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getDhcpServerByIpAddressResponse"> <wsdl:part name="getDhcpServerByIpAddressReturn" type="tns2:WSDhcpServer"/> </wsdl:message> Response If the DHCP server is found. Request and Response Messages Below is the portion of Gets.wsdl that describes the Dhcp Server request and response messages. This structure is also used by the ImportDhcpServer API call. ImportDhcpServer will update the server based on the presence of an ID element in the WSDhcpServer structure.getDhcpServer getDhcpServer There are two calls for retrieving information about a DHCP server: getDhcpServerByName getDhcpServerByIpAddress Both return a WSDhcpServer structure. a WSDhcpServer structure is filled in with its information. No rdata The text for the data area of the record. <wsdl:message name="getDomainResourceRecResponse"> <wsdl:part name="getDomainResourceRecReturn" type="tns2:WSDomainResourceRec"/> </wsdl:message> <wsdl:message name=" getDomainResourceRecRequest"> <wsdl:part name="domainName" type="soapenc:string"/> <wsdl:part name="domainTypeName" type="soapenc:string"/> <wsdl:part name="owner" type="soapenc:string"/> <wsdl:part name="type" type="soapenc:string"/> <wsdl:part name="classtype" type="soapenc:string"/> <wsdl:part name="rdata" type="soapenc:string"/> </wsdl:message> Response If the resource record is found. No Return Codes Condition Return Code Exception reading from db -2 Domain not found -60 DNS Resource Record not unique -125 DNS resource record not found -136 266 IPControl CLI and API Guide . Use this call to retrieve a resource record that is not bound to a particular device. Modify the returned structure as needed and pass the modified structure to ImportDomainResourceRecord.getDom ainResourceRec getDomainResourceRec This operation retrieves information about a DNS resource record from IPControl. No owner The OWNER section of the resource record. ImportDomainResourceRecord will perform an update instead of a create due to the presence of an ID element in the resource record structure. a WSDomainResourceRec structure is filled in with its information. No type The type of resource record. This call can be used in conjunction with the ImportDomainResourceRecord call to modify an existing DNS resource record. This structure is also used by the ImportDomainResourceRecord API call.wsdl that describes the getDomainResourceRec request and response messages. Yes classtype The value currently supported is IN. Request These are the request parameters: Param eter Nam e Description Required domainName The name of the domain Yes domainNameType The name of the domain type to which the domain belongs. Defaults to “Default”. Request and Response Messages Below is the portion of Gets. <wsdl:message name="getNetelementInterfaceRequest"> <wsdl:part name="neName" type="soapenc:string"/> <wsdl:part name="iName" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getNetelementInterfaceResponse"> <wsdl:part name="getNetelementInterfaceReturn" type="tns2:WSNetElementInterface"/> </wsdl:message> Response If the Network Element Interface is found.wsdl that describes the getNetElementInterface request and response messages. getNetelementInterface Request There are two parameters in the request. Modify the returned structure as needed and pass the modified structure to ImportNetElementInterface. Request and Response Messages Below is the portion of Gets. Use this call in conjunction with the ImportNetElementInterface call to modify an existing network element interface. a WSNetElementInterface structure is filled in with its information. This call returns a WSNetElementInterface data structure. ImportNetElementInterface updates the network element interface based on the presence of an ID element in the WSNetElementInterface structure. Yes iName The name of the interface Yes Return Codes Condition Return Code Network element not found -33 Interface not found -19 Application Program Interfaces (API) 267 . Param eter Nam e Description Required neName The name of the network element.getNetelementInterface getNetelementInterface There is one call to retrieve a network element interface: getNetElementInterface. This structure is also used by the ImportNetElementInterface API call. <wsdl:message name="getPrefixPoolByStartAddrResponse"> <wsdl:part name="getPrefixPoolByStartAddrReturn" type="tns2:WSPrefixPool"/> </wsdl:message> <wsdl:message name="getPrefixPoolByStartAddrRequest"> <wsdl:part name="addr" type="soapenc:string"/> </wsdl:message> <wsdl:message name="getPrefixPoolByNameResponse"> <wsdl:part name="getPrefixPoolByNameReturn" type="tns2:WSPrefixPool"/> </wsdl:message> <wsdl:message name="getPrefixPoolByNameRequest"> <wsdl:part name="name" type="soapenc:string"/> </wsdl:message> Response If the prefix pool is found. Param eter Nam e Description Required Addr The Start Address of the Prefix Pool Yes Return Codes If the prefix pool is not found. Modify the returned structure as needed and pass the modified structure to ImportPrefixPool. 268 IPControl CLI and API Guide . a WSPrefixPool structure is filled in with its information. getPrefixPoolByName Request There is one parameter in the request. Request and Response Messages Below is the portion of Gets. the call will fail with an error code of -262.getPrefixPool getPrefixPool There are two calls for retrieving information about a Prefix Pool: getPrefixPoolByName getPrefixPoolByStartAddr Both return a WSPrefixPool structure. This structure is also used by the ImportPrefixPool API call. Use either of the calls in conjunction with the ImportPrefixPool call to modify an existing Prefix Pool. Param eter Nam e Description Required Name The name of the Prefix Pool Yes getPrefixPoolByStartAddr Request There is one parameter in the request.wsdl that describes the Prefix Pool request and response messages. ImportPrefixPool will perform an update instead of a create due to the presence of an ID element in the prefix pool structure. For more information. -3 Invalid Parameter: Missing or Invalid parameters related to a particular call -4 Resource Not Found: Resource that service requires does not exist ArpDiscoverNetElement Overview The arpDiscoverNetElement API enables the web service client to issue an immediate Arp Discovery task to collect host information from a router’s ARP cache. Code Description -1 System Error: Serious error preventing the operation from continuing. and for querying the status of IPControl tasks. Request and Response Messages Below is the portion of TaskInvocation. <wsdl:message name="arpDiscoverNetElementResponse"> <wsdl:part name="arpDiscoverNetElementReturn" type="xsd:int"/> </wsdl:message> <wsdl:message name="arpDiscoverNetElementRequest"> <wsdl:part name="netelement" type="soapenc:string"/> <wsdl:part name="performNetHostAdd" type="xsd:boolean"/> <wsdl:part name="updateReclaim" type="xsd:boolean"/> <wsdl:part name="ignoreDuplicates" type="xsd:boolean"/> </wsdl:message> Response If the task is scheduled successfully. the negative integer returned in the response contains a code as described in the chapter introduction. You can see the complete WSDL at: http://localhost:8080/inc-ws/services/TaskInvocation?wsdl Return Codes The following codes are returned as negative integers from those services returning type int.ArpDiscoverNetElement Tasks Overview This section explains the web services available for issuing tasks to IPControl. Each of these services is available as an operation in the TaskInvocation web service. Application Program Interfaces (API) 269 . Pass this task number to the taskStatus service to obtain the status of that task. look for error messages in the web services log. If the task is not scheduled successfully.wsdl that describes the arpDiscoverNetElement request and response messages. such as failure to connect to the database. the web service returns the task number. -2 Access Denied: User failed security check. updateReclaim Set to true to update the last discovered counters for blocks and hosts defined within the network element. Pass this task number to the taskStatus service to obtain the status of that task. Parameters Below is the portion of TaskInvocation. <wsdl:message name="dhcpUtilizationResponse"> <wsdl:part name="dhcpUtilizationReturn" type="xsd:int" /> </wsdl:message> </wsdl:message><wsdl:message name="dhcpUtilizationRequest"> <wsdl:part name="adminId" type="soapenc:string" /> <wsdl:part name="password" type="soapenc:string" /> <wsdl:part name="elementName" type="soapenc:string" /> <wsdl:part name="ipAddress" type="soapenc:string" /> </wsdl:message> Response If the task is scheduled successfully. <wsdl:operation name="arpDiscoverNetElement" parameterOrder="netelement performNetHostAdd updateReclaim ignoreDuplicates"> <wsdl:input message="impl:arpDiscoverNetElementRequest" name="arpDiscoverNetElementRequest"/> <wsdl:output message="impl:arpDiscoverNetElementResp onse" name="arpDiscoverNetElementResponse"/> </wsdl:operation> Param eter name Description and accepted values netelement Name or IP Address of the Net Element to run ARP discover on. If the task is not scheduled successfully. the negative integer returned in the response contains a code as described in the chapter introduction.wsdl that describes the parameter structure passed to arpDiscoverNetElement.wsdl that describes the dhcpUtilization request and response messages. The individual parameters are described in the table that follows. DHCPUtilization Overview The dhcpUtilization API enables the web service client to issue an immediate DHCP Collection task to collect statistics on the utilization of a DHCP server.DHCPUtilization Request The parts passed as input from the client to the web service are described in the next section. ignoreDuplicates Set to true to ignore duplicate hostnames encountered while adding new hosts. performNetHostAdd Set to true to automatically add new hosts that are found during discovery. 270 IPControl CLI and API Guide . the web service returns the task number. Request and Response Messages Below is the portion of TaskInvocation. DHCPUtilization Request The parts passed as input from the client to the web service are described in the next section. Yes. The individual parameters are described in the table that follows. when IP Address or FQDN is not specified. Application Program Interfaces (API) 271 . when the elementName is not specified.wsdl that describes the parameter structure passed to dhcpUtilization. Yes. ipAddress IP Address or fully-qualified (FQDN) of the DHCP server for which IPControl will collect statistics. Parameters Below is the portion of TaskInvocation. <wsdl:operation name="dhcpUtilization" parameterOrder="adminId password elementName ipAddress"> <wsdl:input message="impl:dhcpUtilizationRequest" name="dhcpUtilizationRequest" /> <wsdl:output message="impl:dhcpUtilizationResponse" name="dhcpUtilizationResponse" /> </wsdl:operation> Part nam e Description and accepted values Required adminId IPControl administrator’s user id Yes password IPControl administrator’s password Yes elementName Name of the DHCP server for which IPControl will collect statistics. 272 IPControl CLI and API Guide .wsdl that describes the discoverNetElement request and response messages. the negative integer returned in the response contains a code as described in the chapter introduction. the positive integer returned by the web service corresponds to the task number. Request and Response Messages Below is the portion of TaskInvocation. when IP Address or FQDN is not specified.wsdl that describes the parameter structure passed to discoverNetElement. The individual parameters are described below. Parameters Below is the portion of TaskInvocation. Request The parts passed as input from the client to the web service are described in the next section. when the elementName is not specified.DiscoverNetElement DiscoverNetElement Overview The discoverNetElement API enables the web service client to issue an immediate Discover task to discover the interfaces bound to a network element already defined in IPControl. ipAddress IP Address or fully-qualified (FQDN) of the device to discover. That task number can then be passed to the TaskStatus service to obtain the status of that task. Yes. <wsdl:operation name="discoverNetElement" parameterOrder="adminId password elementName ipAddress"> <wsdl:input message="impl:discoverNetElementRequest" name="discoverNetElementRequest" /> <wsdl:output message="impl:discoverNetElementResponse" name="discoverNetElementResponse" /> </wsdl:operation> Part nam e Description and accepted values Required adminId IPControl administrator’s user ID Yes password IPControl administrator’s password Yes elementName Name of Network Element (device) to discover. If the task is not scheduled successfully. <wsdl:message name="discoverNetElementResponse"> <wsdl:part name="discoverNetElementReturn" type="xsd:int" /> </wsdl:message> <wsdl:message name="discoverNetElementRequest"> <wsdl:part name="adminId" type="soapenc:string" /> <wsdl:part name="password" type="soapenc:string" /> <wsdl:part name="elementName" type="soapenc:string" /> <wsdl:part name="ipAddress" type="soapenc:string" /> </wsdl:message> Response If the task is scheduled successfully. Yes. wsdl that describes the parameter structure passed to getTask .wsdl that describes the getTask request and response messages. Yes Application Program Interfaces (API) 273 . <wsdl:operation name="getTask" parameterOrder="taskId"> <wsdl:input message="impl:getTaskRequest" name="getTaskRequest" /> <wsdl:output message="impl:getTaskResponse" name="getTaskResponse"/> </wsdl:operation> Param eter name Description and accepted values Required taskId The task number to query. Parameters Below is the portion of TaskInvocation. The parameter is described in the table that follows. Request and Response Messages Below is the portion of TaskInvocation. <wsdl:message name="getTaskRequest"> <wsdl:part name="taskId" type="xsd:int" /> </wsdl:message> <wsdl:message name="getTaskResponse"> <wsdl:part name="getTaskReturn" type="impl:ArrayOf_soapenc_string" /> </wsdl:message> Response GetTask will return the status of the queried task as a string array with the following information: Elem ent Description 0 Task ID 1 Service 2 Scope 3 Status 4 Process start time Request The input from the client to the web service is described in the next section.GetTask GetTask Overview The getTask API enables the web service client to query the status of tasks and receive detailed information about those tasks. Yes 274 IPControl CLI and API Guide . Request and Response Messages Below is the portion of TaskInvocation.wsdl that describes the getTaskStatus request and response messages. Request The input from the client to the web service is described in the next section. <wsdl:operation name="getTaskStatus" parameterOrder="taskId"> <wsdl:input message="impl:getTaskStatusRequest" name="getTaskStatusRequest" /> <wsdl:output message="impl:getTaskStatusResponse" name="getTaskStatusResponse" /> </wsdl:operation> Part nam e Description and accepted values Required taskId The task number to query. described next in this section. <wsdl:message name="getTaskStatusResponse"> <wsdl:part name="getTaskStatusReturn" type="soapenc:string" /> </wsdl:message> <wsdl:message name="getTaskStatusRequest"> <wsdl:part name="taskId" type="xsd:int" /> </wsdl:message> Response GetTaskStatus returns the status of the queried task as one of the following strings: NOTSTARTED QUEUED INPROGRESS COMPLETE COMPLETEWITHERRORS ERROR For more detailed information about the task. use the getTask service.GetTaskStatus GetTaskStatus Overview The getTaskStatus API enables the web service client to query the status of tasks. The parameter is described below.wsdl that describes the parameter structure passed to getTaskStatus. Parameters Below is the portion of TaskInvocation. That task number can then be passed to the taskStatus service to obtain the status of that task. <wsdl:message name="globalNetElementSyncResponse"> <wsdl:part name="globalNetElementSyncReturn" type="xsd:int" /> </wsdl:message> <wsdl:message name="globalNetElementSyncRequest"> <wsdl:part name="adminId" type="soapenc:string" /> <wsdl:part name="password" type="soapenc:string" /> </wsdl:message> Response If the task is scheduled successfully.GlobalNetElem entSync GlobalNetElementSync Overview The globalNetElementSync API enables the web service client to issue an immediate Global Synchronization task for all network elements in IPControl that are flagged for inclusion in the Global Sync process.wsdl that describes the parameter structure passed to globalNetElementSync . the negative integer returned in the response contains a code as described in the chapter introduction. Parameters Below is the portion of TaskInvocation. the positive integer returned by the web service will correspond to the task number. The individual parameters are described below. Request The parts passed as input from the client to the web service are described in the next section. <wsdl:operation name="globalNetElementSync" parameterOrder="adminId password"> <wsdl:input message="impl:globalNetElementSyncRequest" name="globalNetElementSyncRequest" /> <wsdl:output message="impl:globalNetElementSyncResponse" name="globalNetElementSyncResponse" /> </wsdl:operation> Part nam e Description and accepted values Required adminId IPControl administrator’s user id Yes password IPControl administrator’s password Yes Application Program Interfaces (API) 275 . If the task is not scheduled successfully.wsdl that describes the globalNetElementSync request and response messages. Request and Response Messages Below is the portion of TaskInvocation. GlobalNetServiceSync GlobalNetServiceSync Overview The globalNetServiceSync API enables the web service client to issue an immediate Global Synchronization task for all network services in IPControl that are flagged for inclusion in the Global Sync process. Request and Response Messages Below is the portion of TaskInvocation.wsdl that describes the globalNetServiceSync request and response messages. <wsdl:message name="globalNetServiceSyncResponse"> <wsdl:part name="globalNetServiceSyncReturn" type="xsd:int" /> </wsdl:message <wsdl:message name="globalNetServicetSyncRequest"> <wsdl:part name="adminId" type="soapenc:string" /> <wsdl:part name="password" type="soapenc:string" /> </wsdl:message> Response If the task is scheduled successfully, the positive integer returned by the web service will correspond to the task number. That task number can then be passed to the taskStatus service to obtain the status of that task. If the task is not scheduled successfully, the negative integer returned in the response contains a code as described in the chapter introduction. Request The parts passed as input from the client to the web service are described in the next section. Parameters Below is the portion of TaskInvocation.wsdl that describes the parameter structure passed to globalNetServiceSync . The individual parameters are described below. <wsdl:operation name="globalNetServiceSync" parameterOrder="adminId password"> <wsdl:input message="impl:globalNetServiceSyncRequest" name="globalNetServiceSyncRequest" /> <wsdl:output message="impl:globalNetServiceSyncResponse" name="globalNetServiceSyncResponse" /> </wsdl:operation> Part nam e Description and accepted values Required adminId IPControl administrator’s user id Yes password IPControl administrator’s password Yes 276 IPControl CLI and API Guide GlobalRollup GlobalRollup Overview The globalRollup API enables the web service client to issue an immediate Global Rollup task to collect statistics and perform regression analysis. Request and Response Messages Below is the portion of TaskInvocation.wsdl that describes the globalRollup request and response messages. <wsdl:message name="globalRollupResponse"> <wsdl:part name="globalRollupReturn" type="xsd:int" /> </wsdl:message> <wsdl:message name="globalRollupRequest"> <wsdl:part name="adminId" type="soapenc:string" /> <wsdl:part name="password" type="soapenc:string" /> <wsdl:part name="periodLength" type="xsd:int" /> <wsdl:part name="_periodType" type="soapenc:string" /> </wsdl:message> Response If the task is scheduled successfully, the positive integer returned by the web service will correspond to the task number. That task number can then be passed to the taskStatus service to obtain the status of that task. If the task is not scheduled successfully, the negative integer returned in the response contains a code as described in the chapter introduction. Request The parts passed as input from the client to the web service are described in the next section. Parameters Below is the portion of TaskInvocation.wsdl that describes the parameter structure passed to globalRollup . The individual parameters are described in the table that follows. <wsdl:operation name="globalRollup" parameterOrder="adminId password periodLength _periodType"> <wsdl:input message="impl:globalRollupRequest" name="globalRollupRequest" /> <wsdl:output message="impl:globalRollupResponse" name="globalRollupResponse" /> </wsdl:operation> Part nam e Description and accepted values Required adminId IPControl administrator’s user id Yes password IPControl administrator’s password Yes periodLength The number of time periods to be included in the regression. If not specified, defaults to value set in System Policies. Yes _periodType The type of time period. Accepted values are: D (days), W (weeks), M (months), and Y (years). Yes Application Program Interfaces (API) 277 Overview Exports Overview This section explains the web services available for retrieving information from IPControl. Each of these services is available as an operation in the Exports web service. You can see the complete WSDL at: http://localhost:8080/inc-ws/services/Exports?wsdl Export Categories There are two categories of Export web services. The first category consists of legacy APIs that were available in the initial version of IPControl. The second category consists of a newer set of APIs that provide a more flexible request and response format. Legacy Web Services The legacy web service APIs are designed to accept one or more request parameters which define the filter used to export objects from the IPControl database. In addition, these legacy APIs return a string response which contains a list of objects. Each object’s fields a re commadelimited, and each object in the list is separated by a newline character. The legacy web service APIs are the following: ExportNetElementsAsCSV ExportAllNetElementsAsCSV ExportNetServicesAsCSV ExportAllNetServicesAsCSV Next Generation Web Services The new web service APIs are designed to accept a string request which contains a query defining the filter used to export objects from the IPControl database. These new APIs return a structure which represents the object being exported. The format of the structure is such that it can be directly used for the corresponding import web service. The new web service APIs are the following: ExportContainer ExportRootBlock ExportChildBlock ExportDevice ExportDeviceResourceRecord 278 IPControl CLI and API Guide ExportNetElementsAsCSV Legacy Web Services ExportNetElementsAsCSV Overview The exportNetElementsAsCSV API enables the web service client to issue a request to retrieve a list of Network Elements from IPControl. This service enables the client to filter the list of Network Elements retrieved. Request and Response Messages Below is the portion of Exports.wsdl that describes the exportNetElementsAsCSV request and response messages. <wsdl:message name="exportNetElementsAsCSVResponse"> <wsdl:part name="exportNetElementsAsCSVReturn" type="soapenc:string" /> </wsdl:message> <wsdl:message name="exportNetElementsAsCSVRequest"> <wsdl:part name="elementName" type="soapenc:string" /> <wsdl:part name="vendorName" type="soapenc:string" /> <wsdl:part name="modelDesc" type="soapenc:string" /> <wsdl:part name="ipaddr" type="soapenc:string" /> <wsdl:part name="globalsync" type="soapenc:string" /> <wsdl:part name="agentName" type="soapenc:string" /> <wsdl:part name="elementType" type="soapenc:string" /> </wsdl:message> Response The string that is returned contains the list of Network Elements matching the selection criteria specified in the request. Each Network Element description is separated by a new line character. The values within each Network Element description are separated by commas, and described in the table below. Fields that are not required may not always contain values. Fields H, I, J and K will not be exported, since these could contain sensitive information. The columns are preserved to maintain conformity with the ImportNetElement API. Col Field Description Required A Name The name of the Network Element. This can be any combination of letters and numbers. Yes B IP Address/FQDN The IP address or fully-qualified domain name (FQDN) of the Network Element. This is a valid IPv4 or IPv6 IP address, or a fully-qualified host name. Yes C Vendor The vendor of the Network Element. Vendor is predefined in IPControl. Yes when Model is specified. D Model The model name of the Network Element. Model is predefined in IPControl. Yes when Vendor is specified. E Type The type of Network Element. Accepted values are CMTS, Router, Switch, or VPN. Yes F Global Sync Whether or not to include this Network Element in the Global Sync process. Value is true or false. Yes Application Program Interfaces (API) 279 ExportNetElementsAsCSV Col Field Description Required G Agent Name The exact name of the IPControl Agent that is responsible for contacting this Network Service. Yes H Telnet user A user name used to telnet to this device. No I Telnet password A password used by the telnet user to telnet to this device. No J Enable password Password used to enter “enabled” or “privileged” mode on the device. No K Read community string The community string used by SNMP to read details from this network element. No L Interfaces A list of enabled interfaces. Multiple interfaces are specified by separating each interface with the ‘|’ character. No M V3 Username Required if using SNMP V3. No N V3 Authentication Protocol Either MD5 or SHA1. Leave blank or set to NONE if no authentication. No O V3 Authentication Password Required if field N is set to either MD5 or SHA1 No P V3 Privacy Protocol Only DES supported at this time. Leave blank or set to NONE if no privacy. No Q V3 Privacy Password Required if field P is set to DES. No R V3 Context Name SNMP V3 Context name, if needed. No S V3 Engine ID SNMP V3 Engine ID, if needed. No Request The parts passed as input from the client to the web service are described in the next section. They are used to filter the information retrieved from IPControl. None are required. To retrieve all Network Elements, use ExportAllNetElementsAsCSV. Parameters Below is the portion of Exports.wsdl that describes the parameter structure passed to exportNetElementsAsCSV . The individual parameters are described in the table that follows. Note that none of the parameters are required, since they are used as a filter for the information retrieved. <wsdl:operation name="exportNetElementsAsCSV" parameterOrder="elementName vendorName modelDesc ipaddr globalsync agentName elementType"> <wsdl:input message="impl:exportNetElementsAsCSVRequest" name="exportNetElementsAsCSVRequest" /> <wsdl:output message="impl:exportNetElementsAsCSVResponse" name="exportNetElementsAsCSVResponse" /> </wsdl:operation> Part nam e Description and accepted values elementName The name of the Network Element. vendorName The vendor of the Network Element. modelDesc The model name of the Network Element. ipAddress IP Address or fully-qualified (FQDN) of the Network Element. 280 IPControl CLI and API Guide ExportNetElementsAsCSV Part nam e Description and accepted values globalsync Whether or not to include this Network Element in the Global Synch process. Specify Y (yes) or N (no). agentName The exact name of the IPControl Agent that is responsible for contacting this Network Element. elementType The type of Network Element. Specify CMTS, Router, Switch or VPN. Application Program Interfaces (API) 281 ExportAllNetElementsAsCSV ExportAllNetElementsAsCSV Overview The exportAllNetElementsAsCSV API enables the web service client to issue a request to retrieve a list of all of the Network Elements from IPControl. To filter the request, use the exportNetElementsAsCSV service. Request and Response Messages Below is the portion of Exports.wsdl that describes the exportAllNetElementsAsCSV request and response messages. <wsdl:message name="exportAllNetElementsAsCSVResponse"> <wsdl:part name="exportAllNetElementsAsCSVReturn" type="soapenc:string" /> </wsdl:message> <wsdl:message name="exportAllNetElementsAsCSVRequest" /> Response The string that is returned contains the list of all of the Network Elements. See the Response section of ExportNetElementsAsCSV for format and details. Request There are no input parameters for this web service. Parameters Below is the portion of Exports.wsdl that describes the parameter structure passed to exportAllNetElementsAsCSV . <wsdl:operation name="exportAllNetElementsAsCSV"> <wsdl:input message="impl:exportAllNetElementsAsCSVRequest" name="exportAllNetElementsAsCSVRequest" /> <wsdl:output message="impl:exportAllNetElementsAsCSVResponse" name="exportAllNetElementsAsCSVResponse" /> </wsdl:operation > 282 IPControl CLI and API Guide This is a value already defined in IPControl. Fields H and I will not be exported. and described in the table below. since these could contain sensitive information. <wsdl:message name="exportNetServicesAsCSVResponse"> <wsdl:part name="exportNetServicesAsCSVReturn" type="soapenc:string" /> </wsdl:message> <wsdl:message name="exportNetServicesAsCSVRequest"> <wsdl:part name="serviceName" type="soapenc:string" /> <wsdl:part name="vendorName" type="soapenc:string" /> <wsdl:part name="containerName" type="soapenc:string" /> <wsdl:part name="ipaddr" type="soapenc:string" / > <wsdl:part name="globalsync" type="soapenc:string" /> <wsdl:part name="agentName" type="soapenc:string" /> <wsdl:part name="serviceType" type="soapenc:string" /> </wsdl:message> Response The string that is returned contains the list of Network Services matching the selection criteria specified in the request. Request and Response Messages Below is the portion of Exports. Col Field Accepted Values Required A Name The name of the Network Service. or a fully-qualified host name. The values within each Network Service description are separated by commas. Yes E Agent name The name of the IPControl Agent that is responsible for contacting this Network Service. INS DHCP or CNR DHCP. Yes H User name for The username used by the collection method (scp Yes Application Program Interfaces (API) 283 . The columns are preserved to maintain conformity with the ImportNetService API. This is always dhcp. Yes F Global Sync Whether or not this Network Service is included in the Global Sync process. Yes C Type The type of Network Service. Yes B IP Address/FQDN The IP address or fully-qualified domain name (FQDN) of the Network Service. for example. This can be any combination of letters and numbers.ExportNetServicesAsCSV ExportNetServicesAsCSV Overview The exportNetServicesAsCSV API enables the web service client to issue a request to retrieve a list of DHCP Network Services from IPControl. Values are scp or ftp. Values are true or false. This must be a valid IPv4 or IPv6 IP address. Each Network Service description is separated by a new line character.wsdl that describes the exportNetServicesAsCSV request and response messages. Yes G Collection Method The method by which the IPControl Agent collects data from the Network Service. This API enables the web service client to filter the list of Network Services retrieved. No D Product name The Network Service product name. Fields that are not required may not always contain values. No K Container(s) No longer used. L VendorInfo Vendor specific information for the product’s collection type. /opt/qip/dhcp/dhcpd. This is exported as “password”. Used in conjunction with the ‘User name for collection’. since they are used as a filter for the information retrieved. None are required. msft and isc.wsdl that describes the parameter structure passed to exportNetServicesAsCSV .conf |/opt/qip/dhcp/dhcp. Yes J Collection port The port number the collection method (scp or ftp) is listening on. Parameters Below is the portion of Exports. To retrieve all Network Services. The individual parameters are described in the table that follows.db or c:\qip\dhcp\dhcpd. the information includes the Path/Executable of NRCD command. Each item of information is specified in this single field by separating each field with the ‘|’ character. the NRCMD password and the Cluster Name.adc. For example.conf |c:\qip\dhcp\dhcp. They are used to filter the information retrieved from IPControl. Note that none of the parameters are required.db For collection type cnr. the NRCMD user id. <wsdl:operation name="exportNetServicesAsCSV" parameterOrder="serviceName vendorName containerName ipaddr globalsync agentName serviceType"> <wsdl:input message="impl:exportNetServicesAsCSVRequest" name="exportNetServicesAsCSVRequest" /> <wsdl:output message="impl:exportNetServicesAsCSVResponse" name="exportNetServicesAsCSVResponse" /> </wsdl:operation> 284 IPControl CLI and API Guide . /opt/cnr/bin/nrcmd|myuserid|mypass| cluster1 Request The parts passed as input from the client to the web service are described in the next section. This is exported as “username”. No For collection types qip. For example. use ExportAllNetServicesAsCSV. the information includes the DHCP Configuration file pathname and DHCP Active Lease file pathname. Required I Password for collection The password used by the collection method (scp or ftp) to log in to the remote server.ExportNetServicesAsCSV Col Field Accepted Values collection or ftp) to log in to the remote server. Application Program Interfaces (API) 285 . Specify Y (yes) or N (no).ExportNetServicesAsCSV Part nam e Description and accepted values serviceName The name of the Network Service. vendorName The Network Service product name. containerName The container the service is attached to. agentName The exact name of the IPControl Agent that is responsible for contacting this Network Service. globalsync Whether or not this Network Service is included in the Global Synch process. serviceType The type of Network Service. Specify dhcp. ipAddress IP Address or fully-qualified (FQDN) of the Network Service. See the Response section of ExportNetServicesAsCSV on page 283 for format and details. Parameters Below is the portion of Exports.wsdl that describes the parameter structure passed to exportAllNetServicesAsCSV.wsdl that describes the exportAllNetServicesAsCSV request and response messages. use the exportNetServicesAsCSV API.ExportAllNetServicesAsCSV ExportAllNetServicesAsCSV Overview The exportAllNetServicesAsCSV API enables the web service client to issue a request to retrieve a list of all of the DHCP Network Services from IPControl. <wsdl:message name="exportAllNetServicesAsCSVResponse"> <wsdl:part name="exportAllNetServicesAsCSVReturn" type="soapenc:string" /> </wsdl:message> <wsdl:message name="exportAllNetServicesAsCSVRequest" /> Response The string that is returned contains the list of all of the Network Services. Request There are no input parameters for this web service. Request and Response Messages Below is the portion of Exports. To filter the request. <wsdl:operation name="exportAllNetSevicesAsCSV"> <wsdl:input message="impl:exportAllNetSevicesAsCSVRequest" name="exportAllNetSevicesAsCSVRequest" /> <wsdl:output message="impl:exportAllNetSevicesAsCSVResponse" name="exportAllNetSevicesAsCSVResponse" /> </wsdl:operation> 286 IPControl CLI and API Guide . Selectors Next Generation Web Services Selectors The new web services APIs accept a single string parameter for the request. which is used to pass options to the service. to export the Device with a hostname of “mydevice”. “ends”. and return a WSContext object in the response. This is accomplished using the WSContext object. to export all Devices with a hostname beginning with “my”. Each new web service must be initialized by the client by calling the initialization method associated with the export web service. the request query string would be as follows: name begins ‘my’ The export filter can be further refined by combining additional selectors using the Boolean operators “and” and “or”. For example. This request string specifies a query which is used to filter the list of exported objects. the client will always perform at least two web service requests to export objects from IPControl. Paging The new web services APIs also support the concept of paging through the export results. the client must call initExportDevice first. Each new export web service supports a specific set of selectors. the request query string would be as follows: name begins ‘my’ and devicetype=’PC’ Use parentheses to apply specific precedence in expressions that utilize multiple Boolean operators. The query syntax consists of one or more selectors. For example. Some queries may result in thousands of exported objects. combined into a Boolean expression. the request query string would be as follows: name=’mydevice’ Selectors which are based on a text field can support the keywords “begins”. The export service initialization APIs take the query string as the request. the web services client should specify the starting point within the list of results. Options Some of the new web services APIs also support a second parameter. Please refer to each API definition on the following pages for the supported selector syntax. when exporting devices. Application Program Interfaces (API) 287 . it is not feasible to return all the results in a single response. For example. Therefore. Due to memory and network constraints. or “contains” to support wildcarding. The export services APIs themselves take the WSContext object as the request. Refer to the WSDL and the sections that follow for more information. and return an array of exported objects in the response. For example. followed by a call to exportDevice. to export all Devices with a hostname beginning with “my” and with a device type of “PC”. as well as the number of results to return. Therefore. and return an error. The session identifier is returned as part of the SOAP Header. configure your client to use the SimpleSessionHandler.apache.org/axis/session. WSContext Below is the portion of Exports. An example of the returned header follows. If you are using the Java Axis package to generate your web services client. or an error occurs. the parameter structure returned by the initExport* APIs. If not. This session identifier must be provided on all subsequent export calls. The element name is sessionID. The initialization call creates a session and returns a session identifier as part of the SOAP envelope.wsdl that describes WSContext. the export* calls cannot correlate with the init call. where the value of the sessionID is 12345678. the details of the session handling follow. The elements are described in the table that follows. The subsequent export* calls must include this element and value in the SOAP Header.apache. options Reserved query Reserved resultCount Reserved internalResultCount Reserved 288 IPControl CLI and API Guide .org/axis/session"> 12345678 </ns1:sessionID> </soapenv:Header> The response processing for the init* calls must capture this element and value. as described in the documentation. and passed to the export* APIs. Without this. <soapenv:Header> <ns1:sessionID soapenv:mustUnderstand="0" xmlns:ns1="http://xml.Sessions Sessions Initialization calls are linked to subsequent export calls by using sessions. The namespace is http://xml. <complexType name="WSContext"> <sequence> <element name="contextId" nillable="true" type="soapenc:string" /> <element name="contextType" nillable="true" type="soapenc:string" /> <element name="filter" nillable="true" type="soapenc:string" /> <element name="firstResultPos" type="xsd:int" /> <element name="maxResults" type="xsd:int" /> <element name="options" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="query" nillable="true" type="soapenc:string" /> <element name="resultCount" type="xsd:int" /> <element name="internalResultCount" type="xsd:int" /> </sequence> </complexType> Elem ent Description contextId Reserved contextType Reserved filter Reserved firstResultPos Reserved maxResults The number of result records to export. Initialization Before the exportRootBlock API is called.255’ udf The name and value of a UDF attached to the block(s) to be exported. container=’Exton’ block=’10.1’ ipaddressrange A range of IP addresses that span one or more blocks’ starting and ending addresses.0. UDF. Below is the portion of Exports. Supported selectors for exporting root blocks are defined in the following table.0. ipaddressrange=’10. <wsdl:message name="initExportRootBlockRequest"> <wsdl:part name="query" type="soapenc:string"/> </wsdl:message> <wsdl:message name="initExportRootBlockResponse"> <wsdl:part name="initExportRootBlockReturn" type="tns2:WSContext"/> </wsdl:message> Request The query string is passed as input from the client to the initExportRootBlock web service. This service enables the client to filter the list of Root Blocks retrieved.10.0/24’ blocktype The block type name of the block(s) to export. blocktype=’Private’ container The container name of the block(s) to be exported. name=’My Block’ name begins ‘My’ name ends ‘Block’ name contains ‘Bl’ block The CIDR notation of the block to export.0.0. The query string syntax is defined previously. The accepted format for CIDR notation is ‘block_address/block_size’. Partial names are supported using the begins/ends/contains qualifiers.0.ExportRootBlock ExportRootBlock Overview The exportRootBlock API enables the web service client to issue a request to retrieve a list of Root Blocks from IPControl.wsdl that describes the initExportRootBlock request and response messages.0. block=’10.*/24’ container begins ‘Ex’ container ends ‘ton’ container contains ‘xto’ ipaddress An IP address that falls within the start and ending addresses of a block to be exported. ipaddress=’10.0.0.myudf=’myudf_value’ Application Program Interfaces (API) 289 .0-10. Selector Description Exam ple name The name of the block to export. the web service client must call initExportRootBlock to initialize the API. as described below. This WSContext object must be included in each successive call to exportRootBlock. When this context is provided to a subsequent call to exportRootBlock. <wsdl:message name="exportRootBlockRequest"> <wsdl:part name="context" type="tns2:WSContext" /> </wsdl:message> <wsdl:message name="exportRootBlockResponse"> <wsdl:part name="exportRootBlockReturn" type="impl:ArrayOf_tns1_WSRootBlock"/> </wsdl:message> Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportRootBlock service defined above. <complexType name="WSRootBlock"> <sequence> <element name="RIR" nillable="true" type="soapenc:string" /> <element name="SWIPname" nillable="true" type="soapenc:string" /> <element name="allocationReason" nillable="true" type="soapenc:string" /> <element name="allocationReasonDescription" nillable="true" type="soapenc:string" /> <element name="allowOverlappingSpace" nillable="true" type="soapenc:string" /> <element name="blockAddr" nillable="true" type="soapenc:string" /> <element name="blockName" nillable="true" type="soapenc:string" /> <element name="blockSize" nillable="true" type="soapenc:strin g" /> <element name="blockType" nillable="true" type="soapenc:string" /> <element name="container" nillable="true" type="soapenc:string" /> <element name="createReverseDomains" nillable="true" type="soapenc:string" /> <element name="description" nillable="true" type="soapenc:string" /> <element name="domainType" nillable="true" type="soapenc:string" /> <element name="organizationId" nillable="true" type="soapenc:string" /> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string" /> </sequence> 290 IPControl CLI and API Guide . However. Service Invocation The portion of Exports. This WSContext has the maxResults field set to a default value of 100. Response The result returned from the exportRootBlock service is an array of WSRootBlock objects matching the selection criteria specified in the query filter. the number of exported blocks is limited to the first 100 that match the criteria in the given query filter. the array of structures returned by exportRootBlock. the value specified by the client cannot exceed 100. The WSRootBlocks can then be modified and/or imported using the importRootBlock API. WSRootBlock Below is the portion of Exports.wsdl that describes the exportRootBlock request and response messages is shown below.ExportRootBlock Response The response from the initExportRootBlock web service is a WSContext object defined previously.wsdl that describes WSRootBlock. The web service client may change the maxResults attribute of the WSContext before any call to the exportRootBlock service to modify the size of the resultant WSRootBlock object array. The format of the WSRootBlock matches that defined by the importRootBlock. The elements are described in the table that follows. blockName A name for the block. defaults to false. domainType The domain type of the reverse domain. SWIPname SWIP/Net name for the block. a block type of Any is assumed. blockAddr The starting address for the block. If not specified. Accepted values are true or false. where the name is the UDF name and the value is the desired value. 24 for a 255. blockType The Block Type of the block. State=PA. allocationReason The name of a pre-existing Allocation Reason. organizationId The organization id for the Regional Internet Registry.0 network). for example. description A description of the block. If not specified. allocationReasonDescription A description of the reason for the allocation.. allowOverlappingSpace Whether or not to allow duplicate (overlapping) address space in this block. Application Program Interfaces (API) 291 . Defaults to system supplied name of Address space/Block size. the valid values are on and off. userDefinedFields A string array containing one or more name=value pairs.ExportRootBlock </complexType> Elem ent Accepted Values RIR The Regional Internet Registry this space was obtained from. If the UDF type is Checkbox.g.255. container The name of the container holding the block. blockSize The size of the block in short-notation (e.255. createReverseDomains Whether or not to automatically create reverse DNS domain(s) for this block. 0/23^container=North’ parentName=’172.*/24’ container begins ‘Ex’ container ends ‘ton’ container contains ‘xto’ parentBlock The name of the parent block of the block(s) to be exported. The portion of Exports.0. Initialization Before the exportChildBlock API is called.0.wsdl that describes the initExportChildBlock request and response messages is shown below.0. Supported selectors for exporting child blocks are defined in the following table.0. The special ^container= declarative allows the container name to be specified.0/24’ blocktype The block type name of the block(s) to export. Partial names are supported using the begins/ends/contains qualifiers. This service enables the client to filter the list of Child Blocks retrieved. This can be fully qualified or not. In addition.0/23^container= /InControl/Canada/North’ . name=’My Block’ name begins ‘My’ name ends ‘Block’ name contains ‘Bl’ block The CIDR notation of the block to export.16.0/23’ parentName=’172. container=’Exton’ block=’10. The query string syntax is defined previously.16.16. the initExportChildBlock service accepts a Boolean flag that specifies if the free blocks maintained by IPControl should be included in the export. 292 IPControl CLI and API Guide parentName=’172. blocktype=’Private’ container The container name of the block(s) to be exported.0. block=’10. The accepted format for CIDR notation is ‘block_address/block_size’. <wsdl:message name="initExportChildBlockRequest"> <wsdl:part name="query" type="soapenc:string"/> <wsdl:part name="includeFreeBlocks" type="xsd:boolean"/> </wsdl:message> <wsdl:message name="initExportChildBlockResponse"> <wsdl:part name="initExportChildBlockReturn" type="tns2:WSContext"/> </wsdl:message> Request The query string is passed as input from the client to the initExportChildBlock web service.0. Selector Description Exam ple name The name of the block to export.ExportChildBlock ExportChildBlock Overview The exportChildBlock API enables the web service client to issue a request to retrieve a list of Child Blocks from IPControl. the web service client must call initExportChildBlock to initialize the API. Application Program Interfaces (API) 293 .1’ ipaddressrange A range of IP addresses that span one or more blocks’ starting and ending addresses. ipaddress=’10. recursive=true status The status of the block(s) to be exported.10. and must be included in each successive call to exportChildBlock. When this context is provided to a subsequent call to exportChildBlock.0.0. Useful in order to eliminate ambiguity by specifying the container name. UDF. status=aggregate interface The name of an interface to which the block is attached. as described below. Valid options are {free. and has the maxResults field set to a default value of 100.0.255’ udf The name and value of a UDF attached to the block(s) to be exported. When set to true. <wsdl:message name="exportChildBlockRequest"> <wsdl:part name="context" type="tns2:WSContext" /> </wsdl:message> <wsdl:message name="exportChildBlockResponse"> <wsdl:part name="exportChildBlockReturn" type="impl:ArrayOf_tns1_WSChildSubnetBlock"/> </wsdl:message> Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportChildBlock service defined above. However. subnet. aggregate. fullyassigned}. the value specified by the client cannot exceed 100.wsdl that describes the exportChildBlock request and response messages. The web service client may change this maxResults attribute of the WSContext before any call to the exportChildBlock service to modify the size of the resultant WSChildBlock object array.0. all child blocks of the specified parent name recursively will be exported. ipaddressrange=’10. Specifies the name of the parent block’s container.0. the number of exported blocks is limited to the first 100 that match the criteria in the given query filter. parentContainer=’North’ recursive Only appied when paretnBlock is supplied.0-10. reserved. interface=’eth0’ ipaddress An IP address that falls within the start and ending addresses of a block to be exported. Service Invocation Below is the portion of Exports.ExportChildBlock Selector Description Exam ple Parent Container Only applied when parentBlock is supplied. fully qualified or not.myudf=’myudf_value’ parentContainer=’/InControl/Canada/North’ Response The response from the initExportChildBlock web service is a WSContext object defined previously. 294 IPControl CLI and API Guide . <complexType name="WSChildSubnetBlock"> <sequence> <element name="childBlock" nillable="true" type="tns1:WSChildBlock"/> <element name="subnetPolicy" nillable="true" type="tns1:WSSubnetPolicy"/> </sequence> </complexType> Elem ent Description and accepted values childBlock The WSChildBlock substructure (see below) subnetPolicy The WSSubnetPolicy substructure (see below) WSChildBlock Below is the portion of Exports. The WSChildSubnetBlock structure consists of two substructures ( WSChildBlock and WSSubnetPolicy) which can then be modified and/or imported using the importChildBlock API. allocationReasonDescription A description of the reason for the allocation.wsdl that describes WSChildBlock.ExportChildBlock Response The result returned from the exportChildBlock service is an array of WSChildSubnetBlock objects matching the selection criteria specified in the query filter. the first parameter structure passed to importChildBlock. WSChildSubnetBlock Below is the portion of Exports.wsdl that describes WSChildSubnetBlock. The format of the WSChildBlock and the WSSubnetPolicy match that defined by the importChildBlock. The elements are described in the table that follows. <complexType name="WSChildBlock"> <sequence> <element name="SWIPname" nillable="true" type="soapenc:string" /> <element name="allocationReason" nillable="true" type="soapenc:string" /> <element name="allocationReasonDescription" nillable="true" type=" soapenc:string" /> <element name="allocationTemplate" nillable="true" type="soapenc:string" /> <element name="blockAddr" nillable="true" type="soapenc:string" /> <element name="blockName" nillable="true" type="soapenc:string" /> <element name="blockSize" nillable="true" type="soapenc:string" /> <element name="blockStatus" nillable="true" type="soapenc:string" /> <element name="blockType" nillable="true" type="soapenc:string" /> <element name="container" nillable="true" type="soapenc:string" /> <element name="createReverseDomains" nillable="true" type="soapenc:string" /> <element name="description" nillable="true" type="soapenc:string" /> <element name="domainType" nillable="true" type="soapenc:string" /> <element name="excludeFromDiscovery" nillable="true" type="soapenc:string"/> <element name="interfaceAddress" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="interfaceName" nillable="true" type="soapenc:string" /> <element name="ipv6" type="xsd:boolean"/> <element name="primarySubnet" type="xsd:boolean"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string" /> </sequence> </complexType> Elem ent Description and accepted values SWIPname SWIP name for this block allocationReason The name of a pre-existing Allocation Reason. WSSubnetPolicy The portion of Exports. If not specified. createReverseDomains Whether or not to automatically create reverse DNS domain(s) for this block. excludeFromDiscovery True when this subnet excluded from Host Discovery tasks. defaults to false. interfaceName If this block is in a device container. domainType The domain type of the reverse DNS domain. blockName The name of the block. FullyAssigned. Aggregate. interfaceAddress The address(es) of the interface IP address.wsdl that describes WSSubnetPolicy. blockType The Block Type for the block. userDefinedFields A string array containing one or more name=value pairs. the second parameter structure passed to ImportChildBlock is shown below. The elements are described in the table that follows. Reserved. container The name of the container holding the block. ipv6 True if this is an IPV6 block. Application Program Interfaces (API) 295 .255. Accepted values are true or false.ExportChildBlock Elem ent Description and accepted values allocationTemplate Reserved blockAddr The starting address of the block. DHCPPolicySet The name of a previously defined DHCP policy set. primarySubnet True if this is a primary subnet. the name of the interface to which it’s attached. description The description of the block. 24 for a 255.255.. blockStatus The current status of the block. blockSize The size of the block in short-notation (e. State=PA. for example. Possible values are: Deployed.g. where the name is the UDF name and the value is the desired value. <complexType name="WSSubnetPolicy"> <sequence> <element name="DHCPOptionsSet" nillable="true" type="soapenc:string" /> <element name="DHCPPolicySet" nillable="true" type="soapenc:string" /> <element name="DNSServers" nillable="true" type="impl:ArrayOf_soapenc_string" /> <element name="defaultGateway" nillable="true" type="soapenc:string" /> <element name="failoverDHCPServer" nillable="true" type="soapenc:string" /> <element name="forwardDomainTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="forwardDomains" nillable="true" type="impl:ArrayOf_soapenc_string" /> <element name="networkLinks" nillable="true" type="soapenc:string"/> <element name="primaryDHCPServer" nillable="true" type=" soapenc:string" /> <element name="primaryWINSServer" nillable="true" type=" soapenc:string" /> <element name="reverseDomainTypes" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="reverseDomains" nillable="true" type="impl:ArrayOf_ soapenc_string" /> </sequence> </complexType> Elem ent Description and accepted values DHCPOptionsSet The name of a previously defined DHCP Options set.0 network). ExportChildBlock Elem ent Description and accepted values DNSServers The name of previously defined DNS servers to be sent as an IP address to the client. 296 IPControl CLI and API Guide . networkLinks Reserved primaryDHCPServer The name of the DHCP server that will act as primary for this subnet. Only required for non-default domain types. failoverDHCPServer The name of the DHCP server that will act as failover for this subnet. defaultGateway The default gateway that DHCP clients on this subnet will use. reverseDomainTypes The domain types corresponding to the domains listed in reverseDomains. Only required for non-default domain types. This cannot be the same as the primary DHCP server. This service is used by the ExportChildBlock CLI to create the header line used when exporting with the expanded format option. Response The result returned from the initExportChildBlockUDFTags service is an array of strings. optionally. call the initExportChildBlockUDFTags API. <wsdl:message name="initExportChildBlockUDFTagsRequest"> <wsdl:part name="context" type="tns2:WSContext"/> </wsdl:message> <wsdl:message name="initExportChildBlockUDFTagsResponse"> <wsdl:part name="initExportChildBlockUDFTagsReturn" type="impl:ArrayOf_soapenc_string"/> </wsdl:message> Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportChildBlock service defined above. These are the field names/tags of the user defined fields defined for the blocks that will be returned on subsequent calls to the exportChildBlock service. forwardDomainTypes The domain types corresponding to the domains listed in forwardDomains.wsdl that describes the initExportChildBlockUDFTags request and response messages is shown below. primaryWINSServer The IP address of the Microsoft WINS server for clients in this subnet. reverseDomains The reverse domain names that will available to the user when adding an IP address to the system. the web service client can. The portion of Exports. Optional Service After the initExportChildBlock API is called to initialize the API. Accepted value is an IP address. forwardDomains The forward domain names that will available to the user when adding an IP address to the system. The first forward domain in the list will be used when there is a domain name DHCP option. order contains ’irs’ The options array is used to pass additional option information to the service.wsdl that describes the initExportContainer request and response messages is shown below. Name=’west. <wsdl:message name="initExportContainerRequest"> <wsdl:part name="query" type="soapenc:string"/> <wsdl:part name="options" type="impl:ArrayOf_soapenc_string"/> </wsdl:message> <wsdl:message name="initExportContainerResponse"> <wsdl:part name="initExportContainerReturn" type="tns2:WSContext"/> </wsdl:message> Request The query string is passed as input from the client to the initExportContainer web service. The portion of Exports. Name ends ‘est’ Name begins ‘wes’ Name contains ‘es’ User Defined Fields UDF. for example: IPControl/Texas/Dallas Response The response from the initExportContainer web service is a WSContext object defined previously and must be included in each successive call to exportContainer.<fieldname>=’<fieldvalue>’ UDF. Application Program Interfaces (API) 297 .order ends ’rst’ UDF. The valid options for ExportContainer are described in the following table: Option Description and accepted values ParentContainerFullPath When this option is specified. The query string syntax is defined previously. the service populates the parent container field using the long format.ExportContainer ExportContainer Overview The exportContainer API enables the web service client to issue a request to retrieve a list of Containers from IPControl. This service enables the client to filter the list of Containers retrieved. as described below.order=’first’ UDF.order begins ’fir’ Exports container by user defined field name and value. Selector Description Exam ple Name Exports container by container name. Usage UDF. Supported selectors for exporting devices are defined in the following table. Initialization Before the exportContainer API is called. the web service client must call initExportContainer to initialize the API. 298 IPControl CLI and API Guide . the number of exported containers is limited to the first 100 that match the criteria in the given query filter. The WSContainer can then be modified and/or imported using the importContainer API. Response The result returned from the exportContainer service is an array of WSContainer objects matching the selection criteria specified in the query filter. the value specified by the client cannot exceed 100.wsdl that describes the exportContainer request and response messages is shown below. The WSContainer object is described in the ImportContainer API section on page 204. However.ExportContainer Service Invocation The portion of Exports. The web service client may change this maxResults attribute of the WSContext before any call to the exportContainer service to modify the size of the resultant WSContainer object array. <wsdl:message name="exportContainerRequest"> <wsdl:part name="context" type="tns1:WSContext"/> </wsdl:message> <wsdl:message name="exportContainerResponse"> <wsdl:part name="exportContainerReturn" type="impl:ArrayOf_tns2_WSContainer"/> </wsdl:message> Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportContainer service defined above. This WSContext has the maxResults field set to a default value of 100. When this context is provided to a subsequent call to exportContainer. Container=’Exton’. The portion of Exports. In addition. Name ends ‘ost’ Name begins ‘hos’ Name contains ‘os’ Container Exports device by Container name. IPAddressRange=10.wsdl that describes the initExportDevice request and response messages is shown following.0. Exports device by IP Address range. Container ends ‘ton’ Container begins ‘Ext Container contains ‘xto’ IP Address Exports device by IP Address. Name=’host.1 Application Program Interfaces (API) 299 . use IPAddressRange. the initExportDevice service accepts the options array. The query string syntax is defined previously.0. Name.0. <wsdl:message name="initExportDeviceRequest"> <wsdl:part name="filter" type="soapenc:string"/> <wsdl:part name="options" type="impl:ArrayOf_s oapenc_string"/> </wsdl:message> <wsdl:message name="initExportDeviceResponse"> <wsdl:part name="initExportDeviceReturn" type="tns2:WSContext"/> </wsdl:message> Request The query string is passed as input from the client to the initExportDevice web service.1 Note . described following the selectors table.ExportDevice ExportDevice Overview The exportDevice API enables the web service client to issue a request to retrieve a list of Devices from IPControl.0. This service enables the client to filter the list of Devices retrieved.1-11. or multiple IPAddress (separated by Or) Selector type filters.0. Supported selectors for exporting devices are defined in the following table. unless the desired result is to export the device with only the IP Address specified in the Selector filter. Instead. Initialization Before the exportDevice API is called. IPAddress=10. the web service client must call initExportDevice to initialize the API. Selector Description Exam ple Name Exports device by hostname.0. this filter should not be used on a IP Address Range multi-homed device. Virtual=1 (for true) Virtual=0 (for false) The options array is used to pass additional option information to the service.’ Domain contains ’s.order=’first’ UDF. Domain=’ins.order contains ’irs’ Address Type Exports device by address type. Usage UDF.order begins ’fir’ UDF.ExportDevice Selector Description Exam ple Device type Exports device by Device type.0’ Block ends ‘.0.0/24’ Block contains ’.0.0. Block=’10. DeviceType=’Router’ DeviceType ends ‘uter’ DeviceType begins ’Rou’ DeviceType contains ’out’ Domain Exports device by Domain name.com.com.0. Specify the numeric value as follows: addrType=4 (Static) 1 : Dynamic DHCP 2 : Automatic DHCP 3 : Manual DHCP 4 : Static 5 : Reserved 6 : Dynamic NA DHCPv6 7 : Automatic NA DHCPv6 8 : Manual NA DHCPv6 9 : Dynamic TA DHCPv6 10 : Automatic TA DHCPv6 11 : Manual TA DHCPv6 12 : Dyanmic PD DHCPv6 13 : Automatic PD DHCPv6 14 : Interface Virtual Exports device by virtual flag.0. This flag is ignored if a Container Selector is not included.0’ Block Type Exports device by Block type.0/24’ Block begins ’10. The valid options for ExportDevice are described in the following table: Option Description and accepted values recurseContainerHierarchy When this option is specified. the service recursively exports all devices within all child containers specified within the Container Selector filter. devices will be exported when an associated IP address is virtual. 300 IPControl CLI and API Guide .<fieldname>=’<fieldvalue>’ UDF. When true is indicated.’ Domain begins ’ins.order ends ’rst’ UDF.c’ Domain ends ’. BlockType=’Any’ BlockType begins ’An’ BlockType ends ’ny’ BlockType contains ’n’ User Defined Fields Exports device by user defined field name and value.com’ Block Exports device by Block name. wsdl that describes the exportDevice request and response messages is shown following. the value specified by the client cannot exceed 100. The elements are described in the table that follows. WSDevice Below is the portion of Exports. that match the criteria in the given query filter. as described below. Service Invocation The portion of Exports. The format of the WSDevice matches that defined by the importDevice. When this context is provided to a subsequent call to exportDevice. <wsdl:message name="exportDeviceRequest"> <wsdl:part name="context" type="tns2:WSContext" /> </wsdl:message> <wsdl:message name="exportDeviceResponse"> <wsdl:part name="exportDeviceReturn" type="impl:ArrayOf_tns2_WSDevice"/> </wsdl:message> Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportDevice service defined aboveand has the maxResults field set to a default value of 100. Paging A device in IPControl is normalized within the database and thus may be represented by more than a single row in multiple tables. always guarantee the number of results to be the max results value or less.wsdl that describes WSDevice. however. the array of structures returned by exportDevice. Response The result returned from the exportDevice service is an array of WSDevice objects matching the selection criteria specified in the query filter.ExportDevice Response The response from the initExportDevice web service is a WSContext object defined previously and must be included in each successive call to exportDevice. Because of this and for performance. <complexType <sequence> <element <element <element <element <element <element name="WSDevice"> name="MACAddress" nillable="true" type="soapenc:st ring"/> name="addressType" nillable="true" type="soapenc:string"/> name="aliases" nillable="true" type="impl:ArrayOf_soapenc_string"/> name="container" nillable="true" type="soapenc:string"/> name="description" nillable="true" type="soapenc:string"/> name="deviceType" nillable="true" type="soapenc:string"/> Application Program Interfaces (API) 301 . The WSDevices can then be modified and/or imported using the importDevice API. the number of exported blocks is limited to the first 100 or less (see Paging). It will. However. The web service client may change this maxResults attribute of the WSContext before any call to the exportDevice service to modify the size of the resultant WSDevice object array. the exportDevice cannot guarantee that the number of WSDevice objects returned in any single execution of the service will be equal to the max results set on the WSContext object. The alias may be fully qualified (contains a trailing dot). and Automatic TA DHCPv6 Aliases A string array containing the alias or list of aliases for this hostname. domainName Domain name already defined to IPControl domainType Domain type already defined to IPControl. DEPRECATED: This is now returned in the WSInterface structure for all devices. the “Default” domain type will be used. a CNAME record is created. or not. deviceType The name of a device type configured in IPControl. everything that is after the first qualifier is interpreted as a domain name. Dynamic DHCP. description A description of the device. you must also specify resourceRecordFlag as true. If not specified.ExportDevice <element name="domainName" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="duid" nillable="true" type="soapenc:string"/> <element name="dupWarning" nillable="true" type="soapenc:string"/> <element name="hostname" nillable="true" type="soapenc:string"/> <element name="hwType" nillable="true" type="soapenc:string"/> <element name="ipAddress" nillable="true" type="soapenc:string"/> <element name="resourceRecordFlag" nillable="true" type="soapenc:string"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string "/> <element maxOccurs="unbounded" name="interfaces" nillable="true" type="tns2:WSInterface"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="excludeFromDiscovery" nillabl e="true" type="soapenc:string"/ </sequence> </complexType> <complexType name="WSInterface"> <sequence> <element name="addressType" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="container" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="excludeFromDiscovery" nillable="true" type="soapenc:string"/> <element name="hwType" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="ipAddress" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="macAddress" nillable="true" type="soapenc:string"/> <element name="name" nillable="true" type="soapenc:string"/> <element name="sequence" nillable="true" type="soapenc:int"/> <element name="virtual" nillable="true" type="impl:ArrayOf_soapenc_boolean"/> </sequence> </complexType> Elem ent Accepted Values MACAddress The hardware MAC address of the device. 302 IPControl CLI and API Guide . defaults to false. container The name of the container that contains the device. Automatic DHCP. Automatic NA DHCPv6. Reserved. the CNAME record will be created in the same domain as the device. When you specify an alias. addressType The address type of this device. To use this element. duid DHCP Unique Identifier dupWarning If the administrator policy of the user indicates “Warn” for the “Allow Duplicate Hostnames Checking” option. If not specified. Accepted values are: Static. Accepted values are true or false. the warning will be ignored and the device added with the duplicate hostname when this field is true. Manual DHCP. When not fully qualified. Dynamic TA DHCPv6. Dynamic NA DHCPv6. When fully qualified. Each element in the array corresponds to one interface for a multi-homed device. DEPRECATED: This is now returned in the WSInterface structure for all devices.ipAddress . or the single interface for a singlehomed device.excludeFromDiscovery .macAddress . . optionally.sequence: reserved . MACAddress must also be specified.virtual: reserved id Internal id. When hwtype is specified. Accepted values are true or false. userDefinedFields A string array containing one or more name=value pairs. for example. Except where noted. hwtype Specify Ethernet or Token Ring.name: Interface Name . ipAddress The IP Address of the device. Optional Service After the initExportDevice API is called to initialize the API.hwType . If the UDF type is Checkbox. defaults to false. call the initExportDeviceUDFTags API. If not specified. provide this on a modify request excludeFromDiscovery Flag indicating if this device should be included in Host Discovery tasks. their value is the same as in the WSDevice structure. The fields in the WSInterface structure are listed below. DEPRECATED: This is now returned in the WSInterface structure for all devices.ExportDevice Elem ent Accepted Values hostname Valid host name or APPLYNAMINGPOLICY.id: The internal ID. <wsdl:message name="initExportDeviceUDFTagsRequest"> <wsdl:part name="context" type="tns2:WSContext"/> </wsdl:message> <wsdl:message name="initExportDeviceUDFTagsResponse"> <wsdl:part name="initExportDeviceUDFTagsReturn" type="impl:ArrayOf_soapenc_string"/> </wsdl:message> Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportDevice service defined above. provide this on a modify request .wsdl that describes the initExportDeviceUDFTags request and response messages is shown below.addressType . the valid values are on and off.container: reserved . Application Program Interfaces (API) 303 . If not specified as true. the web service client can. This service is used by the ExportDevice CLI to create the header line used when exporting with the expanded format option. The portion of Exports. Interfaces An array of WSInterface structures. defaults to false. resourceRecordFlag Whether or not to add resource records for this device. where the name is the UDF name and the value is the desired value. DEPRECATED: This is now returned in the WSInterface structure for all devices. State=PA. 304 IPControl CLI and API Guide . These are the field names/tags of the user defined fields defined for the devices that will be returned on subsequent calls to the exportDevice service.ExportDevice Response The result returned from the initExportDeviceUDFTags service is an array of strings. The portion of Exports. The query string syntax is defined previously. Container ends ‘ton’ Container begins ‘Ext Container contains ‘xto’ IP Address Select device by IP Address.ExportDeviceResourceRecord ExportDeviceResourceRecord Overview The exportDeviceResourceRecord API enables the web service client to issue a request to retrieve a list of resource records for a device or list of devices from IPControl.0. Selector Description Exam ple Name Select device by hostname. use IPAddressRange.0. the initExportDeviceResourceRec service accepts an option that specifies that recursively all devices within all child containers specified within the Container Selector filter should be selected.1-11.0.1 Note . unless the desired result is to export the device with only the IP Address specified in the Selector filter.0. Name ends ‘ost’ Name begins ‘hos’ Name contains ‘os’ Container Select device by Container name.wsdl that describes the initExportDeviceResourceRec request and response messages is shown following. <wsdl:message name="initExportDeviceResourceRecRequest"> <wsdl:part name="filter" type="soapenc:string"/> <wsdl:part name="options" type="impl:ArrayOf_soapenc_string"/> </wsdl:message> <wsdl:message name="initExportDeviceResourceRecResponse"> <wsdl:part name="initExportDeviceResourceRecReturn" type="tns2:WSContext"/> </wsdl:message> Request The query string is passed as input from the client to the initExportDeviceResourceRec web service in the filter parameter. or multiple IPAddress (separated by Or) Selector type filters. Container=’Exton’. Name=’host. this filter should not be used on a multi-homed device. Instead.1 Application Program Interfaces (API) 305 . Initialization Before the exportDeviceResourceRecord API is called. Specify the option parameter as recurseContainerHierarchy. IPAddressRange=10.0. In addition. IP Address Range Select device by IP Address range. the web service client must call initExportDeviceResourceRec to initialize the API. This service enables the client to filter the list of resource records retrieved by device. Name. IPAddress=10.0. Supported selectors for exporting device resource records by device are defined in the following table. 0/24’ Block begins ’10.order contains ’irs’ Response The response from the initExportDeviceResourceRec web service is a WSContext object defined previously and must be included in each successive call to exportDeviceResourceRec.’ Domain begins ’ins. Block=’10.0/24’ Block contains ’.0.ExportDeviceResourceRecord Selector Description Exam ple Device type Select device by Device type.<fieldname>=’<fieldvalue>’ UDF. DomainType=’Internal’ DomainType begins ‘abc’ DomainType ends ‘xyz’ Domain Type contains ‘lmnop’ Block Select device by Block name. as described below.0’ Block ends ‘.c’ Domain ends ’.order begins ’fir’ UDF.’ Domain contains ’s.order=’first’ UDF.com’ Domain Type Select device by domain type. <wsdl:message name="exportDeviceResourceRecRequest"> <wsdl:part name="context" type="tns2:WSContext" /> </wsdl:message> <wsdl:message name="exportDeviceResourceRecResponse"> <wsdl:part name="exportDeviceResourceRecReturn" type="impl:ArrayOf_tns2_WSDeviceResourceRec"/> </wsdl:message> 306 IPControl CLI and API Guide .0’ Block Type Select device by Block type.order ends ’rst’ UDF. Service Invocation The portion of Exports. Domain=’ins.com.0.com.0.0.wsdl that describes the exportDeviceResourceRec request and response messages is shown following. DeviceType=’Router’ DeviceType ends ‘uter’ DeviceType begins ’Rou’ DeviceType contains ’out’ Domain Select device by Domain name. Usage UDF. BlockType=’Any’ BlockType begins ’An’ BlockType ends ’ny’ BlockType contains ’n’ User Defined Fields Select device by user defined field name and value.0. When this context is provided to a subsequent call to exportDeviceResourceRec. however. the value specified by the client cannot exceed 5000. or less (see Paging). The format of the WSDeviceResourceRec matches that defined by the importDeviceResourceRecord.ExportDeviceResourceRecord Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportDeviceRec service defined above and has the maxResults field set to a default value of 5000. the exportDeviceResourceRec cannot guarantee that the number of WSDeviceResourceRec objects returned in any single execution of the service will be equal to the max results set on the WSContext object. Response The result returned from the exportDeviceResourceRec service is an array of WSDeviceResourceRec objects matching the selection criteria specified in the query filter. WSDeviceResourceRec The portion of Exports. The elements are described in the table that follows. the number of exported resource records is limited to the first 5000 devices. Paging A device in IPControl is normalized within the database and thus may be represented by more than a single row in multiple tables.wsdl that describes WSDeviceResourceRec. Because of this and for performance. always guarantee the number of results to be the max results value or less. that match the criteria in the given query filter. The web service client may change this maxResults attribute of the WSContext before any call to the exportDeviceResourceRec service to modify the size of the resultant WSDeviceResourceRec object array. It will. The WSDeviceResourceRecs can then be modified and/or imported using the importDeviceResourceRecord API. <complexType name="WSDeviceResourceRec"> <sequence> <element name="TTL" nillable="true" type="soapenc:string"/> <element name="comment" nillable="true" type="soapenc:string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="data" nillable="true" type="soapenc:string"/> <element name="domain" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="hostname" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="ipAddress" nillable="true" type="soapenc:string"/> <element name="owner" nillable="true" type="soapenc:string"/> <element name="resourceRecClass" nillable="true" type="soapenc:string"/> <element name="resourceRecType" nillable="true" type="soapenc:string"/> </sequence> </complexType> Application Program Interfaces (API) 307 . the array of structures returned by exportDeviceResourceRec is shown following. However. Defaults to “IN”. domain Domain name where resource records are to be added. The format is dependent on the type specified above. resourceRecClass The Class of the Resource Record. resourceRecordType The Type of the resource Record. data The data portion of the resource record. ipAddress The IP Address of the Device. owner The owner field of the resource record. hostname The device host name. 308 IPControl CLI and API Guide . If not specified. comment Comment text associated with the resource record. domainType Domain type already defined to IPControl.ExportDeviceResourceRecord Elem ent Accepted Values container The name of the container that holds the device. the “Default” domain type will be used. This is required only if there is overlapping address space in use and the ip address is in overlapping space. TTL The Time To Live for the record. The container is then used to uniquely determine the device. the web service client must call initExportPrefixPool to initialize the API. Name=’pool1’ Container Exports prefix pool by Container name.wsdl that describes the initExportPrefixPool request and response messages is shown following. as described below. Service Invocation The portion of Exports. Initialization Before the exportPrefixPool API is called. IPAddressRange=’2001 :db8 :0 :1 ::/65’ Response The response from the initExportPrefixPool web service is a WSContext object defined previously and must be included in each successive call to exportPrefixPool. The portion of Exports. The query string syntax is defined previously. Selector Description Exam ple Name Exports prefix pool by name. described following the selectors table. IPAddress=’2001:db8::1’ IP Address Range Exports prefix pool by address range in address/length format. Application Program Interfaces (API) 309 .wsdl that describes the exportPrefixPool request and response messages is shown following.ExportPrefixPool ExportPrefixPool Overview The exportPrefixPool API enables the web service client to issue a request to retrieve a list of Prefix Pools from IPControl. In addition. <wsdl:message name="initExportPrefixPoolRequest"> <wsdl:part name="filter" type="soapenc:string"/> <wsdl:part name="options" type="impl:ArrayOf_soapenc_string"/> </wsdl:message> <wsdl:message name="initExportPrefixPoolResponse"> <wsdl:part name="initExportPrefixPoolReturn" type="tns2:WSContext"/> </wsdl:message> Request The query string is passed as input from the client to the initExportPrefixPool web service. Supported selectors for exporting prefix pools are defined in the following table. IP Address Exports the prefix pool that contains that address. This service enables the client to filter the list of Prefix Pools retrieved. Container=’Exton’ Net Service Exports prefix pool by assigned DHCP server Netservice=’DhcpServer1’ . the initExportPrefixPool service accepts the options array. The elements are described in the table that follows. When this context is provided to a subsequent call to exportPrefixPool. The WSPrefixPools can then be modified and/or imported using the importPrefixPool API.wsdl that describes WSPrefixPool. the array of structures returned by exportPrefixPool. Response The result returned from the exportPrefixPool service is an array of WSPrefixPool objects matching the selection criteria specified in the query filter. the value specified by the client cannot exceed 100. The web service client may change this maxResults attribute of the WSContext before any call to the exportPrefixPool service to modify the size of the resultant WSPrefixPool object array. However.ExportPrefixPool <wsdl:message name="endExportPrefixPoolRequest"> <wsdl:part name="context" type="tns2:WSContext"/> </wsdl:message> <wsdl:message name="exportPrefixPoolResponse"> <wsdl:part name="exportPrefixPoolReturn" type="impl:ArrayOf_tns2_WSPrefixPool"/> </wsdl:message> Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportPrefixPool service defined aboveand has the maxResults field set to a default value of 100. WSPrefixPool Below is the portion of Exports. that match the criteria in the given query filter. the number of exported pools is limited to the first 100. The format of the WSPrefixPool matches that defined by the importPrefixPool. <complexType name="WSPrefixPool"> <sequence> <element name="allowClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="delegatedPrefixLength" nillable="true" type="soapenc:int"/> <element name="denyClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="dhcpOptionSet" nillable="true" type="soapenc:string"/> <element name="dhcpPolicySet" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="length" nillable="true" type="soapenc:int"/> <element name="longestPrefixLength" nillable="true" type="soapenc:int"/> <element name="name" nillable="true" type="soapenc:string"/> <element name="primaryNetService" nillable="true" type="soapenc:string"/> <element name="shortestPrefixLength" nillable="true" type="soapenc:int"/> <element name="startAddr" nillable="true" type="soapenc:string"/> <element name="type" nillable="true" type="soapenc:string"/> </sequence> </complexType> 310 IPControl CLI and API Guide . ” Automatic PD DHCPv6” name Address Pool name. CNR only. Length Length of the prefix pool type One of “Dynamic PD DHCPv6”. Application Program Interfaces (API) 311 . primaryNet Service The name of the DHCP server that will serve prefixes from this pool dhcpOptionSet The name of an Option Set used with this pool dhcpPolicySet The name of a Policy Set used with this pool. container The name of the container that holds the block in which the pool is defined. longestPrefixLength Specifies the longest length of the delegated prefix. allowClient Classes An array of Client Classes that are allowed in this address pools. delegatedPrefixLength Specifies the default length of the delegated prefix shortestPrefixLength Specifies the shortest length of the delegated prefix. Each array element names a different Client Class. Each element of the array names a different Client Class. denyClientClasses An array of Client Classes that are NOT allowed in this address pools.ExportPrefixPool Elem ent Description id The internal identifier for this address pool object startAddr The IP Address of the first address in the pool. CNR only. “update” or “delete” that resource record pendingAction='create' Select resource records by the login id of the administrator requesting the resource record change. Selector Description Exam ple Domain Select resource records by domain name.ExportResourceRecordPendingApproval ExportResourceRecordPendingApproval Overview The exportResourceRecordPendingApproval API enables the web service client to issue a request to retrieve a list of resource records that are waiting for approval by the invoking administrator. adminLoginId='someuser' adminLoginId pendingAction='delete' pendingAction=’update’ Response The response from the initExportResourceRecordPendingApproval web service is a WSContext object defined previously. Domain contains “ins. This service enables the client to filter the list of resource records retrieved by requesting administrator. Currently. 312 IPControl CLI and API Guide . domain name/type and the requested action. The portion of Exports. Initialization Before the exportResourceRecordPendingApproval API is called.wsdl that describes the initExportResourceRecordPendingApproval request and response messages is shown following. as described below. the web service client must call initExportResourceRecordPendingApproval to initialize the API. This WSContext object must be included in each successive call to exportResourceRecordPendingApproval. Domain Type contains ‘Internal’ pendingAction Select resource records based on the request to “create”. <wsdl:message name="initExportResourceRecordPendingApprovalRequest"> <wsdl:part name="filter" type="soapenc:string"/> <wsdl:part name="options" type="impl:ArrayOf_soapenc_string"/> </wsdl:message> <wsdl:message name="initExportResourceRecordPendingApprovalResponse"> <wsdl:part name="initExportResourceRecordPendingApprovalReturn" type="tns2:WSContext"/> </wsdl:message> Request The query string is passed as input from the client to the initExportResourceRecordPendingApproval web service in the filter parameter. there are no options defined for this service.com’ Domain Type Select resource records by domain type. Supported selectors for exporting device resource records by device are defined in the following table. The query string syntax is defined previously. ExportResourceRecordPendingApproval Service Invocation The portion of Exports. always guarantee the number of results to be the max results value or less. When this context is provided to a subsequent call to exportResourceRecordPendingApproval. WSResourceRecPendingApproval The portion of Exports. Paging A resource record change request in IPControl is normalized within the database and thus may be represented by more than a single row in multiple tables. the array of structures returned by exportResourceRecordPendingApproval is shown following. Response The result returned from the exportResourceRecordPendingApproval service is an array of WSResourceRecPendingApproval objects matching the selection criteria specified in the query filter.wsdl that describes WSResourceRecPendingApproval. However.wsdl that describes the exportResourceRecordPendingApproval request and response messages is shown following. It will. or less (see Paging). <wsdl:message name="exportResourceRecordPendingApprovalRequest"> <wsdl:part name="context" type="tns2:WSContext" /> </wsdl:message> <wsdl:message name="exportResourceRecordPendingApprovalResponse"> <wsdl:part name="exportResourceRecordPendingApprovalReturn" type="impl:ArrayOf_tns2_WSResourceRecPendingApproval"/> </wsdl:message> Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportResourceRecordPendingApproval service defined above and has the maxResults field set to a default value of 5000. the number of exported resource records is limited to the first 5000 resource record change requests. The web service client may change this maxResults attribute of the WSContext before any call to the exportResourceRecordPendingApproval service to modify the size of the resultant WSResourceRecPendingApproval object array. the value specified by the client cannot exceed 5000. the exportResourceRecordPendingApproval service cannot guarantee that the number of WSResourceRecPendingApproval objects returned in any single execution of the service will be equal to the max results set on the WSContext object. Application Program Interfaces (API) 313 . The workflowId returned in WSResourceRecPendingApproval can then be used to invoke the modifyPendingApproval API. however. Because of this and for performance. that match the criteria in the given query filter. The elements are described in the table that follows. domainType Domain type of resource record. action The request – “update”. domain Domain name of resource record. dateTime The date and time of the approval request.ExportResourceRecordPendingApproval <complexType name="WSDeviceResourceRec"> <sequence> <element name="TTL" nillable="true" type="soapenc:string"/> <element name="action" nillable="true" type="soapenc:string"/> <element name="admin" nillable="true" type="soapenc:st ring"/> <element name="comment" nillable="true" type="soapenc:string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="data" nillable="true" type="soapenc:string"/> <element name="dateTime" nillable="true" type="soapenc:string"/> <element name="domain" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="hostname" nillable="true" type="soapenc:string"/> <element name="ipAddress" nillable="true" type="soapenc:string"/> <element name="owner" nillable="true" type="soapenc:string"/> <element name="resourceRecClass" nillable="true" type="soapenc:string"/> <element name="resourceRecType" nillable="true" type="soapenc:st ring"/> <element name="server" nillable="true" type="soapenc:string"/> <element name="view" nillable="true" type="soapenc:string"/> <element name="workflowId" nillable="true" type="soapenc:int"/> <element name="zone" nillable="true" type="s oapenc:string"/> </sequence> </complexType> Elem ent Accepted Values TTL The Time To Live for the record. “create” or “delete” admin The login id of the requesting administrator comment Comment text associated with the resource record. Defaults to “IN”. data The data portion of the resource record. resourceRecClass The Class of the Resource Record. The format is dependent on the type specified above. server The Time To Live for the record. owner The owner field of the resource record. This is required only if there is overlapping address space in use and the ip address is in overlapping space. resourceRecordType The Type of the resource Record. zone The name of the DNS network service as defined in IPControl to import the zone data into. hostname The device host name. The container is then used to uniquely determine the device. ipAddress The IP Address of the Device. view The name of the view for the domains of this resource record workflowid This is required as input to modifyPendingApproval. 314 IPControl CLI and API Guide . container The name of the container that holds the device for this resource record. Domain Type contains ‘Internal’ pendingAction Select resource records based on the request to “create”. Initialization Before the exportResourceRecordPendingApprovalStatus API is called. <wsdl:message name="initExportResourceRecordPendingApprovalRequestStatus"> <wsdl:part name="filter" type="soapenc:string"/> <wsdl:part name="options" type="impl:ArrayOf_soapenc_string"/> </wsdl:message> <wsdl:message name="initExportResourceRecordPendingApprovalStatusResponse"> <wsdl:part name="initExportResourceRecordPendingApprovalStatusReturn" type="tns2:WSContext"/> </wsdl:message> Request The query string is passed as input from the client to the initExportResourceRecordPendingApprovalStatus web service in the filter parameter. The query string syntax is defined previously. Currently. This WSContext object must be included in each successive call to exportResourceRecordPendingApprovalStatus as described below.wsdl that describes the initExportResourceRecordPendingApprovalStatus request and response messages is shown following.com’ Domain Type Select resource records by domain type. Supported selectors for exporting device resource records by device are defined in the following table. the web service client must call initExportResourceRecordPendingApprovalStatus to initialize the API. Application Program Interfaces (API) 315 . “update” or “delete” that resource record pendingAction='create' pendingAction='delete' pendingAction=’update’ Response The response from the initExportResourceRecordPendingApprovalStatus web service is a WSContext object defined previously. there are no options defined for this service. Domain contains “ins. These updates include those to create.ExportResourceRecordPendingApprovalStatus ExportResourceRecordPendingApprovalStatus Overview The exportResourceRecordPendingApprovalStatus API enables the web service client to issue a request to retrieve a list of resource records were submitted for approval by the invoking administrator. The portion of Exports. update or delete a resource record. Selector Description Exam ple Domain Select resource records by domain name. 316 IPControl CLI and API Guide . the value specified by the client cannot exceed 5000. however. the exportResourceRecordPendingApprovalStatus service cannot guarantee that the number of WSResourceRecPendingApproval objects returned in any single execution of the service will be equal to the max results set on the WSContext object.ExportResourceRecordPendingApprovalStatus Service Invocation The portion of Exports. or less (see Paging). the array of structures returned by exportResourceRecordPendingApprovalStatus is shown following.wsdl that describes the exportResourceRecordPendingApprovalStatus request and response messages is shown below. The elements are described in the table that follows. When this context is provided to a subsequent call to exportResourceRecordPendingApprovalStatus. <wsdl:message name="exportResourceRecordPendingApprovalStatusRequest"> <wsdl:part name="context" type="tns2:WSContext" /> </wsdl:message> <wsdl:message name="exportResourceRecordPendingApprovalStatusResponse"> <wsdl:part name="exportResourceRecordPendingApprovalStatusReturn" type="impl:ArrayOf_tns2_WSResourceRecPendingApproval"/> </wsdl:message> Request The WSContext passed as input by the client web service is the WSContext object returned by the initExportResourceRecordPendingApprovalStatus service defined abov and has the maxResults field set to a default value of 5000. WSResourceRecPendingApproval The portion of Exports. the number of exported resource records is limited to the first 5000 resource record change requests. Response The result returned from the exportResourceRecordPendingApprovalStatus service is an array of WSResourceRecPendingApproval objects matching the selection criteria specified in the query filter. The web service client may change this maxResults attribute of the WSContext before any call to the exportResourceRecordPendingApprovalStatus service to modify the size of the resultant WSResourceRecPendingApproval object array. Paging A resource record change request in IPControl is normalized within the database and thus may be represented by more than a single row in multiple tables. However. that match the criteria in the given query filter. It will. Because of this and for performance. always guarantee the number of results to be the max results value or less.wsdl that describes WSResourceRecPendingApproval. zone The name of the DNS network service as defined in IPControl to import the zone data into. domain Domain name of resource record. container The name of the container that holds the device for this resource record.ExportResourceRecordPendingApprovalStatus <complexType name="WSDeviceResourceRec"> <sequence> <element name="TTL" nillable="true" type="soapenc:string"/> <element name="action" nillable="true" type="soapenc:string"/> <element name="admin" nillable="true" type="soapenc:string"/> <element name="comment" nillable="true" type="soapenc:string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="data" nillable="true" type="soapenc:string"/> <element name="dateTime" nillable="true" type="soapenc:s tring"/> <element name="domain" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="hostname" nillable="true" type="soapenc:string"/> <element name="ipAddress" nillable="true" type="soapenc:string"/> <element name="owner" nillable="true" type="soapenc:string"/> <element name="resourceRecClass" nillable="true" type="soapenc:string"/> <element name="resourceRecType" nillable="true" type="soapenc:string"/> <element name="server" nillable="true" type="soapenc:string"/> <element name="view" nillable="true" type="soapenc:string"/> <element name="workflowId" nillable="true" type="soapenc:int"/> <element name="zone" nillable="true" type="soapenc:string"/ > </sequence> </complexType> Elem ent Accepted Values TTL The Time To Live for the record. This is required only if there is overlapping address space in use and the ip address is in overlapping space. Application Program Interfaces (API) 317 . dateTime The date and time of the approval request. server The Time To Live for the record. The format is dependent on the type specified above. owner The owner field of the resource record. resourceRecordType The Type of the resource Record. view The name of the view for the domains of this resource record workflowid This is required as input to modifyPendingApproval. hostname The device host name. resourceRecClass The Class of the Resource Record. domainType Domain type of resource record. The container is then used to uniquely determine the device. action The request – “update”. “create” or “delete” admin The login id of the requesting administrator comment Comment text associated with the resource record. ipAddress The IP Address of the Device. data The data portion of the resource record. Defaults to “IN”. Request The complex type WSDevice. Within this block. The elements are described in the table that follows. there should be a range of addresses with a type of “Reserved” and a status of “reserved” for the given device type. to in-use. This service is available as an operation in the IncUseNextReservedIPAddress web service. which is passed as input from the client to the web service. for the specified device type. it will be applied to the device associated with the IP Address. The next lowest IP address within the range will be assigned a type of “Static” and a status of “inuse”. <complexType <sequence> <element <element <element <element name="WSDevice"> name="view" nillable="true" type="soapenc:string" /> name="hwType" nillable="true" type="soapenc:string" /> name="addressType" nillable="true" type="soapenc:string" /> name="ipAddress" nillable="true" type="soapenc:string" /> 318 IPControl CLI and API Guide .UseNextReservedIPAddress Updates This section explains the web services available for updating information in IPControl.wsdl that describes the UseNextReservedIPAddress request and response messages. is described in the next section. In addition. there is an option to add resource records for the device. <wsdl:message name="useNextReservedIPAddressRequest"> <wsdl:part name="inpDevice" type="tns1:WSDevice" /> </wsdl:message> <wsdl:message name="useNextReservedIPAddressResponse"> <wsdl:part name="useNextReservedIPAddressReturn" type="soapenc:string" /> </wsdl:message> Response The string that is returned contains the IP Address used to satisfy the request. UseNextReservedIPAddress Overview The UseNextReservedIPAddress API enables the web service client to mark the next reserved IP Address in the specified block.wsdl that describes WSDevice. the parameter structure passed to UseNextReservedIPAddress. Parameters WSDevice The portion of IncUseNextReservedIPAddress. is shown following. You can see the complete WSDL at: http://localhost:8080/inc-ws/services/IncUseNextReservedIPAddress?wsdl Request and Response Messages Below is the portion of IncUseNextReservedIPAddress. If a hostname is specified. The block must have a status if “In Use/Deployed”. If not specified. Accepted values are true or false. No MACAddress Not used deviceType The device type associated with the reserved IP address.UseNextReservedIPAddress <element name="resourceRecordFlag" nillable="true" type="soapenc:string" /> <element name="MACAddress" nillable="true" type="soapenc:string" /> <element name="deviceType" nillable="true" type="soapenc:string" /> <element name="domainName" nillable="true" type="soapenc:string" /> <element name="container" nillable="true" type="soapenc:string" /> <element name="description" nillable="true" type="soapenc:string" /> <element name="hostname" nillable="true" type="soapenc:string" /> <element name="aliases" nillable="true" type="impl:ArrayOf_soapenc_string" /> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string" /> </sequence> </complexType> Elem ent Accepted Values view Not used hwType Not used addressType Not used ipAddress Required Return Code Fault String -26 Invalid Ip Address: address -47 Device type not found: type The IP Address of the block Yes resourceRecordFlag Whether or not to add resource records for this device. domainName Not used container Not used description Not used hostname Valid host name or APPLYNAMINGPOLICY. aliases Not used userDefinedFields Not used Yes Yes Other returnCodes and faultstrings Return Code Faultstring -1 Error saving resource records: error (system errors) -5 Container not found for block -23 No matching in-use blocks found -36 Block not found -47 Error creating DnsResourceRecHelper (system error) -61 Forward domain not found for: address -62 Subnet not found for: address Application Program Interfaces (API) 319 . defaults to false. You can see the complete WSDL at: http://localhost:8080/inc-ws/services/Deletes?wsdl DeleteAddrPool Overview The DeleteAddrPool API enables the web service client to delete an Address Pool from a block . Parameters WSAddrpool The portion of Deletes. is described in the next section. is shown following. the web service will validate and delete the address pool.DeleteAddrPool Deletes The Delete APIs allow a client program to delete objects in the system. <wsdl:operation name="deleteAddrPool" parameterOrder="inpAddrPool deleteDevicesInAddrpool"> <wsdl:input message="impl:deleteAddrPoolRequest" name="deleteAddrPoolRequest"/> <wsdl:output message="impl:deleteAddrPoolResponse" name="deleteAddrPoolResponse"/> </wsdl:operation> <wsdl:message name="deleteAddrPoolRequest "> <wsdl:part name="inpAddrPool" type="tns2:WSAddrpool"/> <wsdl:part name="deleteDevicesInAddrpool" type="xsd:boolean"/> </wsdl:message> <wsdl:message name="deleteAddrPoolResponse"> </wsdl:message> Response There is no data in the response. The elements are described in the table that follows. Request The complex type WSAddrpool.wsdl that describes the deleteAddrPool request and response messages is shown following. Request and Response Messages The portion of Deletes. which is passed as input from the client to the web service. By specifying the address pool to be deleted. the parameter structure passed to DeleteAddrPool. Each of these services is available as an operation in the Deletes web service.wsdl that describes WSAddrpool. 320 IPControl CLI and API Guide . <complexType name="WSAddrpool"> <sequence> <element name="allowClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="denyClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="dhcpOptionSet" nillable="true" type="s oapenc:string"/> <element name="dhcpPolicySet" nillable="true" type="soapenc:string"/> <element name="endAddr" nillable="true" type="soapenc:string"/> <element name="failoverNetService" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:string"/> <element name="name" nillable="true" type="soapenc:string"/> <element name="primaryNetService" nillable="true" type="soapenc:string"/> <element name="sharename" nillable="true" type="soapenc:string"/> <element name="startAddr" nillable="true" type="soapenc:string"/> <element name="type" nillable="true" type="soapenc:string"/> <element name="prefixLength" nillable="true" type="soapenc:string"/> </sequence> </complexType> Elem ent Accepted Values Required Return Code Faultstring Name The name of the address pool to be deleted. Yes -117 Address Pool not found Container The container in which the address pool resides in. Yes -117 Address Pool not found Startaddr The start Address of the address pool to be deleted. Yes -117 Address Pool not found Application Program Interfaces (API) 321 . This is to disambiguate the address pool. wsdl that describes the deleteAggregate request and response messages is shown following. It will also adjust the parent block assignments of any child blocks. The elements are described in the table that follows. the parameter structure passed to DeleteAggregateBlock. the web service will validate and delete the block. which is passed as input from the client to the web service. Yes -127 Block start and parent block 322 IPControl CLI and API Guide . <wsdl:operation name="deleteAggregateBlock" parameterOrder="inpBlock"> <wsdl:input message="impl:deleteAggregateBlockRequest" name="deleteAggregateBlockRequest"/> <wsdl:output message="impl:deleteAggregateBlockResponse" name="deleteAggregateBlockResponse"/> </wsdl:operation> <wsdl:message name="deleteAggregateBlockRequest "> <wsdl:part name="inpBlock" type="tns2:WSBlock4Delete"/> </wsdl:message> <wsdl:message name="deleteAggregateBlockResponse"> </wsdl:message> Response There is no data in the response. By specifying the block to be deleted. is shown following. Request and Response Messages The portion of Deletes. <complexType name="WSBlock4Delete"> <sequence> <element name="blockAddr" nillable="true" type="soapenc:string"/> <element name="blockSize" nillable="true" type="soapenc:int"/> <element name="container" nillable="true" type="soapenc:string"/> </sequence> </complexType> Elem ent Accepted Values Required Return Code Faultstring blockAddr The start address of the aggregate block to be deleted.wsdl that describes WSBlock4Delete.DeleteAggregateBlock DeleteAggregateBlock Overview The DeleteAggregateBlock API enables the web service client to delete an intermediate level Aggregate block from the block hierarchy. is described in the next section. Request The complex type WSBlock4Delete. Parameters WSBlock4Delete The portion of Deletes. Long format eliminates ambiguity in cases where there are duplicate container names. Long format example: IPControl/Texas/Dallas.255.255.g. Short format example: Dallas. Yes -15 Block size invalid: <size> container The name of the container from which to delete the aggregate block.0 network). Names can be in either short or long format. Yes -42 Missing container name -5 Could not find container: <container> -99 Admin is not authorized to add blocks to this container Application Program Interfaces (API) 323 .DeleteAggregateBlock Elem ent Accepted Values Required Return Code Faultstring address both required -12 Could not convert <address> to ipAddress blockSize The size of the block in short-notation (e.. 24 for a 255. DeleteBlock DeleteBlock Overview The DeleteBlock API enables the web service client to delete blocks from IPControl.wsdl that describes the DeleteBlock request and response messages is shown following. e. 324 IPControl CLI and API Guide No. This is often the address followed by CIDR size. block name and container name. -100 Cannot delete free aggregate. unless block is overlappe d. Request The request takes two parameters.0. Parameters Elem ent Accepted Values Required Return Code Faultstring blockName The name of an existing block. .0/8. Request and Response Messages The portion of Deletes. This is required if overlapping space is in use and the block overlaps another in the system. if the block name was changed during allocation.0. Yes -36 Block not found -97 Block not unique -98 Parent not found. <wsdl:operation name="deleteBlock" parameterOrder="container blockName"> <wsdl:input message="impl:deleteBlockRequest" name="deleteBlockRequest"/> <wsdl:output message="impl:deleteBlockResponse" name="deleteBlockResponse"/> </wsdl:operation> <wsdl:message name="deleteBlockRequest"> <wsdl:part name="container" type="soapenc:string"/> <wsdl:part name="blockName" type="soapenc:string"/> </wsdl:message> <wsdl:message name="deleteBlockResponse"> </wsdl:message> Response There is no data in the response.g. Their use is described in more detail in the next section. -101 Error deleting block -102 IP Address Cleanup Error -105 Error reclaiming blocks -99 Container not found Container The name of the container holding the block. 10. then the modified value should be supplied here. However. Parameters fullName This is name of the container. The name can be either qualified or unqualified. fullName. Request and Response Messages The portion of Deletes. A qualified name must start with the root container and include the complete container path to the desired container. but must be unique.wsdl that describes the deleteContainer request and response messages is shown following. Other returnCodes and faultstrings ReturnCode Faultstring -2 Container delete failed (database error) -5 Container not found -99 Access denied -132 Invalid Container name supplied -143 Container name ambiguous -144 Container has children -145 Container has blocks -146 Container has services Application Program Interfaces (API) 325 .DeleteContainer DeleteContainer Overview The DeleteContainer API enables the web service client to delete containers from IPControl. Request The request contains a single string parameter. <wsdl:operation name="deleteContainer" parameterOrder="fullName"> <wsdl:input message="impl:deleteContainerRequest" name="deleteContainerRequest"/> <wsdl:output message="impl:deleteContainerResponse" name="deleteContainerResponse"/> </wsdl:operation> <wsdl:message name="deleteContainerRequest <wsdl:part name="fullName" type="soapenc:string"/> </wsdl:message> <wsdl:message name="deleteContainerResponse"> </wsdl:message> Response There is no data in the response. The container names should be separated by slashes. which is passed as input from the client to the web service.wsdl that describes the deleteDevice request and response messages is shown following. the parameter structure passed to DeleteDevice. Request The complex type WSDevice. Use the ModifyBlock API to delete Interface-type devices. only two of the fields are used. Parameters WSDevice The portion of Deletes. The required elements are described in the table that follows. However.DeleteDevice DeleteDevice Overview The DeleteDevice API enables the web service client to delete devices from IPControl. The other elements are ignored. Note that this is not used to delete devices of type “Interface”. this is the same structure that is passed to ImportDevice. <complexType <sequence> <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element name="WSDevice"> name="MACAddress" nillable="true" type="soapenc:string"/> name="addressType" nillable="true" type="soapenc:string"/> name="aliases" nillable="true" type="impl:ArrayOf_soapenc_string"/> name="container" nillable="true" type="soapenc:string"/> name="description" nillable="true" type="soapenc:string"/> name="deviceType" nillable="true" type="soapenc:string"/> name="domainName" nillable="true" type="soapenc:string"/> name="domainType" nillable="true" type="soapenc:string"/> name="dupWarning" nillable="true" type="soapenc:string"/> name="hostname" nillable="true" type="soapenc:string"/> name="hwType" nillable="true" type="soapenc:string"/> name="ipAddress" nillable="true" type="soapenc:string"/> name="resourceRecordFlag" nillable="true" type="soapenc:string"/> name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string"/> maxOccurs="unbounded" name="interfaces" nillable="true" type="tns2:WSInterface"/> name="id" nillable="true" type="soapenc:int"/> 326 IPControl CLI and API Guide .wsdl that describes WSDevice. is shown following. is described in the next section. For consistency. Request and Response Messages The portion of Deletes. <wsdl:operation name="deleteDevice" parameterOrder="inpDev"> <wsdl:input message="impl:deleteDeviceRequest" name="deleteDeviceRequest"/> <wsdl:output message="impl:deleteDeviceResponse" name="deleteDeviceResponse"/> </wsdl:operation> <wsdl:message name="deleteDeviceRequest"> <wsdl:part name="inpDev" type="tns2:WSDevice"/> </wsdl:message> <wsdl:message name="deleteDeviceResponse"> </wsdl:message> Response There is no data in the response. -28 IP Address ambiguous Application Program Interfaces (API) 327 . if overlapping space is in use and the device is in an overlapped block.DeleteDevice <element name="excludeFromDiscovery" nillabl e="true" type="soapenc:string"/ </sequence> </complexType> Elem ent Accepted Values Required Return Code Faultstring ipAddress The IP Address of the device Yes -26 Invalid IP Address: address -27 IP Address not found -28 IP Address ambiguous container The name of the container that contains the device. Yes. Use the ModifyBlock API to delete Interface-type devices. are shown following. are described in the next section. which are passed as input from the client to the web service. the parameter structures passed to DeleteDeviceInterface. Parameters WSDevice The portion of Deletes. <complexType <sequence> <element <element <element <element <element <element <element <element <element <element <element <element <element name="WSDevice"> name="MACAddress" nillable="true" type="soapenc:string"/> name="addressType" nillable="true" type="soapenc:string"/> name="aliases" nillable="true" type="impl:ArrayOf_soapenc_string"/> name="container" nillable="true" type="soapenc:string"/> name="description" nillable="true" type="soapenc:string"/> name="deviceType" nillable="true" type="soapenc:string"/> name="domainName" nillable="true" type="soapenc:string"/> name="domainType" nillable="true" type="soapenc:string"/> name="dupWarning" nillable="true" type="soapenc:string"/> name="hostname" nillable="true" type="soapenc:string"/> name="hwType" nillable="true" type="soapenc:string"/> name="ipAddress" nillable="true" type="soapenc:string"/> name="resourceRecordFlag" nillable="true" type="soapenc:string"/> 328 IPControl CLI and API Guide . The elements are described in the table that follows.wsdl that describes the deleteDeviceInterface request and response messages is shown following. Note that this is not used to delete devices of type “Interface”. However. Request and Response Messages The portion of Deletes.DeleteDeviceInterface DeleteDeviceInterface Overview The DeleteDeviceInterface API enables the web service client to delete device interfaces from IPControl. these are the same structures that are passed to ImportDevice. <wsdl:operation name="deleteDeviceInterface" parameterOrder="inpDev"> <wsdl:input message=" "impl:deleteDeviceInterfaceRequest" name="deleteDeviceInterfaceRequest""/> <wsdl:output message=" impl:deleteDeviceInterfaceResponse" name="deleteDeviceInterfaceResponse"/> </wsdl:operation> <wsdl:message name="deleteDeviceInterfaceRequest"> <wsdl:part name="inpDev" type="tns2:WSDevice"/> </wsdl:message> <wsdl:message name="deleteDeviceInterfaceResponse"> </wsdl:message> Response There is no data in the response. For consistency.wsdl that describes WSDevice and WSInterface. Request The complex types WSDevice and WSInterface. only three of the fields are used. description Ignored No deviceType Ignored No domainName Ignored No domainType Ignored No dupWarning Ignored No hostname Ignored No hwType Ignored No ipAddress The IP Address of the device Yes resourceRecord Flag Ignored No userDefined Fields Ignored No Return Code Faultstring -28 IP Address ambiguous -26 Invalid IP Address: address -27 IP Address not found -28 IP Address ambiguous -127 IP Address is required Application Program Interfaces (API) 329 .DeleteDeviceInterface <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element maxOccurs="unbounded" name="interfaces" nillabl e="true" type="tns2:WSInterface"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="excludeFromDiscovery" nillable="true" type="soapenc:string"/> </sequence> </complexType> <complexType name="WSNetElementInterface"> <sequence> <element name="id" nillable="true" type="soapenc:int"/> <element name="interfaceName" nillable="true" type="soapenc:string"/> <element name="netElementName" nillable="true" type="soapenc:string"/> <element name="status" nillable="true" type="soapenc:string"/> </sequence> </complexType> Elem ent Accepted Values Required MACAddress Ignored No addressType Ignored No aliases Ignored No container The name of the container that contains the device. Yes. if overlapping space is in use and the device is in an overlapped block. sequence .addressType .excludeFromDiscovery . Each element in the array corresponds to one interface to be deleted.container .DeleteDeviceInterface Elem ent Accepted Values Required Return Code Faultstring interfaces An array of WSInterface structures.id . The fields in the WSInterface structure are: Yes -20 Must specify interface name -19 Interface not found for device: ipAddress with interface name: name -38 Cannot delete all interfaces.virtual id Ignored No excludeFrom Discovery Ignored No 330 IPControl CLI and API Guide .hwType . Use DeleteDevice. name: Interface Name (Required) The following are ignored: .ipAddress .macAddress . Request The complex type WSDeviceResourceRec. <wsdl:operation name="deleteDeviceResourceRecord" parameterOrder="inpRR"> <wsdl:input message="impl:deleteDeviceResourceRecordRequest" name="deleteDeviceResourceRecordRequest"/> <wsdl:output message="impl:deleteDeviceResourceRecordResponse" name="deleteDeviceResourceRecordResponse"/> </wsdl:operation> <wsdl:message name="deleteDeviceResourceRecordRequest"> <wsdl:part name="inpRR" type="tns2:WSDeviceResourceRec"/> </wsdl:message> <wsdl:message name="deleteDeviceResourceRecordResponse"> </wsdl:message> Response There is no data in the response. Parameters WSDeviceResourceRecord The portion of Deletes. Request and Response Messages The portion of Deletes. which is passed as input from the client to the web service. the parameter structure passed to DeleteDeviceResourceRecord. The elements are described in the table that follows.wsdl that describes the deleteDeviceResourceRecord request and response messages is shown following. is described in the next section.wsdl that describes WSDeviceResourceRec.DeleteDeviceResourceRecord DeleteDeviceResourceRecord Overview The DeleteDeviceResourceRecord API enables the web service client to delete resource records from IPControl that are affiliated with a device. is shown following. <complexType name="WSDeviceResourceRec"> <sequence> <element name="TTL" nillable="true" type="soapenc:string"/> <element name="comment" nillable="true" type="soapenc:string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="data" nillable="true" type="soapenc:string"/> <element name="domain" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="hostname" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="ipAddress" nillable="true" type="soapenc:string"/> <element name="owner" nillable="true" type="soapenc:string"/> <element name="resourceRecClass" nillable="true" type="soapenc:string"/> <element name="resourceRecType" nillable="true" type="soapenc:string"/> </sequence> </complexType> Application Program Interfaces (API) 331 . Yes -91 Data field required domain The name of the domain for this resource record Yes -60 Domain not found: domain -135 Domain required: domain domainType The domain type of the domain. Yes. This must match the RData exactly. Defaults to “Default”. Yes. No -81 Domain type not found: domainType hostname The device host name. IP Address not unique: address -120 No device with ipaddress: address -89 Owner field required -134 Invalid character in Owner owner -90 Type field required -92 Unknown type: type id Ignored ipAddress The IP Address of the device Owner The ow ner field of the record to be deleted. This is required only if there is overlapping address space in use and the ip address is in overlapping space. unless ipAddress is specified -133 Hostname or ip address required -121 Hostname not unique: hostname -120 No device with hostname: hostname -133 Hostname or ip address required -26 Invalid IP Address: address -28 Specify container. Only if ipAddress in overlappin g space data The RData portion of the record to delete.DeleteDeviceResourceRecord Elem ent Accepted Values Required Return Code Faultstring TTL Time To Live No comment Ignored container The name of the container that holds the device. This defaults to “IN” No resourceRecType The type of resource record being deleted Yes 332 IPControl CLI and API Guide . The container is then used to uniquely determine the device. unless host name is specified Yes resourceRecClass The Resource Record class. This must match exactly. device or resource record (database error) -124 DNS Resource record not found -125 DNS Resource record not unique 401 <401>Unauthorized Application Program Interfaces (API) 333 .DeleteDeviceResourceRecord Other returnCodes and faultstrings ReturnCode Faultstring -2 Exception reading domain. Request and Response Messages The portion of Deletes. <complexType name="WSDomain"> <sequence> <element name="contact" nillable="true" type="soapenc:string"/> <element name="defaultTTL" nillable="true" typ e="soapenc:string"/> <element name="delegated" type="xsd:boolean"/> <element name="derivative" nillable="true" type="soapenc:string"/> <element name="domainName" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="expire" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:string"/> <element name="infoTemplate" nillable="true" type="soapenc:string"/> <element name="managed" type="xsd:boolean"/> <element name="negativeCacheTTL" nillable="true" type="soapenc:string"/> <element name="refresh" nillable="true" type="soapenc:string"/> <element name="retry" nillable="true" type="soapenc:string"/> <element name="reverse" type="xsd:boolean"/> <element name="serialNumber" nillable="true" type="soapenc:long"/> <element name="templateDomain" nillable="true" type="soapenc:string"/> <element name="userDefinedFields" nillable="true" type="impl:ArrayOf_soapenc_string"/> </sequence> </complexType> 334 IPControl CLI and API Guide . the parameter structure passed to DeleteDomain. <wsdl:message name="deleteDomainRequest"> <wsdl:part name="inpDomain" type="tns2:WSDomain"/> </wsdl:message> <wsdl:message name="deleteDomainResponse"> </wsdl:message> Response There is no data in the response.wsdl that describes the deleteDomain request and response messages is shown following. Parameters WSDomain The portion of Deletes. is described in the next section. The elements are described in the table that follows. Request The complex type WSDomain.DeleteDomain DeleteDomain Overview The DeleteDomain API enables the web service client to delete domains from IPControl. is shown following. which is passed as input from the client to the web service.wsdl that describes WSDomain. No id Ignored No infoTemplate Ignored No managed No negativeCacheTTL Ignored Ignored refresh Ignored No retry Ignored No reverse Ignored No serialNumber Ignored No templateDomain Ignored No userDefinedFields Ignored No -81 Could not delete domain domain: zones may be attached to it. when not “Default”. -233 domainType expire Domain type name already defined to IPControl. Ignored Yes. domain from Default domain type. Yes Return Code Faultstring -60 Domain not found: domainType/domain -95 Cannot delete . the “Default” domain type will be used. If not specified. Domain type not found: domainType No Other returnCodes and faultstrings ReturnCode Faultstring -2 Exception reading domain or domain type record (database error) -99 Access denied Application Program Interfaces (API) 335 . -135 Domain required -232 Cannot delete domain because it is a parent domain.DeleteDomain Elem ent Description and accepted values Required contact Ignored No defaultTTL Ignored No delegated Ignored No derivitive Ignored No domainName The name of the domain to delete. is described in the next section. <complexType name="WSDeviceResourceRec"> <sequence> <element name="TTL" nillable="true" type="soapenc:string"/> <element name="comment" nillable="true" type="soapenc:string"/> <element name="data" nillable="true" type="soapenc:string"/> <element name="domain" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="owner" nillable="true" type="soapenc:string"/> <element name="resourceRecClass" nillable="true" type="soapenc:string"/> <element name="resourceRecType" nillable="true" type="soapenc:string"/> </sequence> </complexType> 336 IPControl CLI and API Guide . which is passed as input from the client to the web service. the parameter structure passed to DeleteDomainResourceRecord. Parameters WSDomainResourceRecord The portion of Deletes.DeleteDomainResourceRecord DeleteDomainResourceRecord Overview The DeleteDomainResourceRecord API enables the web service client to delete resource records from IPControl that are affiliated with a domain. The elements are described in the table that follows.wsdl that describes the deleteDomainResourceRecord request and response messages is shown following. Request The complex type WSDomainResourceRec. is shown following.wsdl that describes WSDomainResourceRec. Request and Response Messages The portion of Deletes. <wsdl:operation name="deleteDomainResourceRecord" parameterOrder="inpRR"> <wsdl:input message="impl:deleteDomainResourceRecordRequest" name="deleteDomainResourceRecordRequest"/> <wsdl:output message="impl:deleteDomainResourceRecordResponse" name="deleteDomainResourceRecordResponse"/> </wsdl:operation> <wsdl:message name="deleteDomainResourceRecordRequest"> <wsdl:part name="inpRR" type="tns2:WSDomainResourceRec"/> </wsdl:message> <wsdl:message name="deleteDomainResourceRecordResponse"> </wsdl:message> Response There is no data in the response. DeleteDomainResourceRecord Elem ent Accepted Values Required TTL Time To Live No comment Ignored data The RData portion of the record to delete. Ignored No -81 Domain type not found: domainType The owner field of the record to be deleted. No resourceRecType The type of resource record being deleted Yes Other returnCodes and faultstrings ReturnCode Faultstring -2 Exception reading domain or resource record (database error) -124 DNS Resource record not found -125 DNS Resource record not unique 401 <401>Unauthorized Application Program Interfaces (API) 337 . domain The name of the domain for this resource record domainType id Owner Return Code Faultstring Yes -91 Data field required Yes -60 Domain not found: domain -135 Domain required: domain The domain type of the domain. This defaults to “IN”. Defaults to “Default”. This must match the RData exactly. Yes -89 Owner field required -134 Invalid character in Owner owner -90 Type field required -92 Unknown type: type resourceRecClass The Resource Record class. This must match exactly. <wsdl:operation name="deleteNetElement" parameterOrder="inpNE"> <wsdl:input message="impl:deleteNetElementRequest" name="deleteNetElementRequest"/> <wsdl:output message="impl:deleteNetElementResponse" name="deleteNetElementResponse"/> </wsdl:operation> <wsdl:message name="deleteNetElementRequest"> <wsdl:part name="inpNE" type="tns1:WSNetElement"/> </wsdl:message> </wsdl:message> <wsdl:message name="deleteNetElementResponse"> </wsdl:message> Response There is no data in the response. Parameters WSetElement The portion of Deletes. The elements are described in the table that follows. the parameter structure passed to DeleteNetElement.DeleteNetElement DeleteNetElement Overview The DeleteNetElement API enables the web service client to delete network element from IPControl. Only the first two elements are used for this API. Request and Response Messages The portion of Deletes. is shown following. Request The complex type WSNetElement .wsdl that describes WSNetElement. <complexType <sequence> <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element <element name="WSNetElement"> name="agentName" nillable="true" type="soapenc:string"/> name="authPassword" nillable="true" type="soapenc:string"/> name="globalSync" nillable="true" type="soapenc:string"/> name="interfaceNameList" nillable="true" type="impl:ArrayOf_soapenc_string"/> name="ipAddress" nillable="true" type="soapenc:string"/> name="model" nillable="true" type="soapenc:string"/> name="name" nillable="true" type="soapenc:string"/> name="readCommunityString" nillable="true" type="soapenc:string"/> name="telnetPassword" nillable="true" type="soapenc:string"/> name="telnetUser" nillable="true" type="soapenc:string"/> name="threshold" nillable="true" type="soapenc:string"/> name="type" nillable="true" type="soapenc:string"/> name="v3AuthPassword" nillable="true" type="soapenc:string"/> name="v3AuthProtocol" nillable="true" type="soapenc:string"/> name="v3ContextName" nillable="true" type="soapenc:string"/> name="v3EngineId" nillable="true" type="soapenc:string"/> name="v3PrivacyPassword" nillable="true" type="soapenc:string"/> name="v3PrivacyProtocol" nillable="true" type="soapenc:string"/> name="vendor" nillable="true" type="soapenc:string"/> 338 IPControl CLI and API Guide .wsdl that describes the deleteNetElement request and response messages is shown following. is described in the next section. which is passed as input from the client to the web service. Yes.DeleteNetElement </sequence> </complexType Elem ent Accepted Values Required Return Code Faultstring name The name of the Network Element. unless a unique IP address is specified -33 Network element not found by name: name -35 Network Element Name is required (indicates null input) Yes. Other returnCodes and faultstrings ReturnCode Faultstring -2 Exception reading network element record (database error) 401 <401>Unauthorized Application Program Interfaces (API) 339 . This must be a valid IPv4 or IPv6 IP address. or a full-qualified host name. This can be any combination of letters and numbers. not unique by ip address: addr ipAddress The IP address or fully-qualified domain name (FQDN) of the Network Element. unless the name is specified -33 Network element not found by ip address: addr -28 Specify network element name. wsdl that describes the deleteNetElementInterface request and response messages is shown following. Request The complex type WSNetElementInterface . Request and Response Messages The portion of Deletes. Parameters WSNetElementInterface The portion of Deletes. is shown following. However. <wsdl:operation name="deleteNetElementInterface" parameterOrder="inpNEI"> <wsdl:input message="impl:deleteNetElementInterfaceRequest" name="deleteNetelementInterfaceRequest"/> <wsdl:output message="impl:deleteNetElementInterfaceResponse" name="deleteNetelementInterfaceResponse"/> </wsdl:operation> <wsdl:message name="deleteNetElementInterfaceRequest"> <wsdl:part name="inpDev" type="tns2:WSNetElementInterface"/> </wsdl:message> <wsdl:message name="deleteNetElementInterfaceResponse"> </wsdl:message> Response There is no data in the response. The elements are described in the table that follows. is described below. which is passed as input from the client to the web service. this is the same structure that is passed to ImportNetElementInterface. For consistency. <complexType name="WSNetElementInterface"> <sequence> <element name="id" nillable="true" type="soapenc:int"/> <element name="interfaceName" nillable="true" type="soapenc:string"/> <element name="netElementName" nillable="true" type="soapenc:string"/> <element name="status" nillable="true" type="soapenc:string"/> </sequence> </complexType> 340 IPControl CLI and API Guide . only two of the fields are used. the parameter structure passed to DeleteNetElementInterface.DeleteNetElementInterface DeleteNetElementInterface Overview The DeleteNetElementInterface API enables the web service client to delete network element interfaces from IPControl.wsdl that describes WSNetElementInterface. This can be one of “Disabled”. -20 Network Element Interface Name is required -33 Network element not found: netelement -35 Network Element name is required -34 Invalid interface status: status Application Program Interfaces (API) 341 . The status of the interface. No interfaceName The name of the interface being added or modified. the interface with the matching identifier is updated. or “Deployed”. The default on an import is “Enabled”. Yes netElementName status The name of a Network Element already defined to IPControl. “Enabled”. If this is not set. Yes No Return Code Faultstring -39 Cannot delete interface: interface for network element: name because there are blocks attached.DeleteNetElementInterface Elem ent Accepted Values Required id The internal identifier for this network element interface object. a new interface is created. If this is set. Request and Response Messages The portion of Deletes. Request The complex type WSNetService. is described below. Parameters WSNetService The portion of Deletes. the parameter structure passed to DeleteNetService. <complexType name="WSNetService"> <sequence> <element name="agentName" nillable="true" type="soapenc:string" /> <element name="collectionMethod" nillable="true" type="soapenc:string" /> <element name="collectionPort" nillable="true" type="soapenc:string" /> <element name="container" nillable="true" type="impl:ArrayOf_soapenc_string" /> <element name="globalSync" nillable="true" type="soapenc:string" /> <element name="ipAddress" nillable="true" type="soapenc:string" /> <element name="name" nillable="true" type="soapenc:string" /> <element name="threshold" nillable="true" type="s oapenc:string" /> <element name="type" nillable="true" type="soapenc:string" /> <element name="userName" nillable="true" type="soapenc:string" /> <element name="userPassword" nillable="true" type="soapenc:string" /> <element name="vendor" nillable="true" type="soapenc:string" /> <element name="vendorInfo" nillable="true" type="impl:ArrayOf_soapenc_string"/> </sequence> </complexType> 342 IPControl CLI and API Guide . <wsdl:operation name="deleteNetService" parameterOrder="inpNS"> <wsdl:input message="impl:deleteNetServiceRequest" name="deleteNetServiceRequest"/> <wsdl:output message="impl:deleteNetServiceResponse" name="deleteNetServiceResponse"/> </wsdl:operation> <wsdl:message name="deleteNetServiceRequest"> <wsdl:part name="inpNS" type="tns1:WSNetService"/> </wsdl:message> <wsdl:message name="deleteNetServiceResponse"> </wsdl:message> Response There is no data in the response. Only the first two elements are used for this API.wsdl that describes the deleteNetService request and response messages is shown following. which is passed as input from the client to the web service. is shown following.DeleteNetService DeleteNetService Overview The DeleteNetService API enables the web service client to delete network service from IPControl.wsdl that describes WSNetService. The elements are described in the table that follows. DeleteNetService Elem ent Accepted Values Required Return Code Faultstring name The name of the Network Service Yes -185 Network Service not found for name:name with type: type -186 Network Service Name is required (indicates null input) -187 Invalid network service type: type type The type of Network Service. dhcp is assumed. No Other returnCodes and faultstrings ReturnCode Faultstring -2 Exception reading network service record (database error) 401 <401>Unauthorized Application Program Interfaces (API) 343 . If this column is left blank. wsdl that describes the DeletePrefixPool request and response messages is shown following. However. are described in the next section. which are passed as input from the client to the web service. Request The complex types WSPrefixPool. is shown following. the parameter structure passed to DeletePrefixPool. For consistency.wsdl that describes WSPrefixPool.DeletePrefixPool DeletePrefixPool Overview The DeletePrefixPool API enables the web service client to delete Prefix Pools from IPControl. The elements are described in the table that follows. only two of the fields are used. these are the same structures that are passed to ImportPrefixPool. This will also delete the Delegated Prefixes inside the Prefix Pool. Request and Response Messages The portion of Deletes. <wsdl:operation name="deletePrefixPool" parameterOrder="inpPrefixPool"> <wsdl:input message="impl:deletePrefixPoolRequest" name="deletePrefixPoolRequest"/> <wsdl:output message="impl:deletePrefixPoolResponse" name="deletePrefixPoolResponse"/> </wsdl:operation> <wsdl:message name="deletePrefixPoolRequest"> <wsdl:part name="inpPrefixPool" type="tns2:WSPrefixPool"/> </wsdl:message> <wsdl:message name="deletePrefixPoolResponse"> </wsdl:message> Response There is no data in the response. <complexType name="WSPrefixPool"> <sequence> <element name="allowClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="container" nillable="true" type="soapenc:string"/> <element name="delegatedPrefixLength" nillable="true" type="soapenc:int"/> <element name="denyClientClasses" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="dhcpOptionSet" nillable="true" type="soapenc:string"/> <element name="dhcpPolicySet" nillable="true" type="soapenc:string"/> <element name="id" nillable="true" type="soapenc:int"/> <element name="length" nillable="true" type="soapenc:int"/> <element name="longestPrefixLength" nillable="true" type="soapenc:int"/> <element name="name" nillable="true" type="soapenc:string"/> <element name="primaryNetService" nillable="true" type="soapenc:string"/> <element name="shortestPrefixLength" nillable="true" type="soapenc:int"/> <element name="startAddr" nillable="true" type="soapenc:string"/> <element name="type" nillable="true" type="soapenc:string"/> </sequence> </complexType> 344 IPControl CLI and API Guide . Parameters WSPrefixPool The portion of Deletes. DeletePrefixPool Elem ent Accepted Values Required Return Code Faultstring Name String Yes -262 Prefix Pool Not found Start Address String Yes -262 Prefix Pool Not found Other returnCodes and faultstrings ReturnCode Faultstring -2 Exception processing delete (database error) -99 Access Denied Application Program Interfaces (API) 345 . Any tasks older than this date are deleted.wsdl that describes the DeleteTaskByDate request and response messages is shown following. <wsdl:operation name="deleteTaskByDays" parameterOrder="before"> <wsdl:input message="impl:deleteTaskByDateRequest" name="deleteTaskByDateRequest"/> <wsdl:output message="impl:deleteTaskByDateResponse" name="deleteTaskByDateResponse"/> </wsdl:operation> <wsdl:message name="deleteTaskByDateRequest"> <wsdl:part name="before" type="xsd:dateTime"/> </wsdl:message> <wsdl:message name="deleteTaskByDateResponse"> <wsdl:part name="deleteTaskByDateReturn" type="xsd:int"/> </wsdl:message> Response The count of tasks deleted is returned. Request The request takes one parameter which is a date. Request and Response Messages The portion of Deletes.DeleteTaskByDate DeleteTaskByDate Overview The DeleteTaskByDate API enables the web service client to delete tasks from IPControl that are older than a given date. Parameters Elem ent Accepted Values Required Return Code Faultstring Before Date/Time Yes -107 Missing Date -110 Invalid Date 346 IPControl CLI and API Guide . Request The request takes one parameter which is the number of days of tasks to retain.DeleteTaskByDays DeleteTaskByDays Overview The DeleteTaskByDays API enables the web service client to delete tasks from IPControl that are older than a given number of days. Request and Response Messages The portion of Deletes.wsdl that describes the DeleteTaskByDays request and response messages is shown following. Any task s older than the current date minus this parameter are deleted. Yes -109 Invalid Days value Application Program Interfaces (API) 347 . Parameters Elem ent Accepted Values Required Return Code Faultstring Days A positive integer. <wsdl:operation name="deleteTaskByDays" parameterOrder="days"> <wsdl:input message="impl:deleteTaskByDaysRequest" name="deleteTaskByDaysRequest"/> <wsdl:output message="impl:deleteTaskByDaysResponse" name="deleteTaskByDaysResponse"/> </wsdl:operation> <wsdl:message name="deleteTaskByDaysRequest"> <wsdl:part name="days" type="xsd:int"/> </wsdl:message> <wsdl:message name="deleteTaskByDaysResponse"> <wsdl:part name="deleteTaskByDaysReturn" type="xsd:int"/> </wsdl:message> Response The count of tasks deleted is returned. Each integer is a Task ID.DeleteTaskById DeleteTaskById Overview The DeleteTaskByID API enables the web service client to delete one or more tasks from IPControl. which is an array of integers. Parameters Elem ent Accepted Values Required Return Code Faultstring ids The Task IDs to delete. Request and Response Messages The portion of Deletes.wsdl that describes the DeleteTaskById request and response messages is shown following. one per element in the array. Yes -106 Task Not found -108 Missing IDs 348 IPControl CLI and API Guide . <wsdl:operation name="deleteTaskById" parameterOrder="ids"> <wsdl:input message="impl:deleteTaskByIdRequest" name="deleteTaskByIdRequest"/> <wsdl:output message="impl:deleteTaskByIdResponse" name="deleteTaskByIdResponse"/> </wsdl:operation> <wsdl:message name="deleteTaskByIdRequest"> <wsdl:part name="ids" type="impl:ArrayOf_soapenc_int"/> </wsdl:message> <wsdl:message name="deleteTaskByIdResponse"> <wsdl:part name="deleteTaskByIdReturn" type="xsd:int"/> </wsdl:message> Response The count of tasks deleted is returned. Request The request takes one parameter. which is passed as input from the client to the web service. Request and Response Messages The portion of Deletes. is shown following. <complexType name="WSDnsZone"> <sequence> <element name="MNAME" nillable="true" type="soapenc:string"/> <element name="acceptZoneTransfers" nillable="true" type="soapenc:string"/> <element name="aliasZone" type="xsd:boolean"/> <element name="allowUpdateACL" nillable="true" type="soapenc:string"/> <element name="autogenNSGlue" nillable="true" type="soapenc:string"/> <element name="domainName" nillable="true" type="soapenc:string"/> <element name="domainType" nillable="true" type="soapenc:string"/> <element name="dynamicZone" type="xsd:boolean"/> <element name="filename" nillable="true" type="soapenc:string"/> <element name="galaxyName" nillable="true" type="soapenc:string"/> <element name="masters" nillable="true" type="soapenc:string"/> <element name="server" nillable="true" type="soapenc:string"/> <element name="templateZone" type="xsd:boolean"/> <element name="updatePolicy" nillable="true" type="soapenc:string"/> <element name="updateZone" nillable="true" typ e="soapenc:string"/> <element name="view" nillable="true" type="soapenc:string"/> <element name="zoneExtensionsAfter" nillable="true" type="soapenc:string"/> <element name="zoneExtensionsPrior" nillable="true" type="soapenc:string"/> <element name="zoneType" nillable="true" type="soapenc:string"/> </sequence> </complexType> Application Program Interfaces (API) 349 . the parameter structure passed to DeleteZone. Request The complex type WSDnsZone. <wsdl:message name="deleteZoneRequest"> <wsdl:part name="inpZone" type="tns2:WSDnsZone"/> </wsdl:message> <wsdl:message name="deleteZoneResponse"> </wsdl:message> Response There is no data in the response.wsdl that describes the deleteZone request and response messages is shown following.wsdl that describes WSDnsZone. Parameters WSDnsZone The portion of Deletes.DeleteZone DeleteZone Overview The DeleteZone API enables the web service client to delete zones from IPControl. is described in the next section. The elements are described in the table that follows. when not “Default”. the “Default” domain type will be used. dynamicZone Ignored Yes. Faultstring -135 Domain required -60 Domain not found: domainType/domain -81 Domain type not found: domainType No filename view Return Code Yes.DeleteZone Elem ent Description and accepted values Required MNAME Ignored acceptZoneTransfers Ignored No No aliasZone Ignored No allowUpdateACL Ignored No autogenNSGlue Ignored No domainName Domain name for the zone.Exception reading domain or domain type record (database error) -88 Zone not found: domainName / domainType / server / view -99 Access denied 350 IPControl CLI and API Guide . Yes templateZone Ignored No updatePolicy Ignored No updateZone Ignored No zoneExtensionsAfter The name of the view in which the zone exists. Ignored No galaxyName Ignored No masters Ignored No server The network service name of the DNS Server for the zone. If not specified. Yes domainType Domain type of the domain for the zone. when not “Default”. ‘Default’ will be used. If not specified. No zoneExtensionsPrior Ignored Ignored zoneType Ignored No -235 Server name required -93 Server not found: server -58 View not found: view No Other returnCodes and faultstrings ReturnCode Faultstring -2 Various . <wsdl:operation name="deleteZoneResourceRecord" parameterO rder="inpRR"> <wsdl:input message="impl:deleteZoneResourceRecordRequest" name="deleteZoneResourceRecordRequest"/> <wsdl:output message="impl:deleteZoneResourceRecordResponse" name="deleteZoneResourceRecordResponse"/> </wsdl:operation> <wsdl:message name="deleteZoneResourceRecordRequest"> <wsdl:part name="inpRR" type="tns2:WSZoneResourceRec"/> </wsdl:message> <wsdl:message name="deleteZoneResourceRecordResponse"> </wsdl:message> Response There is no data in the response. Parameters WSResourceRecord The portion of Deletes.wsdl that describes the deleteZoneResourceRecord request and response messages is shown following. is shown following. which is passed as input from the client to the web service.wsdl that describes WSZoneResourceRec. The elements are described in the table that follows. Request The complex type WSZoneResourceRec. <complexType name="WSZoneResourceRec"> <sequence> <element name="TTL" nillable="true" type="soapenc:string"/> <element name="data" nillable="true" type="soapenc:string"/> <element name="owner" nillable="true" type="soapenc:string"/> <element name="resourceRecClass" nillable="true" type="soapenc:string"/> <element name="resourceRecType" nillable="true" type="soapenc:string"/> <element name="server" nillable="true" type="soapenc:string"/> <element name="view" nillable="true" type="soapenc:string"/> <element name="zone" nillable="true" type="soapenc:string"/> </sequence> </complexType> Application Program Interfaces (API) 351 . Request and Response Messages The portion of Deletes. the parameter structure passed to DeleteZoneResourceRecord. is described below.DeleteZoneResourceRecord DeleteZoneResourceRecord Overview The DeleteZoneResourceRecord API enables the web service client to delete resource records from IPControl that are affiliated with a zone. These are specialized resource records. known as “glue” records. This defaults to “IN”.DeleteZoneResourceRecord Elem ent Accepted Values Required Return Code Faultstring TTL Time To Live No Data The RData portion of the record to delete. This must match exactly. Yes -91 Data field required Owner The owner field of the record to be deleted. Defaults to “Default”. . Yes 352 IPControl CLI and API Guide -88 Zone not found. No zone The Name of the zone in which the resource record exists. No resourceRecType “A” or “NS” Yes -90 Type field missing -92 Type field invalid server The DNS Server that serves the zone Yes view The DNS View in which the zone resides. Yes -89 Owner field required resourceRecClass The Resource Record class. This must match the RData exactly. or as name-value pairs. For example. The file is written as XML. The Callout Manager’s properties file can be found in $INCHOME/callout_manager.txt]. the user script must delete the temporary file passed to it.txt]. When building your scripts.Other Interfaces Callout Manager The Callout Manager is a facility within IPControl that notifies other applications of alerts and programmatic events. Execute the script that is configured for this event. The properties file contains directives that control the Callout Manager behavior. Examples of Callout Manager uses are: Interfacing to other Alert Management facilities Automating Router or DHCP configuration Performing off-line auditing Operation The Callout Manager performs the following functions: Receive a message (via JMS) from the other IPControl components Inspects the message to determine the event type Takes the data supplied with the event and writes it to a temporary file. then your defined output would be written to C:\Program Files\Diamond IP\InControl\etc on Windows. passing it the name of the temporary file. Configuration The Callout Manager is configured through a text file known as a “properties” file. Hence. the callout manager simply waits. if your script had [echo ‘hello world’ > output. or /opt/incontrol/etc on Solaris or Linux.properties. as dictated by the configuration (see below). Any Other Interfaces 353 . if you do not specify fully qualify output paths. When the message queue is empty. rather than [echo ‘hello world’ > /opt/incontrol/tmp/out. then the output. Assuming that path is where you installed InControl.txt file would be found under /opt/incontrol/etc. Note that the callout manager does not wait for the user script to complete. output. If true.names Yes Specifies the JMS Queue Name.count Yes Specifies the number of threads for receiving callout messages. and specify a custom path and script name.connections.path No Specifies the directory where the temporary files will be created for the events. the file contains XML.name Yes Specifies the Java class that manages the Queue creation.connections.reconnect. This should not be changed from its shipped value.Other Interfaces changes made to this file require that the Callout Manager service be restarted for the changes to take effect.callout. Should not be changed from its shipped value. Defaults to $INCHOME/tmp.connections. Should not be changed from its shipped value queue. alertcallout No The name of the command to execute when an alert is raised. on Windows. On Solaris or Linux. an example of the property value would be /opt/incontrol/bin/alertcallout.callout. If false (default).retry Yes Specifies the reconnection retry count if the Callout manager is disconnected from JMS.callout. The following table lists those properties.reconnect.factory.properties that you want to use and uncomment it (remove the # in front of the line). If specified.add = /opt/scripts/blockadd_callout.thread.connections. Should not be changed from its shipped value.connections. an example of the property value would be c:\\Program Files\\Diamond IP\\InControl\\bin\\alertcallout. For example: block.sh Property Required Description log.filename Yes Specifies the name of the file that holds the logging directives.xml No Specifies the format of the temporary file. the string must end with a path separator.callout. 354 IPControl CLI and API Guide . the file contains name=value pairs.config. queue. output. queue. Should not be changed from its shipped value. Locate the property or properties within callout_manager.bat. For example.delay Yes Specifies the retry interval should the Callout Manager be disconnected from JMS. queue.sh. queue. add No The name of the command to execute when a block is added to IPControl. On Solaris or Linux. an example of the property value would be c:\\Program Files\\Diamond IP\\InControl\\bin\\ devicemodify_callout.sh Other Interfaces 355 .Other Interfaces Property Required Description block. an example of the property value would be c:\\Program Files\\Diamond IP\\InControl\\bin\\ blockdelete_callout. an example of the property value would be /opt/incontrol/bin/deviceadd_callout. For example.bat.modify No The name of the command to execute when a device is modified within the IPControl GUI. on Windows. block. For example.s h device. block.bat.sh.add No The name of the command to execute when a device is added within the IPControl GUI.sh device. on Windows.bat. On Solaris or Linux.bat. an example of the property value would be c:\\Program Files\\Diamond IP\\InControl\\bin\\ deviceadd_callout. an example of the property value would be /opt/incontrol/bin/blockmodify_callout.delete No The name of the command to execute when a block is deleted within IPControl. On Solaris or Linux. For example. an example of the property value would be /opt/incontrol/bin/blockadd_callout. an example of the property value would be /opt/incontrol/bin/devicemodify_callout . For example.modify No The name of the command to execute when a block is modified within IPControl. on Windows. sh. an example of the property value would be /opt/incontrol/bin/blockdelete_callout. an example of the property value would be c:\\Program Files\\Diamond IP\\InControl\\bin\\ blockmodify_callout. on Windows. an example of the property value would be c:\\Program Files\\Diamond IP\\InControl\\bin\\ blockadd_callout. For example. On Solaris or Linux.bat. On Solaris or Linux. on Windows. a message containing the details of the event is sent to the Callout Manager. Configuring the script is performed as indicated above. This allows the administrator to provide scripts which send a notification to the appropriate party when certain appliance events warrant it. whereas the second event identifies the state of the DNS server as determined by the IPControl monitoring software. On Solaris or Linux.Other Interfaces Property Required Description device. bat. as desired. For example.stopped = /opt/incontrol/bin/dnsstoppped_callout. an example of the property value would be /opt/incontrol/bin/taskcomplete_callout. A script can be configured for each individual event message. by providing the property name and callout script name-value pair in the $INCHOME/callout_manager.category. For example. or at the category or source level. On Solaris or Linux. The administrator can choose to provide a script for one or both events.s h task. Specifically. sh Appliance Events The Sapphire Appliance logs several event messages to the IPControl database.status.sh 356 IPControl CLI and API Guide . the events included are those that are listed on the Details screen from the Appliance Dashboard. As each event is logged to the database. on Windows.delete No The name of the command to execute when a device is deleted within the IPControl GUI.bat. For example: dnsserver.action. Scripts are configured in the Callout Manager’s properties file. The types of events which are logged include starting and stopping of services and changes in state of any monitored service. on Windows. The property name that identifies the event is of the form source. as indicated above.message. if an administrator were to stop the DNS server on a Sapphire Appliance through the Manage link of the Appliance Dashboard.down The first event identifies the action performed by the administrator. as needed.properties file.stopped dnsserver.action. For example.status. an example of the property value would be c:\\Program Files\\Diamond IP\\InControl\\bin\\ devicedelete_callout. two events would be logged: dnsserver.complete No The name of the command to execute when a task is launched with the IPControl GUI. an example of the property value would be c:\\Program Files\\Diamond IP\\InControl\\bin\\taskcomplete_out.sh dnsserver. an example of the property value would be /opt/incontrol/bin/devicedelete_callout.down = /opt/incontrol/bin/dnsdown_callout. Finally. This includes all action (stopped. the scripts could be configured at the category level of the event. all DNS server events would be handled by the dnsevent_callout.1 . running) events. For example: dnsserver = /opt/incontrol/bin/dnsev ent_callout. The contents of the XML or name-value pair file that is passed to the script contains the details.Appliance Details in the IPControl User Guide for a complete.sh In this case. running) would be handled by the dnsstatus_callout.Other Interfaces This configuration provides individual scripts for specific event messages.11.status = /opt/incontrol/bin/dnsstatus_callout.sh script.action = /opt/incontrol/bin/dnsaction_callout. to allow the script to provide its own conditional processing based on the particular event. Please refer to section 5. and all status events (down. detailed list of all appliance events. the source.sh script. Alternatively. Other Interfaces 357 . started) and status (down. and message.sh In this case. all action events (stopped. category.sh dnsserver. the script mapping can be provided at the highest level of the event. which include the source. For example: dnsserver.sh script. started) would be handled by the dnsaction_callout. ) block.arin.add = /opt/nc/etc/callout/addSwip. this should be reassign@arin. For a Reassign – Simple template. The scripts include the ability to automatically send an email with the appropriate content to the RIR. visit the ARIN and/or RIPE websites at http://www.pl block. customer_state No Specifies the default state for the customer being assigned this block. To configure the callout manager to call the SWIP scripts on these events. Property Required Description from_address Yes The email address of the sender of the template email. (The examples assume that $INCHOME = /opt/nc.Simple template. customer_country_code No Specifies the default country code for the customer being assigned this block. This includes templates for ARIN and RIPE.properties. modify the following properties in the $INCHOME/callout_manager.net.properties file. The Callout Manager can be configured to call these scripts on each Add.ripe. The default properties are stored in a properties file called $INCHOME/etc/callout/swip.net. customer_address No Specifies the default street address for the customer being assigned this block. commonly referred to as a SWIP (Shared WhoIs Project) template. Delete.pl block. to_address Yes The email address of the recipient of the email address.Other Interfaces RIR Template Support Introduction IPControl includes support for creating a limited set of Regional Internet Registry (RIR) templates that can be electronically mailed to the appropriate registry. Typically.modify = /opt/nc/etc/callout/modifySwip. customer_city No Specifies the default city for the customer being assigned this block. 358 IPControl CLI and API Guide .delete = /opt/nc/etc/callout/deleteSwip. For further details about RIR templates. Configuration ARIN File Generation IPControl provides a set of sample scripts that can be used.pl The scripts can be configured with default information to be used when generating the data files. This support is provided via sample scripts that can be called via the IPControl Callout Manager. to generate the proper ARIN Reassign . customer_postal_code No Specifies the default postal code for the customer being assigned this block. The following table lists those properties. via the Callout Manager. this should be “REASSIGN SIMPLE” customer_name No Specifies the default name of the customer to which the block has been reassigned.net or http://www. or Modify of a block within IPControl. subject No The subject of the email. orgname No Specifies the text that will appear in the “descr” field of the in inetnum (or inet6num) templates. Delete.pl The scripts can be configured with default information to be used when generating the data files. All inetnum objects under APNIC Whois Database must have a status attribute. This corresponds to the “tech-c” field in the inetnum (or inet6num) template. (The examples assume that $INCHOME = /opt/nc. The Callout Manager can be configured to call these scripts on each Add. this should be
[email protected] file. This corresponds to the “notify” field in the inetnum (or inet6num) template.properties. To configure the callout manager to call the RIPE scripts on these events. These templates are used to update the RIPE database directly via email.net. modify the following properties in the $INCHOME/callout_manager.modify = /opt/nc/etc/callout/modifyRipe. via the Callout Manager. status No Specifies the default values of the status field in the inetnum or inet6num templates. The status attribute must be one of the following values: ALLOCATED PORTABLE ALLOCATED NON-PORTABLE ASSIGNED PORTABLE ASSIGNED NON-PORTABLE Other Interfaces 359 . revsrv No Specifies the reverse server address for this address space. The following table lists those properties.Other Interfaces RIPE File Generation IPControl provides a set of sample scripts that can be used. to generate the proper RIPE inetnum or inet6num templates.delete = /opt/nc/etc/callout/deleteRipe.pl block. or Modify of a block within IPControl.add = /opt/nc/etc/callout/addRipe. The default properties are stored in a properties file called $INCHOME/etc/callout/ripe. Property from_address Required Yes Description The email address of the sender of the template email. The status attribute must be one of the following values: UNSPECIFIED ALLOCATED PORTABLE ALLOCATED NON-PORTABLE ASSIGNED PORTABLE ASSIGNED NON-PORTABLE All inet6num objects under APNIC Whois Database must have a status attribute. techc No Specifies the email address of the technical contact for this address space. Typically this is the name of the organization that will use the address space. This corresponds to the “admin-c” field in the inetnum (or inet6num) template.pl block. Typically. notify No Specifies the email address of the RIPE contact for this address space. to_address Yes The email address of the recipient of the email address.) block. adminc No Specifies the email address of the administrative contact for this address space. This corresponds to the “rev-srv” field in the inetnum (or inet6num) template. it will attempt to send an email to the address specified in the to_address field. then the scripts will proceed with creating a Reassign-Simple template for adding. This is either “RIPE” or a designation for the NIR. source The name of the database from which the data was obtained. Operation ARIN File Generation Scripts In order to support the automatic file generation of ARIN SWIP templates and emails.properties file. This will be placed in the “Delete:” field. or deleted and they are addSwip. mntirt The name of an irt object that represents a Computer Security Incident Response Team (CSIRT) that handles security incidents for the address space specified by the inetnum object. the scripts are provided as examples.pl. In these cases.pl. After creating the template. delete_reason The default text to use when deleting an address space. changed The email address of who last updated the database object and the date it occurred. If the property is present and is non-empty. LIR or ISP that allocates/assigns the address. remarks General remarks. Although fully functional. May include a URL or instructions on where to send abuse complaints. They accept as their first argument a filename. if a delete has taken place. The changed attribute is not a network contact address. as defined in the swip. (For information on configuring the Callout Manager to perform these tasks please see the section above called Configuration – ARIN File Generation. modifySwip.) All of the scripts are written in PERL and require that PERL 5 be installed and configured on the IPControl Executive system by the system administrator. The key decision point is the presence of a property called swipname in the data file. or deleting an address space.Other Interfaces Property mntby Required Description The default value to use as the identifier of a registered mntner object used for authorization and authentication. modified.pl. PERL 5 is NOT supplied with IPControl. This field specifies the default value to use. 360 IPControl CLI and API Guide . The scripts parse this file to pull out any required data and decide whether or not to proceed with the template processing. This filename should point to a file that contains block information formatted as name-value pairs. as it merely records who made the most recent change to the registration information. modifying. there are three scripts that can get called by the Callout Manager when a block is added. All RIPE addresses will initially record an RIPE address in this attribute. mnt-lower is used as well as mnt-by. password The default password to use if the either the CRYPT-PW or MD5 authentication is used with the mntner object. and deleteSwip. mntroutes The identifier of a registered mntner object used to control the creation of route objects associated with the address range specified by the inetnum (or inet6num) object. as RIPE creates the first database object. The ARIN scripts all operate in a similar fashion. mntlower Sometimes there is a hierarchy of maintainers. Expected User Defined Field Mappings The SWIP Perl scripts expect to make use of both standard and User Defined Fields.pl. it will attempt to send an email to the address specified in the toaddress field. The scripts parse this file to pull out any required data and decide whether or not to proceed with the template processing. and deleteRipe. This filename should point to a file that contains block information formatted as name-value pairs.) All of the scripts are written in PERL and require that PERL 5 be installed and configured on the IPControl Executive system by the system administrator. The key decision point is the presence of a property called “swipname” in the data file. Note: All scripts delete the data file before exiting. Other Interfaces 361 .Other Interfaces Note: All scripts delete the data file before exiting. the scripts are provided as examples.properties file. The following table shows a mapping of the fields used by the scripts and their relation to the standard and User Defined Fields. or deleting an address space. as defined in the ripe. or deleted and they are addRipe. (For information on configuring the Callout Manager to perform these tasks please see the section above called Configuration – RIPE File Generation. then the scripts will proceed with creating an inetnum or inet6num template for adding.pl.pl. there are three scripts that can get called by the Callout Manager when a block is added. modified. Expected User Defined Field Mappings The RIPE Perl scripts expect to make use of both standard and User Defined Fields. PERL 5 is NOT supplied with IPControl. They accept as their first argument a filename. modifyRipe. After creating the template. The following table shows a mapping of the fields used by the scripts and their relation to the standard and User Defined Fields. If the property is present and is non-empty. NC Tags SWIP Field UDF startaddrstring / blocksize IP Address and Prefix N swipname Network-Name N org_name Customer Name Y street_address Customer Address Y city Customer City Y state Customer State Y postal_code Customer Postal Code Y country_code Customer Country Code Y public_comments Public Comments Y RIPE File Generation Scripts In order to support the automatic file generation of RIPE inetnum or inet6num templates and emails. The RIPE scripts all operate in a similar fashion. Although fully functional. modifying. Other Interfaces NC Tags RIPE Field UDF startaddrstring .endaddrstring inetnum (or inet6num) N swipname netname N orgname descr Y country_code country Y admin_contact admin-c Y tech_contact tech-c Y rev_srv rev-srv Y status status Y remarks remarks Y notify notify Y mntby mnt-by Y mntlower mnt-lower Y mntroutes mnt-routes Y changed changed Y source source Y 362 IPControl CLI and API Guide . 3. either Start or Stop. 6. 5. 1. If you require it to listen on another port. Resource records are processed using rules specific to each resource record’s Type field. you must run the Listener as root so that the process can access privileged ports.properties>] Stopping the DNSListener on Unix $INCHOME/etc/dl_stop Starting or Stopping DNSListener via Windows GUI Follow these steps. Scroll down to InControl DNS Listener. edit the dns_listener. Double-click on Administrative Tools. It does this by sequentially reading each resource record contained in an IXFR. 3. 2. Choose which status you want. processing each one according to a set of rules described below. Click on Start -> Control Panel -> Administrative Tools. Right-click on InControl DNS Listener. Other Interfaces 363 . The DNS Listener process imports DNS resource records collected via an incremental zone transfer (IXFR) from a DNS server into IPControl. 4. 2. Configuration Configure the DNS Listener Make sure the listener is not running by using the appropriate stop command (see “Usage” above). 1. Start the DNS Listener by using the appropriate start command (see “Usage” above). and then inserting some portion of the resulting data into IPControl. The type-specific rules are listed in detail further down in this appendix. Double-click on Services. Usage Starting the DNSListener on Unix $INCHOME/etc/dl_start [-c <listener. The Listener listens on port 5053 by default. Note: For the Listener to listen on a port numbered from 1-1023 on UNIX.properties file.Other Interfaces DNS Listener The DNS Listener process can dynamically collect information from DNS servers about updates to zones and import this information into IPControl. 168. 1.com. 4.example”.192”.1 port 5053. file “db. add the also-notify option to the zones that you want IPControl to stay synchronized with. 3.0.168. }.conf.com.0.168.192. Right click on the name of the zone that you want to keep synchronized in IPControl and select Properties from the menu.in-addr.1 port 5053. next to the machine icon to open the zones that server is responsible for.192.” { type master.0. 364 IPControl CLI and API Guide . zone “example.1 on port 5053 when it updates zones example. also-notify { 192. also-notify { 192. }. For example. Click the plus symbol '+'.Other Interfaces Configure DNS BIND 8. the alsonotify option in this file would cause bind to send notify messages to the address 192. }. }. Microsoft DNS Server Follow these steps.arpa.inaddr. usually /etc/named.0.: Options { directory “/var/lib/named”. zone “0.0 or newer In the BIND configuration file.168. Open the Forward Lookup Zones or Reverse Lookup Zones. notify no.arpa.168. file “db. }. and 0.” { type master. Start the Microsoft DNS Server application: Control Panel->Administrative Tools->DNS 2.168. properties file. and any other DNS servers that you want notified when zones are updated. Other Interfaces 365 . Click on the Zone Transfers tab and then click the Notify. Select The following servers from the radio button group. Click OK. Note: Microsoft DNS can only send Notify messages on port 53.. Add the IP address of the DNS Listener. so the Listener will need to be configured to listen on port 53 by editing the dns_listener.Other Interfaces 4.. 6. button. 5. 7. _msdcs.ins. if no block is defined that contains the address then the address device pair will not be created. SRV The data from SRV records are processed in the same way as other resource records with the exception of the name field.com. All others The domain name that the resource record will be placed in is taken from the name field of the resource record after the left label has been removed.com. leading under-bars are prepended to the labels that describe the service. data from the imported record is used to update the serial number of the domain. if the name field contains the zone name. The name field of SRV records specifies a service available for the domain for which it is a part of._tcp. The service type and protocol is encoded in the left portion of its name field. If the domain is found in IPControl. the host name will be taken from the name field of the resource record. if an address and device is to be created the DNS Listener will use the left most label of the name field as the host portion of the FQDN for the host. with additional fields to the left of the domain name then an IP address and device will be created. If the IP address already exists in a block defined in IPControl and there is no host name associated with the linked device. To avoid collision with the rest of the domain name space. and a device will be created using the name field. MX MX records are imported into IPControl and attached to the domain supplied in the name field.pdc. The service specification part w ould be: _ldap. 600 SRV 0 100 400 pdc. For example in the following SRV record: _ldap.ins. if the name field matches exactly the zone name then no IP address and device will be created.pdc._msdcs and the domain name part would be: sw. 366 IPControl CLI and API Guide . and it is linked to the domain. If the domain can not be found in IPControl processing of the resource record will stop. an IP address will be created using the rdata field.sw. The device and IP address will also be associated with the resource record in addition to the domain. NS NS records are ignored by the DNS Listener daemon. The domain name is taken from the name field of the resource record.ins. if the address found in the rdata field of the resource record can be located within a block defined in IPControl. If the domain does not exist in IPControl processing for that record stops. It considers all the labels to the right of the right-most label that starts with an underscore to be part of the domain name of the SRV record. PTR Data from PTR records is used in the same way as data from A records with the exception that the name and rdata field are swapped when creating an IP address and device. If the domain exists in IPControl.Other Interfaces Record Processing Rules RR Type Description SOA Data from the SOA record is used to update a domain in IPControl. a resource record object is created using the data supplied by the imported record. A Data from A records is used to create resource record entries attached to domains in IPControl and additionally can create individual IP addresses and devices.com. Note that: if a domain name that matches the zone name is not defined in IPControl then processing of the resource record stops. This practice is not always followed in the field and so the DNSImport CLI uses the following rule to determine where the domain name part of the name field starts.sw._tcp. The input thread will then sequentially remove the resource records from the queue and process them as described above. When the number of notify messages exceeds the listener. Both the port the server sends to and the port the listener listens on can be changed as described below. The transfer thread will request an IXFR from the appropriate DNS server.notifythreshold property. The resource record input manager thread is notified when records are placed on the queue. which is a privileged port on most UNIX systems. and the transfer manager is not in the paused state. When the number of records remaining on the queue is less than the listener. Other Interfaces 367 .maxrecords specifies. When this happens the input manager compares the number of records on the queue with the listener.maxrecords property. the transfer manager thread will create and start a transfer thread. but will not start any new transfer threads. When changes are made to the affected zones the DNS server will send a NOTIFY message to the listener. The notify thread is responsible for listening for notify messages from DNS servers. and a short lived thread. When the transfer manager is in the pause state it will continue to process notify messages from the notify thread. See Figure 1. the input manager thread will send a pause message to t he transfer manager thread. If there are more records than the listener. and then exit.maxrecords. In this way IPControl is kept synchronized with the DNS as hosts join and leave the network.Other Interfaces Detailed Description The DNS Listener is a small multi-threaded program that listens for messages from DNS servers. a restart message will be sent to the transfer manager. When the listener receives a NOTIFY message. the notify thread sends a message to the transfer manager thread which increments its count of notify messages for the server. When notified of a change to a zone that a server is responsible for the listener can request detailed information about those changes and then use this information to update IPControl. Notify messages sent by DNS servers are sent to port 53 by default. For this reason the DNS Listener defaults to port 5053. The listener is composed of three long lived threads. one queue. place the resulting resource records on the queue. listener. The default is one NOTIFY message.Other Interfaces Figure 1 – DNS Listener The DNS Listener can use a properties file to set certain operational properties.notifythreshold 368 IPControl CLI and API Guide The number of NOTIFY messages received before the listener attempts an IXFR transfer from the DNS server. The default is 5053 if this property is not supplied. . you must run dl_start as root. Note: For the listener to listen on port 53 on *NIX. The properties are: listener.port The port on which the listener should listen for NOTIFY messages from a DNS server. but only for at most 60 seconds.maxrecords is accepted by the listener via an IXFR further IXFR requests will not be initiated until all records have been processed by the queue processing thread.All Files push) or call rndc (for Selected/Changed Zone Filebased pushes). The agent will report the return code of the script in the task result messages.sh (or %INCHOME%\etc\dns_callout. The agent will wait for the completion of script before moving on.maxrecords High water mark that controls NOTIFY message processing. The name of the script is not configurable. 369 . If more than listener.conf file. The script gets called just before we attempt to Restart the server (on a DNS Config . The default is 1000 records. DNS Deployment Callout When a DNS File-based deployment task is performed and the configuration and data files are placed on the DNS Server. the IPControl Agent has the ability to execute a callout script. that is. the one that resides on the actual DNS server. however it does not interrogate this return value and thus will always continue even if the script fails.cmd for Windows).Other Interfaces listener. The details of this script are as follows: The script is called by the remote agent. The script gets passed one parameter which is the full path name of the new named. It is always $INCHOME/etc/dns_callout. This helps limit the amount of memory the listener can claim at any one time. This field was always ignored by the DeleteAggregateBlock API. This affects the ImportAggregateBlock API.0. the parameter structure passed to importAddrpool: <element name="prefixLength" nillable="true" type="soapenc:string"/> In addition.0.0. WSAllocationTemplateDetails The sharename element of WSAllocationTemplateDetails has been marked for deprecation and will be ignored beginning with IPControl 6.0 WSAddrpool One element was added to WSAddrpool. Refer to the importAddrpool section of the API chapter for more detailed information. This affects the AddSite and ModifyBlock APIs. the sharename element has been marked for deprecation and will be ignored beginning with IPControl 6. 370 IPControl CLI and API Guide .Appendix A API Changes IPControl 6. WSAggregateBlock The interfaceAddress element of WSAggregateBlock has been marked for deprecation and will be ignored beginning with IPControl 6. was modified to be an array: <element name="interfaceAddress" nillable="true" type="impl:ArrayOf_soapenc_string"/> <element name="primarySubnet" type="xsd:boolean"/> Refer to the ImportChildBlock API section of the API chapter for more detailed information. Please refer to the exportDevice section of the API chapter for more detailed information. WSContainer One additional element. Appendix A API Changes 371 . was added to WSChildBlock. hwtype. WSDevice One element was added to WSDevice. and returned by exportDevice and getDevice: <element name="duid" nillable="true" type="soapenc:string"/> Refer to the importDevice section of the API chapter for more detailed information. ipAddress and excludeFromDiscovery. One element. <element name="replaceDHCPServerV6" nillable="true" type="soapenc:string"/> Additional details are described in the ImportContainer API section. was added to WSContainer. Note that devices with only the default interface will export the following fields in the WSInterface structure: MACAddress. primarySubnet. interfaceAddress. the parameter structure passed to importDevice.Appendix A WSChildBlock One element. replaceDHCPServerV6. These fields will no longer be exported as part of the WSDevice structure. This will affect the ModifyContainer CLI as well as the ImportContainer and ExportContainer APIs. This structure is used by the ImportChildBlock. ExportChildBlock and DetachBlockAPIs. WSPrefixPool This is a new structure described in the ImportPrefixPool section of the API chapter. the parameter structure passed to ImportDhcpServer: <element name="v4V6Both" nillable="true" type="soapenc:string"/> Refer to the ImportDhcpServer section of the API chapter for more detailed information. This structure is also used by the deleteZone API. ModifyDhcpServer and GetDhcpServer APIs. WSDnsZone Two elements were added to WSDnsZone. and returned by exportDevice and getDevice: <element name="container" nillable="true type="impl:ArrayOf_soapenc_string"/> <element name="virtual" nillable="true" impl:ArrayOf_soapenc_boolean/> Refer to the ImportDevice section of the API chapter for more detailed information.Other Interfaces WSDhcpServer One element was added to WSDhcpServer. 372 IPControl CLI and API Guide . WSInterface Two elements were added to WSInterface. This affects the ModifyBlock and GetBlock APIs. the parameter structure passed to importDnsZone: <element name="dynamicZone" type="xsd:boolean"/> <element name="updatePolicy" nillable="true" type="soapenc:string"/> Refer to the importZone section of the API chapter for more detailed information. This affects the ImportDhcpServer. the parameter structure passed to importDevice. WSGenericBlock One element was added to WSGenericBlock: <element name="primarySubnet" type="xsd:boolean"/> Refer to the ModifyBlock API section for more detailed information. This element is reserved for future implementation. ExportChildBlock. ImportNetService This ImportNetService API and CLI have been deprecated as of IPControl 6. Use the ImportDhcpServer API and CLI instead. Appendix A API Changes 373 .Appendix A WSSubnetPolicy One element was added to WSSubnetPolicy: <element name="networkLinks" nillable="true" type="soapenc:string"/> This affects the ImportChildBlock. GetBlock and ModifyBlock APIs. ImportNetService support will be removed in a future release.0.