IPControl

Command 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

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

Command Line Interfaces (CLI)

Assumptions Regarding CLI Usage

Each CLI performs a specific task, or in some cases, several tasks at once. However, 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 - create IP address allocation templates

Manual step - create DNS and/or DHCP servers

Table 1 illustrates the recommended order in which the IPControl CLIs should be run.
Table 1 CLI Sequence
Sequence

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,
ImportRootBlock, or created manually

Com mand Line Interfaces (CLI) 3

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.

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, or indirectly
via the available command script. The direct approach requires a rather lengthy and
cumbersome syntax, while the indirect method requires the proper passing of necessary
parameters.
Direct
The following is an example of the direct method of execution (it assumes that the IPControl
environment variables, namely INC_HOME, JAVA_HOME and CLASSPATH are resident):
$INCHOME/jre/bin/java DINC_HOME=$INCHOME DNCX_HOME=$NCX_HOME Duser.dir=$INCHOME
cp $CLASSPATH com.diamondip.netcontrol.cli.ImportNetService u joe p joepwd
f southeast.csv

Indirect
The following example executes the same call but uses the indirect approach of calling a
predefined command script:
/opt/incontrol/ImportNetService.sh u joe p joepwd f southeast.csv

File Format
The format for import files is comma-separated values (CSV) and Microsoft Excel Workbook
(.xls or .xlsx).. These files are easily created or modified using any standard text editor. For
greater ease of use, most spreadsheet applications like Microsoft Excel or OpenOffice Calc
support saving as a CSV format.
Template files for each CLI are available in the templates directory underneath the CLI
directory (typically <product home>/etc/cli).
Note when creating import files, any lines that begin with the pound (#) character are ignored
by the InControl CLIs.

4 IPControl CLI and API Guide

File Form at

Available Command Line Interface Matrix

Object

Im port

Modify

Delete

Address Pool

Aggregate Block

Child Block

Container

Device

Device Interface

Device RR

DHCP Server

DNS

Domain

Domain RR

Galaxy Domain

Net Element

Net Element Interface

Net Service

Prefix Pool

RR Pending Approval

X
X

X
X

X
X

X
X

RR Pending Approval Status

Root Block

Zone

Zone RR

Next Available IP

X
(see ImportZone)

X
X

Join Block

Split Block

Detach Block

Task

Im port

GlobalNetElementSync

GlobalNetServiceSync

ImportElementSnapshot

ImportServiceSnapshot

GlobalRollup

DiscoverNetElement

DhcpConfigurationTask

DhcpUtilization

GetTask

GetTaskStatus

DeleteTask

Export

Modify

Delete

Export

Com mand Line Interfaces (CLI) 5

Im portAddrpool

Imports
ImportAddrpool
Overview

The ImportAddrpool CLI allows the user to bulk import address pools into IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportAddrpoolCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportAddrpool.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example imports address pools from the newaddrpools.csv file, places into the
newaddrpools.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportAddrpool.sh u joe p joepwd f newaddrpools.csv
r newaddrpools.reject e importerrors.txt

File Format
Col

Field

Accepted Values

Required

Start Address

The IP Address of the first address in the pool. This

address must be in a block with an In-Use/Deployed
status.

Yes

6 IPControl CLI and API Guide

Im portAddrpool

Col

Field

Accepted Values

Required

End Address

The IP Address of the last address in the pool. This

address must be in the same block as the Start Address.
In addition, the Start and End addresses must not
overlap any other pools. This is ignored for IPv6
pools.(PrefixLength is used instead).

Yes, for
IPv4 pool.

Address Pool Type

One of Dynamic DHCP, Automatic DHCP,

Static, Reserved, Dynamic NA DHCPv6,
Automatic NA DHCPv6, Dynamic TA DHCPv6,
Automatic TA DHCPv6

Yes

Name

Address Pool name. Defaults to Start Address-End

Address

No

Share Name

DEPRECATED. This field will be ignored.

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
Start
address is
not
unique.

Primary Net Service

The name of the DHCP server that will serve addresses

from this pool

Yes, when
a DHCP
server is
not
defined
for the
subnet.

Failover Net Service

The name of the failover DHCP server that will serve

addresses from this pool. To use this field, Primary Net
Service must also be specified.

No

DHCP Option Set

The name of an Option Set used with this pool.

No

For IPV4 address pools, the DHCP option set applies

only to non-CNR DHCP servers.
For IPV6 address pools, the DHCP option set applies
only to CNR DHCP servers.
J

DHCP Policy Set

The name of a Policy Set used with this pool.

No

For IPV4 address pools, the DHCP policy set applies

only to non-CNR DHCP servers.
For IPV6 address pools, the DHCP policy set applies
only to CNR DHCP servers.
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. Separate the list entries with a vertical bar |.
For example, to allow two client classes named
allowA and allowB, 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. Separate the list entries with a vertical
bar |. For example, to disallow two client classes
named denyA and denyB, specify:

No

denyA|denyB

Com mand Line Interfaces (CLI) 7

Im portAddrpool

Col

Field

Accepted Values

Required

PrefixLength

CIDR size of the pool for an IPv6 pool. An IPv6

should be on CIDR boundaries.This is ignored for an
IPv4 pool(End Address field is used instead).

Yes, for
IPv6 pool.

8 IPControl CLI and API Guide

Im portAggregateBlock

ImportAggregateBlock
Overview

The ImportAggregateBlock CLI allows the user to insert an intermediate level Aggregate
block between existing blocks in the block hierarchy. By specifying a parent block, target
block and a container, IPControl will validate and insert the desired aggregate block. It will
also adjust the parent block assignments of any would-be child blocks.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportAggregateBlockCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportAggregateBlock.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportAggregateBlock.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.

-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.

Usage Example

This example imports aggregate blocks from the newaggblocks.csv file, places into the
newaggblocks.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportAggregateBlock.sh u joe p joepwd f newaggblocks.csv
r newaggblocks.reject e importerrors.txt

File Format
Col

Field

Container

Accepted Values

Required

The name of the container into which to insert the new

aggregate 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

Com mand Line Interfaces (CLI) 9

Im portAggregateBlock

Col

Field

Accepted Values

Required

Start Address

The start address of the new aggregate block.

Yes

Block Size

The size of the block in short-notation (e.g., 24 for a

255.255.255.0 network).

Yes

Block Type

The Block Type for the block If not specified, a block

type of Any is assumed.

No

Block Name

A name for the block. Defaults to system

supplied name of Address space/Block size.

No

Description

A description of the block.

No

SWIP Name

SWIP name for the block.

Yes, if
required by
container
rules

Allocation Reason

The name of a pre-existing Allocation Reason.

No

Allocation Reason
Description

A description of the reason for the allocation. Wrap

the statement in quotes if it contains any commas.

No

Interface Name

If this block is being added to a device container, the

name of the interface to attach the block to.

Yes, if block is
being added
to device
container.
Otherwise,
no.

Interface Offset or
Address

DEPRECATED. This field will be ignored.

No

Create Reverse
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

Domain Type

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

User Defined Fields

A series of name=value pairs, 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. For example, UDFone=value one
|UDFtwo=value two. If the UDF type is Checkbox,
the valid values are on or off. If the UDF type is
Textarea, use \n to separate lines.

Yes, for
UDFs defined
as required
fields.

Parent Container

The name of the container where the parent block

resides.

Yes

Parent Block Address

The address of the parent block

Yes

Parent Block Size

The size of the parent block in short-notation (e.g., 24

for a 255.255.255.0 network).

Yes

10 IPControl CLI and API Guide

Im portChildBlock

ImportChildBlock
Overview

The ImportChildBlock CLI allows the user to bulk import child blocks into IPControl. It
also allows modification of existing records when using the overwrite option (-o) and the
expanded format, described later in this section. It can also be used to attach an existing block
to another container, by specifying an existing Address Block.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportChildBlockCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-o] [-v] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportChildBlock.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-o] [-v] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportChildBlock.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-o

No

Overwrite option. Specify whether the import file contents will

overwrite any matching records that exist in the database. This
option requires expanded format. See below.

-v

No

Produces verbose output.

Usage Example

This example imports child blocks from the newchildblocks.csv file, places into the
newchildblocks.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportChildBlock.sh u joe p joepwd f newchildblocks.csv
r newchildblocks.reject e importerrors.txt

Com mand Line Interfaces (CLI) 11

Im portChildBlock

Import with overwite using expanded format and the !BLANK! keyword

This example imports child blocks using the expanded format.

$INCHOME/etc/cli/ImportChildBlock.sh u joe p joepwd f cexport.csv o

Here is the input file:

Note the following:

You can produce a file in this format using the ExportChildBlock CLI.
The o (overwite) parameter is required in order to modify blocks via this CLI.
The rows describe blocks to be either imported or modified. In other words, existing
blocks will be modified; new blocks will be imported. Blocks to be modified are
identified by either blockName (D) or blockAddr (E) and, when necessary to resolve
ambiguity, container (A).
The first row is a header line, beginning with ^. The column headers beyond the
architected column AA contain the user defined field tags.
Column P contains Expanded when the row includes user defined fields beyond
column AA. For example, row 3 has no user defined fields defined for that block.
In this example, columns AB-AD contain the values for the user defined fields. If
there is no value for a field in the block, an empty cell will be exported.
To clear a field in an existing record, specify !BLANK!, as shown in row 4 column
AC. A cell with no value, as in row 2 column AD, will result in no change to the value
for the record stored in the database.
Blocks cannot be moved to a different container using this CLI, because the container
is used to identify the block.
If an expanded user defined field column contains data for a block where that field is
not defined, an error will be reported.

12 IPControl CLI and API Guide

Im portChildBlock

File Format
Col

Field

Accepted Values

Required

Container

The name of the 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

Block size | IPV6

The size of the block in short-notation (e.g., 24 for a

255.255.255.0 network).

Yes | No

If an IPV6 block is desired, follow the block size with

|true. IPV4 is the default.
C

Block type

The Block Type for the block If not specified, a block

type of Any is assumed.

No

Block Name

A name for the block. Defaults to system supplied name

of Address space/Block size.

No

Address Block

The address block to allocate. If no address block is

specified, space will be auto-allocated. If the address is
specified and already exists, the block will be attached to
the specified container.

No

Description

A description of the block. Use \n to separate lines.

No

Current Status

The current status of the block. Accepted values are:

Deployed, FullyAssigned, Reserved, Aggregate.

Yes

SWIP Name

SWIP name for the block.

Yes, if
required by
Container
rules

Allocation
Reason

The name of a pre-existing Allocation Reason. If

Allocation Reason is not currently in IPControl, this
field is skipped.

No

Allocation
Reason
Description

A description of the reason for the allocation. Wrap the

statement in quotes if it contains any commas.

No

Allocation
Template

If this block is being added to a device container with

blockStatus=Deployed, the name of the allocation
template to use to create address pools from the newly
created block.

No

Interface Name

If this block is being added to a device container, the

name of the interface to attach the block to.

Yes, if block
is being
added to
device
container.
Otherwise,
no.

Com mand Line Interfaces (CLI) 13

Im portChildBlock

Col

Field

Accepted Values

Required

Interface Offset
or Address

The specific address(es), or offset(s) from the beginning,

for the interface IP address(es). If an IP address is
specified, it should be in the form xxx.xxx.xxx.xxx. If
an integer is specified, it will be interpreted as an offset
from the beginning of the block (i.e. an offset of 2 in a
/24 block will create an interface xxx.xxx.xxx.2).

No. An
offset of 1 is
assumed if
none is
specified.

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.
Multiple addresses can be specified by separating the
values with the | character. For example, specify 3
interface offsets as 1|2|3.
You can modify or delete interface addresses using the
overwrite option. Specify the complete list of addresses
using the IP address, separated by the | character if
there is more than one. You cannot add an interface
address or delete all interface addresses.
Note that you cannot modify or delete a virtual interface
address.
N

Create Reverse
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

Domain Type

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

User Defined
Fields

A series of name=value pairs, 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. For example, UDFone=value one
|UDFtwo=value two. If the UDF type is Checkbox,
the valid values are on or off. If the UDF type is
Textarea, use \n to separate lines.

Yes, for
UDFs
defined as
required
fields.

When this column contains the word Expanded, an

expanded format input file is expected. See below for an
example of this format.
Q

Exclude From
Discovery

Flag indicating if this subnet should be included in Host

Discovery tasks. Accepted values are true or false. If
not specified, defaults to false.

No

Valid only for Deployed blocks.

R

DHCP Option
Set

The name of a DHCP Option Set defined within

IPControl that should apply to this subnet. Valid only
for Deployed blocks.

No

DHCP Policy Set

The name of a DHCP Policy Set defined within

IPControl that should apply to this subnet. Valid only
for Deployed blocks.

No

DNS Servers

The list of default DNS Servers for this subnet. This

list is supplied to DHCP clients on this subnet. The
server name or IP Address is valid. For multiple
servers, separate the server names with a vertical bar (|).
Valid only for Deployed blocks.

No

14 IPControl CLI and API Guide

Im portChildBlock

Col

Field

Accepted Values

Required

Default Gateway

The default gateway address for this subnet. This

address is supplied to DHCP clients on this subnet.
Valid only for Deployed blocks.

No

Primary DHCP
Server

The name or IP Address of the primary DHCP server

for this address space. Valid only for Deployed
blocks.

No

Failover DHCP
Server

The name or IP Address of the failover DHCP Server

for this address space. Valid only for Deployed
blocks.

No

DNS Forward
Domains

The list of DNS Forward domains for this address

space, separated by a vertical bar (|). This list will
appear in the GUI when choosing domains for devices.
To specify a domain type, specify the domain followed
by / followed by the domain type. Valid only for
Deployed blocks. For example:

No

hr.ins.com.|dmz.com./External
In this example, hr.ins.com uses the default domain
type, and dmz.com is of type External.
Y

DNS Reverse
Domains

The list of DNS Reverse domains for this address space,

separated by a vertical bar (|). This list will appear in the
GUI when choosing domains for devices. To specify a
domain type, specify the domain followed by /
followed by the domain type. Valid only for Deployed
blocks. For example:

No

0-15.1.0.10.in-addr.arpa. /External |40.10.in-addr.arpa.

In this example, 0-15.1.0.10.in-addr.arpa. is of type
External, and 40.0.10.in-addr.arpa. uses the default
domain type.
Z

Primary WINS
Server

The IP Address of the Primary WINS Server for this

subnet. Used to provide this information to DHCP for
Dynamic Address types. Multiple WINS servers may be
specified, separated by a comma.

No

AA

Allocation
Strategy

The Automatic Allocation Strategy to use where a block

address is not provided. Valid options are:

No

Bestfit (the default option when none is specified)

Sparse (IPv6 only)
Random. (IPv6 only)
Note this field is not used for overwrite.
AB

Primary Subnet

Flag indicating if this subnet is primary. Accepted

values are true or false. If not specified, defaults to
false.

No

Valid only for Deployed blocks in device

containers.

Com mand Line Interfaces (CLI) 15

Im portContainer

ImportContainer
Overview

The ImportContainer CLI allows the user to bulk import containers into IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportContainerCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportContainer.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportContainer.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.

-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.

Usage Example

This example imports containers from the newcontainers.csv file, places into the newcontainers.reject
file any records that could not be imported, and reports errors to the importerrors.txt file.
$INCHOME/etc/cli/ImportContainer.sh u joe p joepwd f newcontainers.csv
r newcontainers.reject e importerrors.txt

File Format
Col

Field

Accepted Values

Required

Container Name

The name of the container. If you are creating a

device container, this container name must match
exactly the name of a network element already in
the database or the record will be rejected.

Yes

Container
Description

A brief description of the container. Use \n to

separate lines.

No

16 IPControl CLI and API Guide

Im portContainer

Col

Field

Accepted Values

Required

Parent Container

The name of the parent container for this container.

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. If using the long format, the
name must be the complete path beginning at the
top of the container tree.

Yes

Container Type

Either logical or device.

Yes

Rule1

A listing of the valid block types for this container,

separated by /. To specify information templates
to be used for a block type, specify the block type
followed by | followed by the information
template name. For example:

No

blocktype1|templateone/blocktype2/block
type3|templatetwo
In this example, blocktype2 does not use an
information template.
F

Rule2

A listing of the block types enabled for root block

creation, separated by /. Note this applies only to
logical containers, and will be ignored if specified
for device containers.

No

Rule3

A listing of the block types that can be used for

space allocation from the parent container,
separated by /.

No

Rule4

A listing of the block types for which SWIP Names

are required, separated by /.

No

Rule5

A listing of the device types for this container,

separated by /. To specify information templates
to be used for a device type, specify the device type
followed by | followed by the information
template name. For example:

No

devicetype1|templateone/devicetype2/
devicetype3|templatetwo
In this example, devicetype2 does not use an
information template.
To specify that all device types should be allowed,
use ALL. To specify that no device types should be
allowed, use NONE.
ALL is the default.
J

Information
Template

The name of a pre-existing information template to

be associated with this container.

No

Com mand Line Interfaces (CLI) 17

Im portContainer

Col

Field

Accepted Values

Required

User Defined Fields

Specify the values for the UDFs in the container

information template, specified in the previous
parameter. Specify as a series of name=value pairs,
where the name is the UDF name and the value is the
desired value. Multiple fields can be specified by
separating each name=value pair with the |
character. For example:

Yes, for
UDFs
defined as
required
fields

fieldOne=valueOne|fieldTwo=valueTwo
If the UDF type is Checkbox, the valid values are
on or off.
If the UDF type is Textarea, use \n to separate
lines.
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.
Accepted values are true or false. If not specified,
defaults to false.

No

Im portDevice

ImportDevice
Overview

The ImportDevice CLI imports devices into IPControl. This is used to bulk load
information about existing network devices. It also allows modification of existing records
when using the overwrite option (-o) and the expanded format, described later in this section.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ImportDevice u <userId> -p <pswd>
-f <import_file> [-e <error messages>] [-r <rejects file>] [-o] [-v] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportDevice.sh u <userId> -p <pswd>
-f <import_file> [-e <error messages>] [-r <rejects file>] [-o] [-v] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportDevice.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-o

No

-v

No

Overwrite option. Specify whether the import file contents will

overwrite any matching records that exist in the database. This
option requires expanded format. See below.
Produces verbose output.

Usage Example

This example imports all of the devices in the file devices.csv and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportDevice.sh u joe p joepwd f devices.csv e importerrors.txt
r importrejects.txt

Com mand Line Interfaces (CLI) 19

Im portDevice

Import with overwite using expanded format and the !BLANK! keyword

This example imports devices using the expanded format.

$INCHOME/etc/cli/ImportDevice.sh u joe p joepwd f cexportdevice.csv o

Here is the input file:

Note the following:

You can produce a file in this format using the ExportDevice CLI.
The o (overwite) parameter is required in order to modify devices via this CLI.
The rows describe devices to be either imported or modified. In other words, existing
devices will be modified; new devices will be imported. Devices to be modified are
identified by hostname, ipaddress or MACAddress.
The first row is a header line, beginning with ^. The column headers beyond the
architected column R contain the user defined field tags.
Column L contains Expanded when the row includes user defined fields beyond
column R. For example, row 4 has no user defined fields defined for that device.
Columns S-V contain the values for the user defined fields. If there is no value for a
field in the device, an empty cell will be exported. For example, row 5 has no value in
column U.
To clear a field in an existing record, specify !BLANK!, as shown in row 6 column
U. A cell with no value, as in row 5 column U, will result in no change to the value for
the record stored in the database.
If an expanded user defined field column contains data for a device where that field is
not defined, an error will be reported.

20 IPControl CLI and API Guide

Im portDevice

File Format
Col

Field

Accepted Values

Required

IP Address

The IP Addresses of the Device.

If there is more than one, the device is created as a
multi-homed device. Separate multiple IP addresses
with a vertical bar (|).
For single-homed devices only, to indicate that
IPControl should use the next available address in
an IPV4 block, specify the block address, followed
by /from-start or /from-end, for example:
10.30.0.0/from-start

Yes

For devices with multiple IP Addresses on a single

interface (devices with address type Interface), use
one or more address to locate the device for an
overwrite. Note that device attributes can be
modified, but an Interface address cannot be
modified or deleted. Use ImportChildBlock with
overwrite to modify or delete an Interface address.
B

Address Type

The address type of this device. Accepted values are:

Static, Dynamic DHCP, Automatic DHCP,
Manual DHCP and Reserved. For DHCP V6:
Dynamic NA DHCPv6, Automatic NA
DHCPv6, Manual NA DHCPv6, Dynamic TA
DHCPv6 and Automatic TA DHCPv6.
Note that if Dynamic, Automatic or Manual
DHCP is specified, there must be a DHCP server
defined in the subnet policies for this IP Address.

Host Name

Devices of type Interface may not be imported, but

they can be modified using overwrite. However, the
address type and IP address cannot be updated.
Valid host name or APPLYNAMINGPOLICY

Device Type

The name of a device type configured in IPControl.

Hardware Type

Specify Ethernet or Token Ring. When Hardware

Type is specified, MAC Address must also be
specified. If MAC Address is specified, this will
default to Ethernet.

MAC Address

The hardware MAC addresses of the device.

Separate multiple entries with a vertical bar (|). If
not left blank, there must be one MAC for each IP
Address in column A.

Yes

Yes
Yes, if
Hostname
specifies use
of naming
policy
No

Yes, if
Hardware
Type is
specified or
if address
type is
Manual
DHCP

Com mand Line Interfaces (CLI) 21

Im portDevice

Col

Field

Accepted Values

Required

Resource Record
Flag

Whether or not to add resource records for this

device. Accepted values are true or false. If not
specified, defaults to false.

No

Note that the domain name must be specified if the

block policy has no forward domains. Also, the
reverse domain must exist in order for the PTR
record to be added.
Domain name already defined to IPControl

Domain Name

Container

The name of the container that contains 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, if
overlapping
space is in
use and the
block name
is
ambiguous.

Domain Type

Domain type name already defined to IPControl. If

not specified, the Default domain type will be
used

No

Description

A description of the device. Use \n to separate

lines.

No

User Defined Fields

A series of name=value pairs, where the name is the

UDF name and the value is desired value. Multiple
fields can be specified by separating each
name=value pair with the | character. For
example, fieldOne=valueOne|fieldTwo=valueTwo.
If the UDF type is Checkbox, the valid values are
on or off. If the UDF type is Textarea, use
\n to separate lines.

Yes, for
UDFs
defined as
required
fields.

Yes, if
Resource
Record Flag
is true
and the
block policy
has no
forward
domains.

When this column contains the word Expanded,

an expanded format input file is expected. See
below for an example of this format.
M

Aliases

The alias or list of aliases for this hostname. When

you specify an alias, a CNAME record is created.
The alias may be fully qualified (contains a trailing
dot), or not. When fully qualified, everything after
the first qualifier is interpreted as a domain name.
When not fully qualified, the CNAME record will
be created in the same domain as the device.
Specify multiple aliases by separating each one with
the | character.
To use this field, you must also specify Resource
Record Flag = true.

22 IPControl CLI and API Guide

No

Im portDevice

Col

Field

Accepted Values

Required

Ignore Warning

If the administrator policy of the user indicates

Warn for the Allow Duplicate Hostnames
Checking option, 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 not specified, defaults to false.

No

Interface Names

Specify the names of the interfaces created for a

multi-homed device. Separate entries with a vertical
bar (|). There must one entry for each IP
Address in Column A.

Yes, if
multiple IP
Addresses
are entered
in Column
A.

Exclude from
Discovery Flags

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, if
multiple IP
Addresses
are entered
in Column
A.

Virtual flag

Specify the flags for each interface created for a

multi-homed device. Separate entries with a vertical
bar (|). There must one entry for each IP
Address in Column A.
Reserved and will be ignored

DUID

DHCP Unique Identifier

No
Yes, for
Address
Type
Manual
NA
DHCPV6.

Com mand Line Interfaces (CLI) 23

Im portDomain

ImportDomain
Overview

The ImportDomain CLI imports domains into IPControl.

Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ImportDomain u <userId> -p <pswd>
-f <import_file> [-e <error messages>] [-r <rejects file>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportDomain.sh u <userId> -p <pswd>
-f <import_file> [-e <error messages>] [-r <rejects file>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportDomain.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-v <verbose>

No

Produces verbose output.

Usage Example

This example imports all of the domains in the file domains.csv and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportDomain.sh u joe p joepwd f domains.csv e importerrors.txt
r importrejects.txt

File Format
Col

Field

Accepted Values

Required

Domain Name

The name of the domain being created.

Yes

Domain Type

Domain type name already defined to IPControl. If

not specified, the Default domain type will be
used.

No

Managed

Indicates that this domain is fully defined in

IPControl. Accepted values are true or false. If not
specified, defaults to true.

No

24 IPControl CLI and API Guide

Im portDomain

Col

Field

Accepted Values

Required

Delegated

Indicates that this domain will be associated directly

with a zone file. Accepted values are true or false.
If not specified, defaults to true.

No

Reverse

Indicates that this domain is a reverse in-addr.arpa

or ip6.arpa domain. Accepted values are true or
false. If not specified, defaults to false.

No

Derivative

Specify the role of this domain. This can be one of

STANDARD, TEMPLATE, or ALIAS. The
default is STANDARD.

No

Template Domain

Name of template domain.

Yes, if
Derivative is
ALIAS

Serial Number

Zone serial number. If not specified, defaults to 1;

ignored if Managed is False.

No

Refresh

Zone refresh interval. If not specified, defaults to

10800; ignored if Managed is False.

No

Retry

Zone retry interval. If not specified, defaults to

3600; ignored if Managed is False.

No

Expire

Zone expire time. If not specified, defaults to

604800; ignored if Managed is False.

No

Negative Cache
TTL

Zone negative cache time to live. If not specified,

defaults to 86400; ignored if Managed is False.

No

Default TTL

Default time to live. If not specified, defaults to

86400; ignored if Managed is False.

No

Contact

O
P

The contact email address in dotted format. For

example, an email address of '[email protected]', would
be represented as 'root.ins.com'. If not specified a
default contact name will be formed by prepending
'dnsadmin' to the domain name as in
'dnsadmin.ins.com.'.

No

Information
Template

Pre-defined information template to be associated

with this domain.

No

User Defined Fields

A series of name=value pairs, where the name is the

UDF field name/tag and the value is desired value.
Multiple fields can be specified by separating each
name=value pair with the | character. For
example, fieldOne=valueOne|fieldTwo=valueTwo.
If the UDF type is Checkbox, the valid values are
on or off. If the UDF type is Textarea, use
\n to separate lines.

Yes, for
UDFs
defined as
required
fields.

Com mand Line Interfaces (CLI) 25

Im portDeviceResourceRecord

ImportDeviceResourceRecord
Overview

The ImportDeviceResourceRecord CLI allows the user to bulk import DNS resource
records for a device into IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ImportDeviceResourceRecordCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportDeviceResourceRecord.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportDeviceResourceRecord.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.

-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.

Usage Example

This example imports resource records from the newresourcerecs.csv file, places into the
newresourcerecs.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportDeviceResourceRecord.sh u joe p joepwd
f newresourcerecs.csv r newresroucerecs.reject e importerrors.txt

File Format
Col

Field

Accepted Values

Required

Domain

The name of the domain to which the resource records will

be added.

Yes

Domain Type

The name of the domain type to which the domain belongs.

Defaults to Default

No

Owner

The OWNER section of the resource record. Note that this

section is specific to the type of resource record. Refer to
the appropriate RFC for exact text that should be entered.

Yes

26 IPControl CLI and API Guide

Im portDeviceResourceRecord

Col

Field

Accepted Values

Required

Host Name

The device host name.

Yes, unless
IP Address
is specified.

IP Address

The IP Address of the Device.

Yes, unless
Host Name
is specified.

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. The container is
then used to uniquely determine the device.

Yes, if IP
Address in
overlapping
space.

TTL

The Time To Live.

No

Class

The value currently supported is IN. If not specified,

defaults to IN.

No

Resource
Record Type

The type of resource record being imported.

Yes

Data

The text for the DATA area of the resource record. Note
that this section is specific to the type of resource record.
Refer to the appropriate RFC for exact text that should be
entered.

Yes

Comment

Text to be appended to the resource record.

No

Com mand Line Interfaces (CLI) 27

Im portDhcpServer

ImportDhcpServer
Overview

The ImportDhcpServer CLI creates DHCP Servers in IPControl.

Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ImportDhcpServer u <userId> -p <pswd>
-f <import filename> [-e <error messages>] [-r <rejects file>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportDhcpServer.sh u <userId> -p <pswd>
-f <import filename> [-e <error messages>] [-r <rejects file>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportDhcpServer.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

File Format
Col

Field

Accepted Values

Required

Name

The name of the DHCP Server. This is often the

hostname of the system running the server.

Yes

IP Address

The IP Address of the DHCP Server. This must be a

legal IP address. If the V4V6Both parameter is V6,
then this must be a legal IPv6 address.

Yes

Product

The product name of the DHCP Server. This must

be one of the products defined in IPControl.

Yes

Agent

The IPControl agent that manages the server

Yes

Default Threshold

The default alert threshold applied to all scopes

managed by this server. This must be a number
between 0 and 100. Defaults to 90.

No

Global Sync

Specify TRUE to include this server in Global Sync

tasks. Defaults to false.

No

Configuration Path

The path to the servers configuration file. Must be a

legal, fully qualified path name for the host system.

No

28 IPControl CLI and API Guide

Im portDhcpServer

Col

Field

Accepted Values

Required

Lease Path

The path to the lease file. Must be a legal, fully

qualified path for the host system. Must be a legal,
fully qualified path name for the host system.

No

Start Script

The path to the script that starts the server. Must be a

legal, fully qualified path name for the host system.

No

Stop Script

The path to the script that stops the server. Must be a

legal, fully qualified path name for the host system.

No

Collection Type

SCP or FTP

No

Collection Port

Must be between 1 and 65535. Defaults to 21 for

FTP and 22 for SCP.

No

Collection User

User name for SCP/FTP access to the executive.

No

Collection
Password

Password for the collection user.

No

Collect Backup
Subnets

Specify TRUE to collection statistics on backup

subnets. Defaults to FALSE.

No

CLI Command

Collection program name

No

CLI User

Collection program user credential.

No

CLI Password

Collection program password credential

No

CLI Arguments

Arguments to the Collection program. Differs

according to product.

No

DDNS

Specify TRUE to enable dynamic DNS updates when

this server issues a lease. Defaults to FALSE.

No

DHCP Option Set

The name of an option set defined in IPControl.

No

DHCP Policy Set

The name of a policy set defined in IPControl.

No

DHCP Client
Classes

The names of client classes defined in IPControl that

this server will be using. Separate multiple client
classes with a vertical bar (|).

No

DHCP Failover IP
Address

The IP Address used by the DHCP server for failover

communications.

No

DHCP Failover
Port

The Port used by the DHCP server for failover

communications.

No

Configuration File
Pre-Extension

Text to prepend to the DHCP server configuration

file. This can be the text itself, or a reference to a file.
If the field begins with file:, then the remainder of
the field is treated as a file name and the files
contents are used.

No

AA

Configuration File
Post-Extension

Text to append to the DHCP server configuration

file. This can be the text itself, or a reference to a file.
If the field begins with file:, then the remainder of
the field is treated as a file name and the files
contents are used.

AB

V4V6Both

IP version supported by the DHCP server. Valid

values are V4, V6 or Both

Yes

Com mand Line Interfaces (CLI) 29

Im portDNS

ImportDNS
Overview

The ImportDNS CLI allows the user to import the contents of a DNS zone file, or the zone
files referenced by master zones declared in an ISC BIND 8.x and newer named.conf file.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.dnsimport.DNSImport f <import filename> -s <server>
[-v <view>] [-z <zone>] [-l] [-t <domainType>] [-m <view/zone=domainType, >]
[-n] [-2 None|ZoneOnly|ZoneAndRR] [-c container]

Via command script (Unix)

$INCHOME/etc/cli/ImportDNS.sh -f <import filename> -s <server> [-v <view>] [-z <zone>] [-l]
[-t <domainType>] [-m <view/zone=domainType, >] [-n] [-2 None|ZoneOnly|ZoneAndRR]
[-c container]

Via command script (Windows)

%INCHOME%/etc/cli/ImportDNS.cmd -f <import filename> -s <server> [-v <view>] [-z <zone>]
[-l] [-t <domainType>] [-m <view/zone=domainType, >] [-n] [-2 None|ZoneOnly|ZoneAndRR]
[-c container]

Parameters
Param eter

Required

Description

-f <import filename>

Yes

File name containing data to import. If the -z parameter is not

supplied, the file is assumed to be a ISC BIND 8.x or newer
configuration file. Otherwise it is assumed to be a ISC DNS
zone file.

-s <server>

Yes

The name of the DNS network service as defined in IPControl

to import the zone data into.

-v <view>

No

The name of the view in which new domains should be created.

If supplied the view must exist. If not supplied new domains
will be created in the view named 'Default.'

-z <zone>

No

The name of the zone. Must be supplied when importing a

single zone file. See -f.

-l

No

Import flat zone. The domain hierarchy will be created to

support the domain in the SOA, but any other sub-domains
found within the zone will not be created as separate domains.

-t

No

The name of the DomainType to assign to the imported

domain(s). If not specified, then the Default DomainType is
used.

30 IPControl CLI and API Guide

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.
Note: This option is only valid when parsing a configuration
file, not when parsing an individual zone file using the z
option.
An example with Views defined:
-m
internal/hr.ins.com=internal,external/dmz.ins
.com=external

An example when views are not defined:

-m hr.ins.com=internal,dmz.ins.com=external

Note: Quotes are not necessary unless there are spaces in the
DomainType names. They are used here for completeness.
-n

No

Allow NS records to be imported. By default, NS records are

ignored. By specifying this option, NS records will be imported
into the domain Resources Records. In addition, the Autogenerate NS records flag for the zone will be turned off.

-2

No

Slave (or secondary) zone handling. Valid values are:

None (default) Ignore all slave zones.
ZoneOnly Import the zone definition only.
ZoneAndRR Import the zone definition and the Resource
Records in the zone file.
Note: This option is only valid when parsing a configuration
file, not when parsing an individual zone file using the z
option.

-c

No

Container name. The full pathname (e.g. InControl/North

America/US/PA) of a container in IPControl to be used to
distinguish between overlapping address blocks. When
ImportDNS encounters A or PTR records when importing a
zone, it will attempt to create Device and IP Address records
accordingly. 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, then this
parameter can be used to specify a container which is used to
select the proper block .

-h, -?

No

Print help.

Description

The ImportDNS CLI imports DNS resource records contained in zone data files into
IPControl. It does this by sequentially reading each resource record contained in a specified
zone file, processing each one according to a set of rules described below, and then inserting
some portion of the resulting data into IPControl.
Resource records read from zone files are initially processed using the same rules described in
RFC 1035. This means that after initial processing the resource record will contain all the
required fields: Name, Type, Class, TTL, and Rdata. This processing can include filling in any
missing TTL values or Name fields, correctly using the Origin when an @ character is
Com mand Line Interfaces (CLI) 31

Im portDNS

encountered in a name field, and appending the Origin when appropriate as described by RFC
1035. The resulting resource record is then processed using rules specific to each resource
records Type field. 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. The
domain name is taken from the name field of the resource record. If the domain does
not exist in IPControl it will be created. When a domain is created by the ImportDNS
CLI its parent domain will be created and linked to its child, or sub-domain. This
process continues until an existing parent is found, or a top level domain is created.
Top level domains created in this way have no parent associated with them. After the
domain and its parents have been created, or if it already exists in IPControl, the data
from the imported record will be used to update the domain. This includes the serial
number, refresh, retry, expire, negative caching TTL, default TTL, and contact fields.
In addition, the managed and delegated properties will be set for the domain. Note: If
parent domains are created as a result of the record being imported, the delegated
property will be set, while the managed property will not be set. If the domain name
ends with .in-addr.arpa. the reverse property will be set.

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. 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. If the
resulting domain (everything to the right of the left-most label) does not exist in
IPControl, then it will be created along with any necessary parent domains. The newly
created domain will have its managed property set, while its delegated property will not
be set. If parent domains were also created, their delegated property will be set and
their managed property will not be set. If the address found in the rdata field of the
resource record can be located within an existing address block defined in IPControl,
an IP address will be created using the rdata field, and a device will be created using the
name field. The device and IP address will also be associated with the resource record
in addition to the domain.

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.

NS

NS records are ignored by the ImportDNS CLI.

MX

MX records are imported into IPControl and attached to the domain supplied in the
name field.

32 IPControl CLI and API Guide

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. The name field of SRV records specifies a service
available for the domain for which it is a part of. The service type and protocol is
encoded in the left portion of its name field. To avoid collision with the rest of the
domain name space, leading underbars are prepended to the labels that describe the
service. 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. 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.
For example in the following SRV record:
_ldap._tcp.pdc._msdcs.sw.ins.com. 600 SRV 0 100 400 pdc.sw.ins.com.
The service specification part would be: _ldap._tcp.pdc._msdcs
and the domain name part would be: sw.ins.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. If the domain cannot
be found in IPControl it will be created, along with any necessary parent domains.
Parent domains will have the delegated property set and the managed property not set.
A resource record object is created using the data supplied by the imported record, and
it is linked to the domain.

Examples

The usage examples below use these example zone data or configuration files:
Example zone data file db.example:
$TTL 3600
@ IN SOA thomas.example.com. hostmaster.thomas.example.com. (
1
; Serial number
10800 ; Refresh
3600
; Retry
604800 ; Expire
86400 )
; Minimum TTL
IN NS
thomas.example.com.
localhost
IN A 127.0.0.1
dhcp
IN A 192.168.0.1
thomas
IN A 192.168.0.2
msdc
IN A 192.168.0.3
www
IN A 192.168.0.4
ftp
IN A 192.168.0.5
mail
IN A 192.168.0.6
_ftp._tcp
_http._tcp

IN SRV
0 100 400 ftp.example.com.
IN SRV 0 100 434.www.example.com.

dns
w3
web
incoming
smtp
pop

IN
IN
IN
IN
IN
IN

CNAME
CNAME
CNAME
CNAME
CNAME
CNAME

thomas.example.com
www.example.com.
www.example.com.
ftp.example.com.
mail.example.com.
mail.example.com.

Example zone data file db.192.168.0:

Com mand Line Interfaces (CLI) 33

Im portDNS

0.168.192.in-addr.arpa IN SOA thomas.example.com. hostmaster.thomas.example.com.

1
; Serial number
10800 ; Refresh
3600
; Retry
604800 ; Expire
86400 )
; Minimum TTL

2.0.168.192.in-addr.arpa. IN NS thomas.example.com.
1.0.168.192.in-addr.arpa.
2.0.168.192.in-addr.arpa.
3.0.168.192.in-addr.arpa.
4.0.168.192.in-addr.arpa.
5.0.168.192.in-addr.arpa.
6.0.168.192.in-addr.arpa.

PTR
PTR
PTR
PTR
PTR
PTR

dhcp.example.com.
thomas.example.com.
msdc.example.com.
www.example.com.
ftp.example.com.
mail.example.com.

Example Bind 9 configuration file named.conf:

Options {

directory /var/lib/named;
notify no;
};
zone example.com. {
type master;
file db.example;
};
zone 0.168.192.in-addr.arpa. {
type master;
file db.0.168.192;
};

Usage Example 1

This example creates master zones linked to the server dns1.sw.ins.com using the zone
data contained within the zone files that are referenced by the master zone declarations within
the named.conf file, specifically the files db.example and db.0.168.192. The following domains are
created: com., example.com., and 0.168.192.in-addr.arpa. The domain
example.com. has 14 resource records associated with it, all the ones declared in the
db.example file except the SOA record, and the NS record. The data from the SOA record
updates the domain example.com with the values from its rdata field. The domain
example.com. is marked as delegated and managed. The domain 0.168.192.inaddr.arpa. has associated with it the resource records from the db.0.168.192 file except the
SOA and NS records. Its properties are also updated with the information from the SOA
record for the zone, and are marked as delegated and managed. It is also marked as reverse.
$INCHOME/etc/cli/ImportDNS.cmd -f /etc/named.conf -s dns1.sw.ins.com

Usage Example 2

This example imports the resource records declared in the zone file db.192.168.0. The domain
0.168.192.in-addr.arpa is created if it does not already exist. The domain has its
delegated, managed, and reverse properties set. The zone 0.168.192.in-addr.arpa is
created and associated with the server dns1.sw.ins.com.

34 IPControl CLI and API Guide

Im portDNS

$INCHOME/etc/cli/ImportDNS.cmd -f db.192.168.0 -s dns1.sw.ins.com

-z 0.168.192.in-addr.arpa

Usage Example 3

This example imports the resource records declared in the zone file db.hr.ins.com. The domain
hr.ins.com is created if it does not already exist. The domain has its delegated, managed,
and reverse properties set. The domain is assigned to the internal DomainType. The zone
hr.ins.com is created and associated with the server dns1.sw.ins.com.
$INCHOME/etc/cli/ImportDNS.cmd -f db.hr.ins.com -s dns1.sw.ins.com
-z hr.ins.com t internal

Usage Example 4

This example creates master zones linked to the server dns1.sw.ins.com using the zone
data contained within the zone files that are referenced by the master zone declarations within
the named.conf file, specifically the files db.example and db.0.168.192. The following domains are
created, if they did not already exist: com., example.com., in-addr.arpa. , and
0.168.192.in-addr.arpa. The domain example.com. has 14 resource records
associated with it, all the ones declared in the db.example file except the SOA record, and the
NS record. The data from the SOA record update the domain example.com with the values
from its rdata field. The domain example.com. is marked as delegated and managed. The
domains com. and example.com are assigned to the external DomainType. The domains
in-addr.arpa and 0.168.192.in-addr.arpa. are assigned to the Default
DomainType. The domain 0.168.192.in-addr.arpa. has associated with it the
resource records from the db.0.168.192 file except the SOA and NS records. Its properties are
also updated with the information from the SOA record for the zone, and are marked as
delegated and managed. It is also marked as reverse.
$INCHOME/etc/cli/ImportDNS.cmd -f /etc/named.conf -s dns1.sw.ins.com
m example.com=external

Usage Example 5

This example creates master zones linked to the server dns1.sw.ins.com using the zone
data contained within the zone files that are referenced by the master zone declarations within
the named.conf file, specifically the files db.example and db.0.168.192. The following domains are
created: com., example.com., and 0.168.192.in-addr.arpa. The domain
example.com. has 14 resource records associated with it, all the ones declared in the
db.example file except the SOA record, and the NS record. The data from the SOA record
updates the domain example.com with the values from its rdata field. The domain
example.com. is marked as delegated and managed. The domain 0.168.192.inaddr.arpa. is associated with it the resource records from the db.0.168.192 file except the
SOA and NS records. Its properties are also updated with the information from the SOA
record for the zone, and are marked as delegated and managed. It is also marked as reverse.
$INCHOME/etc/cli/ImportDNS.cmd -f /etc/named.conf -s dns1.sw.ins.com -2 ZoneOnly

In addition, a zone definition is created for the Slave zone foo.com. Its masters substatement is set to 192.168.0.1; 192.168.0.2. If necessary the domain foo.com is
also created with the SOA information found in the file bak.foo.com. The domain is marked as
delegated and managed. No resource records are imported for foo.com.
Com mand Line Interfaces (CLI) 35

Im portDNS

Usage Example 6

This example creates master zones linked to the server dns1.sw.ins.com using the zone
data contained within the zone files that are referenced by the master zone declarations within
the named.conf file, specifically the files db.example and db.0.168.192. The following domains are
created: com., example.com., and 0.168.192.in-addr.arpa. The domain
example.com. has 14 resource records associated with it, all the ones declared in the
db.example file except the SOA record, and the NS record. The data from the SOA record
updates the domain example.com with the values from its rdata field. The domain
example.com. is marked as delegated and managed. The domain 0.168.192.inaddr.arpa. has associated with it the resource records from the db.0.168.192 file except the
SOA and NS records. Its properties are also updated with the information from the SOA
record for the zone, and are marked as delegated and managed. It is also marked as reverse.
$INCHOME/etc/cli/ImportDNS.cmd -f /etc/named.conf -s dns1.sw.ins.com -2 ZoneAndRR

In addition, a zone definition is created for the Slave zone foo.com. Its masters substatement is set to 192.168.0.1; 192.168.0.2. If it did not already exist, the domain
foo.com is also created with the SOA information found in the file bak.foo.com. The
domain is marked as delegated and managed. The domain has associated with it the resource
records from the bak.foo.com file except the SOA and NS records.
Return codes

The ImportDNS CLI always returns 0.

36 IPControl CLI and API Guide

Im portDomainResourceRecord

ImportDomainResourceRecord
Overview

The ImportDomainResourceRecord CLI allows the user to bulk import DNS resource
records for a domain into IPControl. This CLI allows the administrator to enter resource
records that are not bound to a particular device.
Note: For Glue records that link one zone to another, use the
ImportZoneResourceRecord CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ImportDomainResourceRecordCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportDomainResourceRecord.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportDomainResourceRecord.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.

-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.

Usage Example

This example imports resource records from the newresourcerecs.csv file, places into the
newresourcerecs.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportDomainResourceRecord.sh u joe p joepwd f newresourcerecs.csv
r newresroucerecs.reject e importerrors.txt

Com mand Line Interfaces (CLI) 37

Im portDomainResourceRecord

File Format
Col

Field

Accepted Values

Required

Domain

The name of the domain to which the resource records

will be added.

Yes

Domain Type

The name of the domain type to which the domain

belongs. Defaults to Default

No

Owner

Yes

TTL

The OWNER section of the resource record. Note that

this section is specific to the type of resource record.
Refer to the appropriate RFC for exact text that should
be entered.
The Time To Live.

Class

The value currently supported is IN. If not specified,

defaults to IN.

No

Resource Record
Type

The type of resource record being imported.

Yes

Data

The text for the DATA area of the resource record.

Note that this section is specific to the type of resource
record. Refer to the appropriate RFC for exact text that
should be entered.

Yes

Comment

Text to be appended to the resource record.

No

38 IPControl CLI and API Guide

No

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. Typically, 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. However, during the initial setup of the system the queried information from
these tasks can be used to populate the original IPControl model. This CLI then, is used to
perform this initial population of discovered blocks and interfaces.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportElementSnapshot u <userId> -p <pswd>
-t <taskId> [-o <output file>] [-v] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportElementSnapshot.sh u <userId> -p <pswd>
-t <taskId> [-o <output file>] [-v] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportElementSnapshot.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.

-o <output file>

No

The name of the file to write all output. If not specified output will be sent
to STDOUT.

-v

No

Produces verbose output.

Usage Example

This example imports blocks and interfaces discovered by task 12345, and places into the
elementsnapshot.out file any output messages.
$INCHOME/etc/cli/ImportElementSnapshot.sh u joe p joepwd t 12345 -o elementsnapshot.out

Com mand Line Interfaces (CLI) 39

Im portGalaxyDomain

ImportGalaxyDomain
Overview

The ImportGalaxyDomain CLI allows the user to bulk import Galaxy Domains into
IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ImportGalaxyDomainCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-v] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportGalaxyDomain.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-v] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportGalaxyDomain.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-v

No

Produces verbose output.

Usage Example

This example import galaxy domains from the newgdomains.csv file, places into the
newgdomains.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportGalaxyDomain.sh u joe p joepwd f newgdomains.csv
-r newgdomains.reject e importerrors.txt

40 IPControl CLI and API Guide

Im portGalaxyDomain

File Format
Col

Field

Accepted Values

Required

Galaxy Name

Name of the Galaxy to which to assign this domain.

Yes

Domain Name

Domain name, already defined to IPControl, to be assigned

to specified galaxy.

Yes

Domain Type

The name of the domain type to which the domain

belongs. If not specified, the Default domain type will
be used.

No

View

The name of the galaxy view to which to assign this

domain. If specified, the view must exist. If not specified,
the new zone will be created in the view named
'GalaxyDefault.'

No

Com mand Line Interfaces (CLI) 41

Im portNetElement

ImportNetElement
Overview

The ImportNetElement CLI allows the user to bulk import network elements into
IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportNetElementCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportNetElement.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportNetElement.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.

-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.

Usage Example

This example imports Network Elements from the netelements.csv file, places into the
netelements.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportNetElement.sh u joe p joepwd f netelements.csv
r netelements.reject e importerrors.txt

File Format
Col

Field

Accepted Values

Required

Name

The name of the Network Element. This can be

any combination of letters and numbers.

Yes

IP Address/FQDN

The IP address or fully-qualified domain name

(FQDN) of the Network Element. This must be a
valid IPv4 or IPv6 IP address, or a fully-qualified
host name.

Yes

42 IPControl CLI and API Guide

Im portNetElement

Col

Field

Accepted Values

Required

Vendor

The vendor of the Network Element. Vendor

must be predefined in IPControl. If not specified,
defaults to Unknown.

Yes when
Model is
specified.

Model

The model name of the Network Element. Model

must be predefined in IPControl. If not specified,
defaults to Unknown.

Yes when
Vendor is
specified.

Type

The type of Network Element. Accepted values

are cmts, router, switch, or vpn.

Yes

Global Sync

Whether or not to include this Network Element in

the Global Sync process. Accepted values are
True or False (case insensitive).

Yes

Agent Name

The exact name of the IPControl Agent thats

responsible for contacting this Network Service.

Yes

Telnet user

A user name used to telnet to this device.

No

Telnet password

A password used by the telnet user to telnet to this

device.

No

Enable password

Password used to enter enabled or privileged

mode on the device.

No

Read community string

The community string used by SNMP to read

details from this network element. Set this when
using SNMP V1. Otherwise use V3 parameters
below.

No

Interface List

Separated by vertical bars (|).

No

V3 Username

Required if using SNMP V3.

No

V3 Authentication
Protocol

Either MD5 or SHA1. Leave blank or set to

NONE if no authentication.

No

V3 Authentication
Password

Required if field N is set to either MD5 or SHA1

No

V3 Privacy Protocol

Only DES supported at this time. Leave blank or

set to NONE if no privacy.

No

V3 Privacy Password

Required if field P is set to DES.

No

V3 Context Name

SNMP V3 Context name, if needed.

No

V3 Engine ID

SNMP V3 Engine ID, if needed.

No

Com mand Line Interfaces (CLI) 43

Im portNetElementInterface

ImportNetElementInterface
Overview

The ImportNetElementInterface CLI allows the user to bulk import network element
interfaces into IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-v

No

Produces verbose output.

Usage Example

This example imports Network Elements interfaces from the netelementinterfaces.csv file, places
into the netelementinterfaces.reject file any records that could not be imported, and reports errors
to the importerrors.txt file.
$INCHOME/etc/cli/ImportNetElementInterface.sh u joe p joepwd
f netelementinterfaces.csv r netelementinterfaces.reject e importerrors.txt

File Format
Col

Field

Accepted Values

Required

Name

The name of a Network Element already defined

to IPControl.

Yes

Interface Name

The name of the interface being imported.

Yes

Status

The status of the new interface. This can be one of

Disabled, Enabled, or Deployed. The
default is Enabled.

No

44 IPControl CLI and API Guide

Im portNetService

ImportNetService
Overview

The ImportNetService CLI allows the user to bulk import DHCP network services into
IPControl.
Note: This CLI has been deprecated as of IPControl 6.0. Use the ImportDhcpServer CLI
instead. ImportNetService support will be removed in a future release.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportNetServiceCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportNetService.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportNetService.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example imports network services from the netservices.csv file, places into the netservices.reject
file any records that could not be imported, and reports errors to the importerrors.txt file.
$INCHOME/etc/cli/ImportNetService.sh u joe p joepwd f netservices.csv
r netservices.reject e importerrors.txt

File Format
Col

Field

Accepted Values

Required

Name

The name of the Network Service. This can be any

combination of letters and numbers.

Yes

IP Address/FQDN

The IP address or fully-qualified domain name

(FQDN) of the Network Service. This must be a
valid IPv4 or IPv6 IP address, or a fully-qualified
host name.

Yes

Com mand Line Interfaces (CLI) 45

Im portNetService

Col

Field

Accepted Values

Required

Type

The type of Network Service. Accepted value is

dhcp. If this column is left blank, dhcp is
assumed.

No

Product name

The Network Service product name. This must be

a value already defined in IPControl, for example,
INS DHCP or CNR DHCP.

Yes

Agent name

The name of the IPControl Agent thats

responsible for contacting this Network Service.

Yes

Global Sync

Whether or not to include this Network Service in

the Global Sync process. Accepted values are
True or False (case insensitive). If no value is
specified, this will default to False.

No

Collection Method

The method by which the IPControl Agent will

collect data from the Network Service. Accepted
values are scp or ftp.

No

For CNR servers, the collection type may also be

cnrsdk for those servers that are managed via the
SDK.
H

User name for

collection

The username used by the collection method (scp

or ftp) to log in to the remote server.

No

If the collection method is cnrsdk, this field is not

used.
I

Password for collection

The password used by the collection method (scp

or ftp) to log in to the remote server. Used in
conjunction with the User name for collection.

No

If the collection method is cnrsdk, this field is not

used.
J

Collection port

The port number the collection method (scp or

ftp) is listening on. If no value is specified, this will
default to 22 if the collection method is scp, and 21
if the collection method is ftp.

No

For CNR servers managed via the SDK, this will

be the port that the CNR server is listening on for
connections.
K

Container(s)

No longer used.

VendorInfo

Vendor specific information for the products

collection type. Each item of information is
specified in this single field by separating each field
with the | character.
For collection types qip, adc, msft and isc, the
information includes the DHCP Configuration file
pathname and DHCP Active Lease file pathname.
For example,
/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 that are not managed via
the SDK, the information includes the
Path/Executable of NRCD command, the

46 IPControl CLI and API Guide

No

Im portNetService

Col

Field

Accepted Values

Required

NRCMD user id, the NRCMD password and the

Cluster Name. For example,
/opt/cnr/bin/nrcmd|myuserid|mypass|
cluster1
For CNR servers managed via the SDK, the
directory component is not required, however the
username and password to connect to the CNR
machine are required as the second and third fields.
For example,
|myuserid|mypass
M

WarningThreshold

Default scope utilization warning threshold.

Provide warnings when usage of a pool assigned to
this service is exceeded. If no value is specified,
this will default to 90.

No

Com mand Line Interfaces (CLI) 47

Im portNetServiceWithTemplate

ImportNetServiceWithTemplate
Overview

The ImportNetServiceWithTemplate CLI allows the user to bulk import DNS servers
into IPControl by applying a pre-defined Server Template.
Using the IPControl GUI, create a DNS Server Template. This is accomplished through the
System Network Services Policies & Options DNS Server Templates. Then use this
CLI to create new servers using that template.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportNetServiceWithTemplateCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportNetServiceWithTemplate.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportNetServiceWithTemplate.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.

-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.

Usage Example

This example imports network services with template from the netserviceswithtemp.csv file, places
into the netserviceswithtemp.reject file any records that could not be imported, and reports errors
to the importerrors.txt file.
$INCHOME/etc/cli/ImportNetServiceWithTemplate.sh u joe p joepwd
f netserviceswithtemp.csv r netserviceswithtemp.reject e importerrors.txt

File Format
Col

Field

Accepted Values

Required

Name

The name of the Network Service. This can be any

combination of letters and numbers and should be
a fully qualified domain name (FQDN).

Yes

48 IPControl CLI and API Guide

Col

Field

Accepted Values

Required

IP Address

The IP address of the Network Service. This must

be a valid IPv4 IP address.

Yes

Type

The type of Network Service. Accepted value is

dns. If this column is left blank, dns is assumed.

No

Template name

The name of the DNS Server Template as defined

in System Network Services Policies & Options
DNS Server Templates. For example, UNIX
Standard for INS DNS.

Yes

Agent name

The name of the IPControl Agent that is

responsible for contacting this Network Service as
defined in System Agents.

Yes

Com mand Line Interfaces (CLI) 49

Im portPrefixPool

ImportPrefixPool
Overview

The ImportPrefixPool CLI allows the user to bulk import prefix pools into IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportPrefixPoolCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportPrefixPool.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportPrefixPool.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.

-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.

Usage Example

This example imports prefix pools from the newprefixpools.csv file, places into the
newprefixpools.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportPrefixPool.sh u joe p joepwd f newprefixpools.csv
r newprefixpools.reject e importerrors.txt

File Format
Col

Field

Accepted Values

Required

Start Address

The IP Address of the first address in the pool. This

address must be in a block with an In-Use/Deployed
status.

Yes

Length

The length of the prefix pool.

Yes

Address Pool Type

One of Dynamic PD DHCPv6 or Automatic PD

DHCPv6.

Yes

Name

Prefix Pool name. Defaults to Start Address/Length

No

50 IPControl CLI and API Guide

Im portPrefixPool

Col

Field

Accepted Values

Required

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
Start
address is
not
unique.

Delegated Prefix
Length

The default length of the delegated prefix.

Yes

Longest Prefix
Length

The longest prefix length allowed for delegated prefixes.

CNR DHCP only.

No

Shortest Prefix
Length

The shortest prefix length allowed for delegated

prefixes. CNR DHCP only.

No

Primary Net Service

The name of the DHCP server that will serve addresses

from this pool

No

DHCP Option Set

The name of an Option Set used with this pool.

No

DHCP Policy Set

The name of a Policy Set used with this pool.

No

Allow DHCP Client

Classes

A list of Client Classes that are allowed in this address

pool. Separate the list entries with a vertical bar |.
For example, to allow two client classes named
allowA and allowB, specify:
allowA|allowB

No

Deny DHCP Client

Classes

A list of Client Classes that are NOT allowed in this

address pools. Separate the list entries with a vertical
bar |. For example, to disallow two client classes
named denyA and denyB, specify:
denyA|denyB

No

Com mand Line Interfaces (CLI) 51

Im portRootBlock

ImportRootBlock
Overview

The ImportRootBlock CLI allows the user to bulk import root blocks into IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ImportRootBlockCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportRootBlock.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ImportRootBlock.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.

-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.

Usage Example

This example imports Root Blocks from the newrootblocks.csv file, places into the
newrootblocks.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportRootBlock.sh u joe p joepwd f newrootblocks.csv
r newrootblocks.reject e importerrors.txt

File Format
Col

Field

Accepted Values

Required

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

IP space

The IP block to create. This should be in the

format of a network address (e.g., 10.0.0.0).

Yes

52 IPControl CLI and API Guide

Im portRootBlock

Col

Field

Accepted Values

Required

Block size

The size of the block in short-notation (e.g., 24 for

a 255.255.255.0 network).

Yes

Description

A description of the block. Use \n to separate

lines.

No

Block type

The Block Type for the block. If not specified, a

block type of Any is assumed.

No

Block Name

A name for the block. Defaults to system supplied

name of Address space/Block size.

No

Allow Duplicate 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

Regional Internet
Registry

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

Organization Id

The organization id for the Regional Internet

Registry this space was obtained from. This id must
be predefined in IPControl.

No

Allocation Reason

The name of a pre-existing Allocation Reason. If

Allocation Reason is not currently in IPControl,
this field is skipped.

No

Allocation Reason
Description

A description of the reason for the allocation.

No

SWIP/Net Name

SWIP/Net name for the block.

Yes, if
required
by
Container
rules

Create Reverse
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

Domain Type

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

User Defined Fields

A series of name=value pairs, 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. For example,
UDFone=value one |UDFtwo=value two. If
the UDF type is Checkbox, the valid values are
on or off. If the UDF type is Textarea, use
\n to separate lines.

Yes, for
UDFs
defined as
required
fields.

Com mand Line Interfaces (CLI) 53

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.
Typically, 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. However,
during the initial setup of the system the queried information from these tasks can be used to
populate the original IPControl model. This CLI then, is used to perform this initial
population of discovered address pools.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.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.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.

Usage Example

This example imports address pools discovered by task 12345, places into the
servicesnapshot.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportServiceSnapshot.sh u joe p joepwd t 12345

54 IPControl CLI and API Guide

Im portZone

ImportZone
Overview

The ImportZone CLI allows the user to bulk import DNS zones into IPControl, and to
update existing DNS zones.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example imports zones from the newzones.csv file, places into the newzones.reject file any
records that could not be imported, and reports errors to the importerrors.txt file.
Note: Zone options are not supported in the first release of this service.
$INCHOME/etc/cli/ImportZone.sh u joe p joepwd f newzones.csv -r newzones.reject
e importerrors.txt

CNR Servers

Important! For CNR servers, 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.

Com mand Line Interfaces (CLI) 55

Im portZone

File Format
Col

Field

Accepted Values

Required

Server

The network service name of the DNS Server.

Yes, if
GalaxyNa
me is not
supplied.

Zone type

Specifies the type of zone being imported.

Accepted values are master, slave, forward or
stub.

Yes

Domain Name

Domain name already defined to IPControl

Yes

Domain Type

Domain type name already defined to IPControl.

If not specified, the Default domain type will be
used.

No

Update Zone

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.

No

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

Filename

The name of the zone file that will be generated by

IPControl. If not specified, w ill default to a systemgenerated value based on zone type.

No

Automatic Generation
of NS/GLUE Records

Accepted values are true or false. If not specified,

defaults to true.

No

MNAME

Specifies an alternative name for the primary or

master DNS server that DDNS requests should
be sent to for this zone. If not specified, no
MNAME will be used. This field only applies to
master zones. It will be ignored for all other zone
types and any zone designated as an Alias zone.

No

Allow Zone Transfers

to DNS Listener

Accepted values are true or false. If not specified,

defaults to true. This field only applies to master
zones. It will be ignored for all other zone types.

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

Zone extensions Prior

Specifies the name of the file containing text lines

that will be inserted prior to the resource records
for this zone.

No

Zone extensions After

Specifies the name of the file containing text lines

that will be inserted following the resource records
for this zone.

No

Template Zone

Indicates if the imported zone is intended to be a

template zone.

No

Accepted values are true or false. If not specified,

defaults to false.
56 IPControl CLI and API Guide

Im portZone

Col

Field

Accepted Values

Required

Alias Zone

Indicates if the imported zone is intended to be a

alias zone. The linked template zone will be
chosen by using the zone assigned to the template
domain to which the alias domain is linked.

No

Accepted values are true or false. If not specified,

defaults to false.
P

Galaxy Name

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.
This free text field only applies to master zone types
with dynamic updates enabled and is accepted
without input validation.
Setting this field value to !BLANK! on a zone
update will serve to completely remove the allow update option from the zone.

Update Policy

Dynamic Zone

This field is ignored for non-master zones.

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.
This field is ignored for non-master and non-dynamic
zones.
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.

Yes, when
Dynamic
Zone is
true, one
of Allow
Update
ACL or
Update
Policy
must be
specified.
See Allow
Update
ACL

No

Com mand Line Interfaces (CLI) 57

Im portZoneResourceRecord

ImportZoneResourceRecord
Overview

The ImportZoneResourceRecord CLI allows the user to bulk import DNS resource
records for a zone into IPControl.
Note: this interface should not be confused with the ImportDomainResourceRecord
CLI, which is used to add records to a domain. ImportZoneResourceRecord is only
effective when the Automatic Generation of NS/Glue Records is set to OFF on the target
zone.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ImportZoneResourceRecordCLI u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ImportZoneResourceRecord.sh u <userId> -p <pswd>
-f <import filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example imports resource records from the newresourcerecs.csv file, places into the
newresourcerecs.reject file any records that could not be imported, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/ImportZoneResourceRecord.sh u joe p joepwd f newresourcerecs.csv
r newresroucerecs.reject e importerrors.txt

58 IPControl CLI and API Guide

Im portZoneResourceRecord

File Format
Col

Field

Accepted Values

Required

Server

The network service name of the DNS Server.

Yes

View

The name of the view for this zone. If supplied

the view must exist. If not specified, 'Default' will
be used.

Yes

Zone

The name of the zone, which is the top level

domain name.

Yes

Owner

Yes

TTL

The OWNER section of the resource record. Note

that this section is specific to the type of resource
record. Refer to the appropriate RFC for exact text
that should be entered.
The Time To Live.

Class

The value currently supported is IN. If not

specified, defaults to IN.

No

Resource Record Type

The type of resource record being imported.

Accepted values are A and NS.

Yes

Data

The text for the DATA area of the resource record.

Note that this section is specific to the type of
resource record. Refer to the appropriate RFC for
exact text that should be entered.

Yes

No

Com mand Line Interfaces (CLI) 59

Im portZoneResourceRecord

Exports
Export CLIs allow you to retrieve and filter information from IPControl. Data may be
viewed on the screen, or output into a file suitable for modifying and importing.
Note that user access control lists (ACL) are enforced, which may affect export results. Users
are not allowed to perform exports on data without the appropriate Read rights in the system.

60 IPControl CLI and API Guide

ExportChildBlock

ExportChildBlock
Overview

The ExportChildBlock CLI exports a list of all the Child Blocks into a specified file. This
file can be modified and then imported using the ImportChildBlock CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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.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. If no file name is specified,
results are outputted to the screen.

-b <block
address/size>

No

Filter. Specify the CIDR notation of a block. That is, specify the
starting IP address for the block, followed by the block size, separated
by a slash /. For example, 10.0.0.0/24. The wildcard character * can
be used in the start address only.

-c <container name>

No

Filter. Specify the name of a specific container or use the wildcard

character * to perform a partial match on the container name.

-d <user defined field

name=value>

No

Filter. Specify a User Defined Field (UDF) attached to a block. The

UDF is specified using the syntax name=value, where name is the name
of the UDF, and value is the value of the UDF. For wildcarding, use a
* character within double quotes, i.e., d udfName=value*. Also
surround the parameter with double quotes if there is an embedded
blank in the filter string.

-de [description]

No

Filter. Allows you to filter export based on the block description.

Surround the parameter with double quotes if there is an embedded
blank, for example, -de two words.

Com mand Line Interfaces (CLI) 61

ExportChildBlock

Param eter

Required Description

-ex

No

-h (--recurse)

No

-i <IP address>

No

Filter. Specify an IP address which falls within the start and end
address of a block.

-j <Interface>

No

Filter. Specify the name of an interface to which the block must be

attached.

Expanded mode. Additional columns will be appended for each UDF

defined in the exported records. The first row of the file will be a
comment header row, beginning with ^, with each columns field
name, including the tag name for each UDF. The architected UDF
column P will contain Expanded. See below for an example.
Only valid when pb is specified. When present, recursively exports
child blocks of the named parent block.

-l (--includeFreeBlocks) No

Flag. By default, the list of exported child blocks will not include the
free blocks which are maintained by IPControl. Include this Boolean
option for the free blocks to be included in the export.

-n <block name>

No

Filter. Specify the name of a specific block or use the wildcard

character * to perform a partial match on the name. If the block name
contains embedded spaces, surround the name with double-quotes .

-pb < parentBlock >

No

Filter. Specify the name of the specific blocks parent or starting

address followed by /CIDR size

-pc <parentContainer>

No

Filter. Specify the name of the specific blocks parent blocks container.
Only valid when accompanied by pb option. Specifying the container
can help to avoid ambiguity. A fully qualified container name may be
supplied.

-r <IP address range>

No

Filter. Specify a range of IP addresses which span one or more blocks.

The format of the range is specified as start-end. For example,
10.0.0.0-10.0.255.255.

-st <block status>

No

Filter. Specify the block status. {free, aggregate, reserved, subnet,

fullyassigned}. Note: if blocks of status free are desired, the l option
must be used.

-t <block type>

No

Filter. Specify the name of a specific block type or use the wildcard
character * to perform a partial match on the block type name.

Usage Example

This example exports all child blocks to the file rbexport.csv in the current directory.
$INCHOME/etc/cli/ExportChildBlock.sh u joe p joepwd f rbexport.csv

This example exports child blocks that begin with the name MyBlock and that are of block
type Private to the file rbexport.csv.
$INCHOME/etc/cli/ExportChildBlock.sh u joe p joepwd f rbexport.csv n MyBlock*
-t Private

Export via parent block name parameter eexample

This example exports all child blocks of the parent block named 172.16.0.0/23.
$INCHOME/etc/cli/ExportChildBlock.sh u joe p joepwd f rbexport.csv pb 172.16.0.0/23

This example exports all child blocks of the parent block named 172.16.0.0/23
recursively.

62 IPControl CLI and API Guide

ExportChildBlock

$INCHOME/etc/cli/ExportChildBlock.sh u joe p joepwd f rbexport.csv pb 172.16.0.0/23 -h

This example exports all child blocks of the parent block named 172.16.0.0/23 contained
in container /InControl/Canada/North.
$INCHOME/etc/cli/ExportChildBlock.sh u joe p joepwd f rbexport.csv pb 172.16.0.0/23
pc /InControl/Canada/North

Export using expanded format example

This example exports all child blocks in the container named CA, with the output in expanded
format.
$INCHOME/etc/cli/ExportChildBlock.sh u joe p joepwd f cexport.csv c CA ex

Here is the output file:

Note the following:

The first row is a header line, beginning with ^. The column headers beyond the
architected column AA contain the user defined field tags.

Column P contains Expanded when the row includes user defined fields beyond
column AA. Row 3 has no user defined fields defined for that block.
Only those user defined field tags defined for the blocks exported (based on container
and blockType) will have columns in the output file.

In this example, columns AB-AD contain the values for the user defined fields. If
there is no value, as in row 2 column AD, the cell will be blank.

You can use ImportChildBlock to import an expanded format exported file by using
the o (overwrite) parameter.

File Format

The format for the export file is as follows.

Note: This is the same format that the ImportChildBlock CLI requires.
Col

Field

Accepted Values

Required

Container

The name of the 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

Com mand Line Interfaces (CLI) 63

ExportChildBlock

Col

Field

Accepted Values

Required

Block size | IPV6

The size of the block in short-notation (e.g., 24 for

a 255.255.255.0 network).

Yes | No

If an IPV6 block is exported, the block size will be

followed by |true, for IPV4 |false.
C

Block type

The Block Type for the block If not specified, a

block type of Any is assumed.

No

Block Name

A name for the block. Defaults to system supplied

name of Address space/Block size.

No

Address Block

The address block to allocate. If no address block

is specified, space will be auto-allocated.

No

Description

A description of the block.

No

Current Status

The current status of the block. Accepted values

are: Deployed, FullyAssigned, Reserved,
Aggregate.

Yes

SWIP Name

SWIP name for the block.

Yes, if
required by
Container
rules

Allocation Reason

The name of a pre-existing Allocation Reason. If

Allocation Reason is not currently in IPControl,
this field is skipped.

No

Allocation Reason
Description

A description of the reason for the allocation.

Wrap the statement in quotes if it contains any
commas.

No

Allocation Template

If this block is being added to a device container

with blockStatus=Deployed, the name of the
allocation template to use to create address pools
from the newly created block.

No

Interface Name

If this block is being added to a device container,

the name of the interface to attach the block to.

Yes, if
block is
being added
to device
container.
Otherwise,
no.

Interface Offset or
Address

The specific address(es) for the interface IP

address(s). Multiple addresses will be separated by
the | character. For example,
10.0.0.1|10.0.0.2|10.0.0.3

No. An
offset of 1
is assumed
if none is
specified.

Create Reverse
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

Domain Type

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

64 IPControl CLI and API Guide

ExportChildBlock

Col

Field

Accepted Values

Required

User Defined Fields

A series of name=value pairs, 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. For example,
UDFone=value one |UDFtwo=value two. If
the UDF type is Checkbox, the valid values are
on or off.

Yes, for
UDFs
defined as
required
fields.

When this column contains the word Expanded,

the ex option was invoked. See below for an
example of the results.
Q

Exclude From
Discovery

Flag indicating if this subnet should be included in

Host Discovery tasks. Accepted values are true or
false. If not specified, defaults to false.

No

Valid only for Deployed blocks.

R

DHCP Option Set

The name of a DHCP Option Set defined within

IPControl that should apply to this subnet. Valid
only for Deployed blocks.

No

DHCP Policy Set

The name of a DHCP Policy Set defined within

IPControl that should apply to this subnet. Valid
only for Deployed blocks.

No

DNS Servers

The list of default DNS Servers for this subnet.

This list is supplied to DHCP clients on this
subnet. The server name or IP Address is valid.
For multiple servers, separate the server names
with a vertical bar (|). Valid only for Deployed
blocks.

No

Default Gateway

The default gateway address for this subnet. This

address is supplied to DHCP clients on this
subnet. Valid only for Deployed blocks.

No

Primary DHCP Server

The name or IP Address of the primary DHCP

server for this address space. Valid only for
Deployed blocks.

No

Failover DHCP Server

The name or IP Address of the failover DHCP

Server for this address space. Valid only for
Deployed blocks.

No

DNS Forward Domains

The list of DNS Forward domains for this address

space, separated by a vertical bar (|). This list will
appear in the GUI when choosing domains for
devices. To specify a domain type, specify the
domain followed by / followed by the domain
type. Valid only for Deployed blocks. For
example:

No

hr.ins.com.|dmz.com./External
In this example, hr.ins.com uses the default
domain type, and dmz.com is of type External.

Com mand Line Interfaces (CLI) 65

ExportChildBlock

Col

Field

Accepted Values

Required

DNS Reverse Domains

The list of DNS Reverse domains for this address

space, separated by a vertical bar (|). This list will
appear in the GUI when choosing domains for
devices. To specify a domain type, specify the
domain followed by / followed by the domain
type. Valid only for Deployed blocks. For
example:

No

0-15.1.0.10.in-addr.arpa. /External |40.10.inaddr.arpa.

In this example, 0-15.1.0.10.in-addr.arpa. is of type
External, and 40.0.10.in-addr.arpa. uses the
default domain type.
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. Used to provide this information to
DHCP for Dynamic Address types. Multiple
WINS servers may be specified, separated by a
comma.
Exported with no value as a place holder for
consistency with ImportChildBlock.
Flag indicating if this subnet is primary. Accepted
values are true or false. Valid only for Deployed
blocks in device containers.

No

No
No

ExportContainer

ExportContainer
Overview

The ExportContainer CLI exports containers into a specified file. This file can be
modified and then imported using the ImportContainer CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ExportContainerCLI u <userId> -p <pswd>
[-f <export filename>] [-n containerName] [-d udfName=value] [-fp] [-v] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ExportContainer.sh u <userId> -p <pswd>
[-f <export filename>] [-n containerName] [-d udfName=value] [-fp] [-v] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ExportContainer.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. If omitted, results are sent to
the screen.

-n [containerName]

No

Filter. Allows you to filter export based on the name of the container.
Use a * character (within single quotes, i.e., n ContainerName*)
for wildcarding. NOTE: if both n and d are specified, the export
includes containers that satisfy both criteria.

-d [udfName=value]

No

Filter. Allows you to filter export based the user defined field name and
value. Only containers that have this UDF set to this value will be
exported. For wildcarding, use a * character w ithin double quotes,
i.e., d udfName=value*. Also surround the parameter with single
quotes if there is an embedded blank in the filter string. NOTE: if both
n and d are specified, the export includes containers that satisfy both
criteria.

-fp

No

Populates the parent container field using the long format, for example:
IPControl/Texas/Dallas

-v

No

Produces verbose output.

Usage Examples

This example exports all containers to the file named exportcontainer.csv file in the current
directory.
$INCHOME/etc/cli/ExportContainer.sh u joe p joepwd f exportcontainer.csv

This example exports all containers whose name starts with the characters West.
Com mand Line Interfaces (CLI) 67

ExportContainer

$INCHOME/etc/cli/ExportContainer.sh u joe p joepwd f exportcontainer.csv n West*

This example exports all containers that have a UDF named customer with the value
12345.
$INCHOME/etc/cli/ExportContainer.sh u joe p joepwd f exportcontainer.csv
d customer=12345

File Format

The format for the export file is as follows.

Note: This is the same format that the ImportContainer CLI requires.
Col

Field

Accepted Values

Col

Field

Accepted Values

Container Name

The name of the container.

Container Description

A brief description of the container.

Parent Container

The name of the parent container for this container.

Container Type

Either logical or device.

Rule1

A listing of the valid block types for this container, separated by /.

Block types that with an associated information template have the
template name concatenated to the block type name, separated by a
|.

Rule2

A listing of the block types enabled for root block creation,

separated by /.

Rule3

A listing of the block types that can be used for space allocation
from the parent container, separated by /.

Rule4

A listing of the block types for which SWIP Names are required,
separated by /.

Rule5

A listing of the valid device types for this container, separated by /.

Device types that with an associated information template have the
template name concatenated to the device type name, separated by a
|. If no device types are allowed, the list will contain the keyword
NONE.

Information Template

The name of a pre-existing information template to be associated

with this container.

User Defined Fields

User defined field values, in name=value format. Multiple values

are separated by a vertical bar (|).
For example:
fieldOne=valueOne|fieldTwo=valueTwo
If the UDF type is Checkbox, the valid values are on or off.

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. The history
records are created each time the Global Utilization Rollup task is
run. Accepted values are true or false.

ExportDevice

ExportDevice
Overview

The ExportDevice CLI exports a list of all the Devices into a specified file. This file can be
modified and then imported using the ImportDevice CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.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.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.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. If no file name is
specified, results are outputted to the screen.

-at [addressType]

No

Filter. Allows you to filter export based on address type. Accepted

values are: Static, Dynamic DHCP, Automatic DHCP, Manual
DHCP, Interface and Reserved. For DHCP V6: Dynamic NA
DHCPv6, Automatic NA DHCPv6, Manual NA DHCPv6,
Dynamic TA DHCPv6 and Automatic TA DHCPv6.

-b [blockName]

No

Filer. Allows you to filter export based on block name.

-c [containerName]

No

Filter. Allows you to filter export based on the name of the

container the device is located in.

-d [udfName=value]

No

Filter. Allows you to filter export based on the user defined name
and value of the device. For wildcarding, use a * character within
double quotes, i.e., d udfName=value*. Also surround the
parameter with double quotes if there is an embedded blank in the
filter string.

Com mand Line Interfaces (CLI) 69

ExportDevice

Param eter

Required

Description

-de [description]

No

Filter. Allows you to filter export based on the device description.

-e [devicetype]

No

Filter. Allows you to filter export based the user device type name.

-ex

No

Expanded mode. Additional columns will be appended for each

UDF defined in the exported records. The first row of the file will
be a comment header row, beginning with ^, with each columns
filed name, including the tag name for each UDF. The architected
UDF column L will contain Expanded. See below for an example.

-h

No

Filter. Must be accompanied with c parameter. Specifies to recursively

include all devices contained in child containers of specified c
parameter filter.

-hw [mac address]

No

Filter. Allows you to filter export based on the MAC Address.

-i [ipaddress]

No

Filter. Allows you to filter export based the ipaddress.

-m [domain]

No

Filter. Allows you to filter export based the domain name.

-n [name]

No

Filter. Allows you to filter export based on the device hostname.

-r [ipaddress1/ipaddress2]

No

Filter. Allows you to filter export based on an address range

between ipaddress1 and ipaddress2 inclusive.

-t [blocktype]

No

Filter. Allows you to filter export based on block type name.

-v

No

Produces verbose output.

-vf [true|false]

No

Filter. Allows you to filter export based on virtual flag.

Usage Examples

This example exports all devices to file named exportdevice.csv in the current directory.
$INCHOME/etc/cli/ExportDevice.sh u joe p joepwd f exportdevice.csv

This example exports devices that contain an IP address within the range of 10.0.0.1
through 10.0.0.200 inclusive, to the file exportdevice.csv.
$INCHOME/etc/cli/ExportDevice.sh u joe p joepwd f exportdevice.csv
r 10.0.0.1/10.0.0.200

This example exports devices that are located in the container named Exton to the file
exportdevice.csv.
$INCHOME/etc/cli/ExportDevice.sh u joe p joepwd f exportdevice.csv c Exton

70 IPControl CLI and API Guide

ExportDevice

Export using expanded format example

This example exports devices in the container named Pennsylvania, with the
output in expanded format.
$INCHOME/etc/cli/ExportDevice.sh u joe p joepwd f cexportdevice.csv c Pennsylvania
ex

Here is the output file:

Note the following:

The first row is a header line, beginning with ^. The column headers
beyond the architected column R contain the user defined field tags.
Column L contains Expanded when the row includes user defined
fields beyond column R. Row 5 has no user defined fields defined for
that device.
Only those user defined field tags defined for the devices exported (based on
container and deviceType) will have columns in the output file.

In this example, columns S-X contain the values for the user defined fields. If there is no
value, as in row 6 column U, the cell will be blank. In this example, when
deviceType=Router or Printer, columns S-V are used. When deviceType=PC, W and X
are used.

You can use ImportDevice to import an expanded format exported

file by using the o (overwrite) parameter.

Com mand Line Interfaces (CLI) 71

ExportDevice

File Format

The format for the export file is as follows.

Note: This is the same format that the ImportDevice CLI requires.
Col

Field

Accepted Values

Required

IP Address

The IP address of the device and its device

interfaces delimited by |.

Yes

Address Type

The Address type of the device.

Yes

Hostname

The hostname of the device.

Yes

Device Type

The devices device type.

Yes

Hardware Type

The devices hardware type.

No

Mac Address

The Mac Address of the device and its device

interfaces delimited by |

No

Resource Record Flag

true if the device is to automatically create an A

or AAAA record upon import, false if not.

No

Domain Name

The devices domain name.

No

Container Name

The container name the device is located in.

Yes

Domain Type

The devices domain type.

No

Description

The devices description.

No

User Defined Fields

The devices user defined field and values delimited

by |.

No

When this column contains the word Expanded,

the ex option was invoked. See below for an
example of the results.
M

Aliases

The devices alias names

No

Duplicate warning

False if this is a duplicate, true if not.

No

Interface Names

The devices interface names

No

Exclude from Discovery

flags

The flags for excluding the devices IP addresses

from host discovery.

No

Virtual

Indicates a virtual address

No

DUID

DHCP Unique Identifier

No

72 IPControl CLI and API Guide

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 devices Resource Record tab within the user
interface. This file can be modified and then used with the
ImportDeviceResourceRecord CLI or the ModifyDeviceResourceRecord CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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.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. If no file name is
specified, results are outputted to the screen.

No

Filter. Allows you to filter export based on the name of the

container the device is located in.

No

Filter. Allows you to filter export based the user defined name
and value the device owns.

No

Filter. Allows you to filter export based the user device type
name.

No

Filter. Allows you to filter export based the devices IP

Address.

No

Filter. Allows you to filter export based on the domain name

of the device.

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

ExportDeviceResourceRecord

Param eter

Required

Description

-n <name>

No

Filter. Allows you to filter export based on the device

hostname.

-r <ipaddress1/ipaddress2>

No

Filter. Allows you to filter export based on an address range

between ipaddress1 and ipaddress2 inclusive.

-t <blocktype>

No

Filter. Allows you to filter export based on block type name.

-b <blockName>

No

Filter. Allows you to filter export based on block name.

No

Filter. Must be accompanied with c parameter. Specifies to

recursively include all devices contained in child containers of
specified c parameter filter.

No

To specify that the export output should be in the format used

by ImportDeviceResourceRecord, use I. Use M for the
ModifyDeviceResourceRecord format. The default is I.

No

There can be a very large number of resource records exported

with this command. The default batch size for each call to the
web service is 1000 devices. If you receive the error, Exception
in thread "main" java.lang.OutOfMemoryError: Java heap space, you
can use this parameter to specify a smaller batch size, for
example, -s 500. You can also edit the command file and
change the Xmx parameter.

No

Produces verbose output.

-h

-o <option>

-s <batch-size>

-v

Usage Examples

This example exports all device resource records (that appear on the devices Resource Record
tab within the user interface) for the device at 10.0.0.24, to a file named exportdevicerr.csv in
the current directory. The output is formatted for the ImportDeviceResourceRecord
CLI.
$INCHOME/etc/cli/ExportDeviceResourceRecord.sh u joe p joepwd i 10.0.0.24
f exportdevicerr.csv

This example exports all device resource records (that appear on the devices Resource Record
tab within the user interface) for the device with hostname switch00024 to a file named
exportdevicerr.csv in the current directory. The output is formatted for the
ModifyDeviceResourceRecord CLI.
$INCHOME/etc/cli/ExportDeviceResourceRecord.sh u joe p joepwd n switch00024
f exportdevicerr.csv o M

This example exports all device resource records (that appear on a devices Resource Record
tab within the user interface) for devices located in container Exton to a file named
exportdevicerr.csv in the current directory. The output is formatted for the
ModifyDeviceResourceRecord CLI.
$INCHOME/etc/cli/ExportDeviceResourceRecord.sh u joe p joepwd c Exton exportdevicerr.csv
o M

74 IPControl CLI and API Guide

ExportNetElement

File Format

The format for the export file when o I is specified is as follows.

Note: This is the same format that the ImportDeviceResourceRecord CLI requires.
Col

Field

Accepted Values

Domain

The name of the domain to which the resource records belongs.

Domain Type

The name of the domain type to which the domain belongs.

Defaults to Default

Owner

The OWNER section of the resource record. Note that this section
is specific to the type of resource record. Refer to the appropriate
RFC for exact text that should be entered.

Host Name

The device host name.

IP Address

The IP Address of the Device.

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. The container is then used to uniquely
determine the device.

TTL

The Time To Live.

Class

The value currently supported is IN. If not specified, defaults to

IN.

Resource Record Type

The type of resource record.

Data

The text for the DATA area of the resource record. Note that this
section is specific to the type of resource record. Refer to the
appropriate RFC for exact text that should be entered.

Comment

Text appended to the resource record.

The format for the export file when o M is specified will be of the format that the
ModifyDeviceResourceRecord CLI requires.
For example, suppose a device at 10.0.0.24 has 4 resource records (that appear on the devices
Resource Record tab within the user interface). The set of attribute-value pairs before the
colon identifies the record to be changed. The set following the colon specifies the values to
be changed. All of the values that can be modified are exported.
ipAddress=10.0.0.24,container=IPControl/Texas/Dallas,owner=switch00026,domain=mycompany.com
,domainType=Default,resourceRecType=A:owner=switch00026,resourceRecType=A,TTL=2400,data=10.
0.0.24,domain=mycompany.com,domainType=Default,comment=
ipAddress=10.0.0.24,container=IPControl/Texas/Dallas,owner=24.0.0,domain=10.in-addr.arpa,do
mainType=Default,resourceRecType=PTR:owner=24.0.0,resourceRecType=PTR,TTL=2400,data=switch0
0026.mycompany.com,domain=10.in-addr.arpa,domainType=Default,comment=
ipAddress=10.0.0.24,container=IPControl/Texas/Dallas,owner=switch00026,domain=mycompany.com
,domainType=External,resourceRecType=A:owner=switch00026,resourceRecType=A,TTL=2400,data=10
.0.0.24,domain=mycompany.com,domainType=External,comment=
ipAddress=10.0.0.24,container=IPControl/Texas/Dallas,owner=24.0.0,domain=10.in-addr.arpa,do
mainType=External,resourceRecType=PTR:owner=24.0.0,resourceRecType=PTR,TTL=2400,data=switch
00026.mycompany.com,domain=10.in-addr.arpa,domainType=External,comment=

Com mand Line Interfaces (CLI) 75

ExportNetElement

ExportNetElement
Overview

The ExportNetElement CLI exports a list of all the Network Elements into a specified
file. This file can be modified and then imported using the ImportNetElement CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.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.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.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. If no file name is
specified, results are outputted to the screen.

-n <NetElement Name>

No

Filter. Allows you to filter export based on specific fields. See file
format for accepted values. If the network element name contains
embedded spaces, surround the name with double-quotes, for
example, exton closet .

-i <IP Address or host

name>

No

Filter. Allows you to filter export based on specific fields. See file
format for accepted values.

-vendor <Network
Element vendor>

No

Filter. Allows you to filter export based on specific fields. See file
format for accepted values. If the vendor name contains
embedded spaces, surround the name with double-quotes.

-model <Network
Element model>

No

Filter. Allows you to filter export based on specific fields. See file
format for accepted values. If the model name contains embedded
spaces, surround the name with double-quotes.

-e <Element type>

No

Filter. Allows you to filter export based on specific fields. See file
format for accepted values.

-globalSync <Y|N>

No

Filter. Allows you to filter export based on specific fields. See file
format for accepted values.

76 IPControl CLI and API Guide

ExportNetElement

Param eter

Required

Description

-agent <Agent Name>

No

Filter. Allows you to filter export based on specific fields. See file
format for accepted values. If the agent name contains embedded
spaces, surround the name with double-quotes.

-c <Container Name>

No

Filter. Allows you to filter export based on container. If the

container name contains embedded spaces, surround the name
with double-quotes, for example, New York .

-o

No

The format option is not implemented in this CLI.

-s

No

The batch size option is not implemented in this CLI.

-v

No

Provides verbose output.

Usage Example

This example exports all network elements to an neexport.csv file in the current directory.
$INCHOME/etc/cli/ExportNetElement.sh u joe p joepwd f neexport.csv

This example exports Cisco network elements that are not included in the GlobalSync
process to the file neexport.csv.
$INCHOME/etc/cli/ExportNetElement.sh u joe p joepwd f neexport.csv globalSync N
vendor Cisco Systems

File Format

The format for the export file is as follows.

Note: This is the same format that the ImportNetElement CLI requires.
Col

Field

Accepted Values

Required

Name

The name of the Network Element. This can be

any combination of letters and numbers.

Yes

IP Address/FQDN

The IP address or fully-qualified domain name

(FQDN) of the Network Element. This must be a
valid IPv4 or IPv6 IP address, or a fully-qualified
host name.

Yes

Vendor

The vendor of the Network Element.

Yes

Model

The model name of the Network Element.

Yes

Type

The type of Network Element. Accepted values

are CMTS, router, switch, or vpn.

Yes

Global Sync

Whether or not to include this Network Element in

the Global Sync process. Accepted values are
True or False (case insensitive).

Yes

Agent Name

Yes

Telnet user

The exact name of the IPControl Agent thats

responsible for contacting this Network Service.
A user name used to telnet to this device.

Telnet password

A password used by the telnet user to telnet to this

device.

No

Enable password

Password used to enter enabled or privileged

mode on the device.

No

Read community string

The community string used by SNMP to read

details from this network element.

No

Interfaces

A list of enabled interfaces.

No

No

Com mand Line Interfaces (CLI) 77

ExportNetElement

Col

Field

Accepted Values

Required

V3 Username

Required if using SNMP V3. Blank if V1 or no

SNMP.

No

V3 Authentication
Protocol

Either MD5 or SHA1. Blank if V1 or no SNMP

No

V3 Authentication
Password

Authentication password. Blank if V1 or no SNMP

No

V3 Privacy Protocol

Privacy Protocol. Blank if V1 or no SNMP

No

V3 Privacy Password

Privacy Password. Blank if V1 or no SNMP

No

V3 Context Name

SNMP V3 Context name. Blank if V1 or no SNMP

No

V3 Engine ID

SNMP V3 Engine ID. Blank if V1 or no SNMP

No

78 IPControl CLI and API Guide

ExportNetService

ExportNetService
Overview

The ExportNetService CLI exports a list of all the DHCP Network Services into a
specified file. This file can be modified and then imported using the ImportNetService
CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.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.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.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, in CSV

format. If no file name is specified, results are
outputted to the screen.

-name <NetService Name>

No

Filter. Allows you to filter export based on specific

fields. See file format for accepted values.

-address <IP Address or host name>

No

Filter. Allows you to filter export based on specific

fields. See file format for accepted values.

-product <Product name>

No

Filter. Allows you to filter export based on specific

fields. See file format for accepted values. If the
product name contains embedded spaces, surround the
name with double-quotes, for example, ISC DHCP
3.x.

-agent <Agent name>

No

Filter. Allows you to filter export based on specific

fields. See file format for accepted values. If the agent
name contains embedded spaces, surround the name
with double-quotes, for example, Executive Agent.

Com mand Line Interfaces (CLI) 79

ExportNetService

-c <Container Name>

No

Filter. Allows you to filter export based on container.

If the container name contains embedded spaces,
surround the name with double-quotes, for example,
New York .

- globalsync <Y|N>

No

Filter. Allows you to filter export based on specific

fields. See file format for accepted values.

-o

No

The format option is not implemented in this CLI.

-s

No

The batch size option is not implemented in this CLI.

-type

No

The type option is not implemented in this CLI.

-v

No

Provides verbose output.

Usage Example

This example exports network services to an nsexport.csv file in the current directory.
$INCHOME/etc/cli/ExportNetService.sh u joe p joepwd f nsexport.csv

This example exports network services using the product INS DHCP to the standard output
(usually screen).
$INCHOME/etc/cli/ExportNetService.sh u joe p joepwd product INS DHCP

File Format

The format for the export file is as follows.

Note: This is the same format that the ImportNetService CLI requires.
Col

Field

Accepted Values

Required

Name

The name of the Network Service. This can be any

combination of letters and numbers.

Yes

IP Address/FQDN

The IP address or fully-qualified domain name

(FQDN) of the Network Service. This must be a
valid IPv4 or IPv6 IP address, or a fully-qualified
host name.

Yes

Type

The type of Network Service. This is always dhcp.

No

Product name

The Network Service product name. This must be

a value already defined in IPControl, for example,
INS DHCP or CNR DHCP.

Yes

Agent name

The exact name of the IPControl Agent thats

responsible for contacting this Network Service.

Yes

Global Sync

Whether or not to include this Network Service in

the Global Sync process. Accepted values are
True or False (case insensitive).

Yes

Collection Method

The method by which the IPControl Agent will

collect data from the Network Service. Accepted
values are scp or ftp.

Yes

User name for

collection

The username used by the collection method (scp

or ftp) to log in to the remote server. Exported as
username.

Yes

Password for collection

The password used by the collection method (scp

or ftp) to log in to the remote server. Used in
conjunction with the User name for collection.
Exported as password.

Yes

80 IPControl CLI and API Guide

ExportNetService

Col

Field

Accepted Values

Required

Collection port

The port number the collection method (scp or

ftp) is listening on. If no value is specified, this will
default to 22 if the collection method is scp, and 21
if the collection method is ftp.

No

Container(s)

No longer used.

VendorInfo

Vendor specific information for the products

collection type. Each item of information is
specified in this single field by separating each field
with the | character.

No

For collection types qip, adc, msft and isc, the

information includes the DHCP Configuration file
pathname and DHCP Active Lease file pathname.
For example,
/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
M

WarningThreshold

Default scope utilization warning threshold.

Provide warnings when usage of a pool assigned to
this service is exceeded. If no value is specified,
this will default to 90.

No

Note: The CLI does not export columns H or I since these could contain sensitive
information. The columns are preserved to maintain conformity with the
ImportNetService CLI.

Com mand Line Interfaces (CLI) 81

ExportPrefixPool

ExportPrefixPool
Overview

The ExportPrefixPool CLI exports a list of all the V6 Prefix Pools into a specified file.
This file can be modified and then imported using the ImportPrefixPool CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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.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, in CSV

format. If no file name is specified, results are
outputted to the screen.

-name <Prefix Pool Name>

No

Filter. Allows you to filter export based on specific

fields. See file format for accepted values.

-ipaddress <IP Address>

No

Filter. Allows you to filter export based on what pools

contain this specific address.

-container <Container name>

No

Filter. Allows you to filter export based on which

pools live in a specific container.

-ipaddressrange < IP Address

/length>

No

Filter. Allows you to filter export based on whether a

range of values falls within the prefix pool. The range
should be of the format IPAddress/length.

-netservice <DHCP Server Name>

No

Filter. Allows you to filter export based on a DHCP

server assigned to that prefix pool.

82 IPControl CLI and API Guide

ExportPrefixPool

Usage Example

This example exports network services to an prefixpoolexport.csv file in the current directory.
$INCHOME/etc/cli/ExportPrefixPool.sh u joe p joepwd f prefixpoolexport.csv

This example exports prefixpools using the netservice INS DHCP to the standard output
(usually screen).
$INCHOME/etc/cli/ExportNetService.sh u joe p joepwd netservice INS DHCP

File Format

The format for the export file is as follows.

Note: This is the same format that the ImportPrefixPool CLI requires.
Col

Field

Accepted Values

Required

Start Address

The IP Address of the first address in the pool. This

address must be in a block with an In-Use/Deployed
status.

Yes

Length

The length of the prefix pool.

Yes

Address Pool Type

Yes

Name

One of Dynamic PD DHCPv6 or Automatic PD

DHCPv6.
Prefix Pool name. Defaults to Start Address/Length

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
Start
address is
not
unique.

Delegated Prefix
Length

The default length of the delegated prefix.

Yes

Longest Prefix
Length

The longest prefix length allowed for delegated prefixes.

CNR DHCP only.

No

Shortest Prefix
Length

The shortest prefix length allowed for delegated

prefixes. CNR DHCP only.

No

Primary Net Service

The name of the DHCP server that will serve addresses

from this pool

No

DHCP Option Set

The name of an Option Set used with this pool.

No

DHCP Policy Set

The name of a Policy Set used with this pool.

No

Allow DHCP Client

Classes

A list of Client Classes that are allowed in this address

pool. Separate the list entries with a vertical bar |.
For example, to allow two client classes named
allowA and allowB, specify:

No

No

allowA|allowB
M

Deny DHCP Client

Classes

A list of Client Classes that are NOT allowed in this

address pools. Separate the list entries with a vertical
bar |. For example, to disallow two client classes
named denyA and denyB, specify:

No

denyA|denyB

Com mand Line Interfaces (CLI) 83

ExportResourceRecordPendingApproval

ExportResourceRecordPendingApproval
Overview

The ExportResourceRecordPendingApproval CLI exports a list of the resource

record updates that are waiting for approval by the invoking administrator. These updates
include those to create, update, or delete a 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.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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.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. If not specified,
results are written to the screen.

No

Filter. Allows you to filter export based on the domain name

of the resource record. The domain names of the exported
records will contain the specified value.

No

Filter. Allows you to filter export based on the domain type of

the resource record.

No

Filter. Allows an approving administrator to filter the export

based on the login id of the administrator requesting the
resource record change.

-x <action>

No

Filter. Allows you to filter export based on the request to

create, update or delete a resource record.

-v

No

Produces verbose output.

-f <export filename>
-m <domain>

-a <domaintype>
-q <requesting admin>

84 IPControl CLI and API Guide

ExportResourceRecordPendingApproval

Usage Examples

This example exports all resource records that are in a pending approval state for
administrator joe to a file named exportpending.csv in the current directory.
$INCHOME/etc/cli/ExportResourceRecordPendingApproval.sh u joe p joepwd
f exportpending.csv

Sample file contents are shown below:

1018, 2009-07-16 23:45:12,jane,Create,example.com.,Default,
Switch3,1800,IN,CNAME,switch00033.example.com.
1019,2009-07-16 21:23:02,jane,Update,example.com.->new.example.com.,
Default,switch00024,1800->2400,IN,A,10.0.0.3,oldcomment->newcomment
1020, 2009-07-17 21:32:22,tom,Delete,example.com.,Default,
RouterSevenWest,1300,IN,CNAME,router00007.test.com.

The following example exports all resource records that are in a pending state for
administrator joe , requested by jane:
$INCHOME/etc/cli/ExportResourceRecordPendingApproval.sh u joe p joepwd
f exportpending.csv q jane

This produces the first two records of the file contents shown in the previous example.
File Format

The format for the export file is described in the table following.
Each line starts with the workflow information:

workflow id

date and time the action was requested

requestors IPControl administrators login id

action requested.
The next two columns contain the domain name and type.
The remaining columns provide a full description of the resource record. For update requests,
old and new values are shown as old value -> new value.
Col

Field

Accepted Values

Workflow id

The id required to approve/reject this change via

ModifyPendingApproval.

Date/Time

The date and time of the approval request.

Administrator

The login id of the administrator submitting the request for

approval.

Action

One of Create, Update, Delete

Domain

The name of the domain to which the resource records belongs.

Domain Type

The name of the domain type to which the domain belongs.

Owner

The OWNER section of the resource record. Note that this section
is specific to the type of resource record. Refer to the appropriate
RFC for exact text format.

TTL

The Time To Live.

Class

The value currently supported is IN.

Com mand Line Interfaces (CLI) 85

ExportResourceRecordPendingApproval

Resource Record Type

The type of resource record.

Data

The text for the DATA area of the resource record. Note that this
section is specific to the type of resource record. Refer to the
appropriate RFC for exact text format.

Comment

Text appended to the resource record.

86 IPControl CLI and API Guide

ExportResourceRecordPendingApprovalStatus

ExportResourceRecordPendingApprovalStatus
Overview

The ExportResourceRecordPendingApprovalStatus CLI exports a list of the

resource record updates that were submitted for approval by the invoking administrator.
These updates include those to create, update, or delete a resource record.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ExportResourceRecordPendingApprovalStatusCLI u <userId>
-p <pswd> [-f <export filename>] [-m <domain>] [-a <domaintype>] [-x <action>]
[-v] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ExportResourceRecordPendingApprovalStatus.sh u <userId>
-p <pswd> [-f <export filename>] [-m <domain>] [-a <domaintype>] [-x <action>]
[-v] [-?]

Via command script (Windows)

%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. If no file name is
specified, results are written to the screen.

No

Filter. Allows you to filter export based on the domain name

of the resource record. The domain names of the exported
records will contain the specified value.

No

Filter. Allows you to filter export based on the domain type of

the resource record.

No

Filter. Allows you to filter export based on the request to

create, update or delete a resource record.

No

Produces verbose output.

-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.
$INCHOME/etc/cli/ExportResourceRecordPendingApprovalStatus.sh u joe p joepwd
f exportstatus.csv

Com mand Line Interfaces (CLI) 87

ExportResourceRecordPendingApprovalStatus

Sample file contents are shown below:

1018, 2009-07-16 23:45:12,joe,Create,example.com.,Default,
Switch3,1800,IN,CNAME,switch00033.example.com.
1019,2009-07-16 21:23:02,joe,Update,example.com.->new.example.com.,
Default,switch00024,1800->2400,IN,A,10.0.0.3,oldcomment->newcomment
1020, 2009-07-17 21:32:22,joe,Delete,example.com.,Default,
RouterSevenWest,1300,IN,CNAME,router00007.test.com.

File Format

The format for the export file is described in the table following.
Each line starts with the workflow information:

workflow id

date and time the action was requested

requestors IPControl administrators login id (same as invoking administrator)

action requested.

The next two columns contain the domain name and type.
The remaining columns provide a full description of the resource record. For update requests,
old and new values are shown as old value -> new value.
Col

Field

Accepted Values

Workflow id

The id required to approve/reject this change via

ModifyPendingApproval.

Date/Time

The date and time of the approval request.

Administrator

The login id of the administrator submitting the request (same as

invoking administrator).

Action

One of Create, Update, Delete

Domain

The name of the domain to which the resource records belongs.

Domain Type

The name of the domain type to which the domain belongs.

Owner

The OWNER section of the resource record. Note that this section
is specific to the type of resource record. Refer to the appropriate
RFC for exact text format.

TTL

The Time To Live.

Class

The value currently supported is IN.

Resource Record Type

The type of resource record.

Data

The text for the DATA area of the resource record. Note that this
section is specific to the type of resource record. Refer to the
appropriate RFC for exact text format.

Comment

Text appended to the resource record.

88 IPControl CLI and API Guide

ExportRootBlock

ExportRootBlock
Overview

The ExportRootBlock CLI exports a list of all the Root Blocks into a specified file. This
file can be modified and then imported using the ImportRootBlock CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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. If no file name is
specified, results are outputted to the screen.

-n <block name>

No

Filter. Specify the name of a specific block or use the wildcard

character * to perform a partial match on the name. If the block
name contains embedded spaces, surround the name with doublequotes .

-b <block address/size>

No

Filter. Specify the CIDR notation of a block. That is, specify the
starting IP address for the block, followed by the block size,
separated by a slash /. For example, 10.0.0.0/24. The wildcard
character * can be used in the start address only.

-t <block type>

No

Filter. Specify the name of a specific block type or use the wildcard
character * to perform a partial match on the block type name.

-c <container name>

No

Filter. Specify the name of a specific container or use the wildcard

character * to perform a partial match on the container name.

-i <IP address>

No

Filter. Specify an IP address which falls within the start and end
address of a block.

-r <IP address range>

No

Filter. Specify a range of IP addresses which span one or more

blocks. The format of the range is specified as start-end. For
example, 10.0.0.0-10.0.255.255.

Com mand Line Interfaces (CLI) 89

ExportRootBlock

Param eter

Required

Description

-d <user defined field

name=value>

No

Filter. Specify a User Defined Field (UDF) attached to a block. The

UDF is specified using the syntax name=value, where name is the
name of the UDF, and value is the value of the UDF. For
wildcarding, use a * character within double quotes, i.e., d
udfName=value*. Also surround the parameter with double quotes
if there is an embedded blank in the filter string.

Usage Example

This example exports all root blocks to a rbexport.csv file in the current directory.
$INCHOME/etc/cli/ExportRootBlock.sh u joe p joepwd f rbexport.csv

This example exports root blocks that begin with the name MyBlock and that are of block
type Private to the file rbexport.csv.
$INCHOME/etc/cli/ExportRootBlock.sh u joe p joepwd f rbexport.csv n MyBlock*
-t Private

File Format

The format for the export file is as follows.

Note: This is the same format that the ImportRootBlock CLI requires.
Col

Field

Accepted Values

Required

Container

The name of the 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

IP space

The IP block to create. This should be in the

format of a network address (e.g., 10.0.0.0).

Yes

Block size

The size of the block in short-notation (e.g., 24 for

a 255.255.255.0 network).

Yes

Description

A description of the block.

No

Block type

The Block Type for the block. If not specified, a

block type of Any is assumed.

No

Block Name

A name for the block. Defaults to system supplied

name of Address space/Block size.

No

Allow Duplicate 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

Regional Internet
Registry

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

Organization Id

The organization id for the Regional Internet

Registry this space was obtained from. This id must
be predefined in IPControl.

No

Allocation Reason

The name of a pre-existing Allocation Reason. If

Allocation Reason is not currently in IPControl,
this field is skipped.

No

90 IPControl CLI and API Guide

ExportRootBlock

Col

Field

Accepted Values

Required

Allocation Reason
Description

A description of the reason for the allocation.

No

SWIP/Net Name

SWIP/Net name for the block.

Yes, if
required
by
Container
rules

Create Reverse
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

Domain Type

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

User Defined Fields

A series of name=value pairs, 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. For example,
UDFone=value one |UDFtwo=value two. If
the UDF type is Checkbox, the valid values are
on or off.

Yes, for
UDFs
defined as
required
fields.

Com mand Line Interfaces (CLI) 91

DeleteAddrPool

Deletes
DeleteAddrPool
Overview

The DeleteAddrPool CLI allows the user to delete Address Pools in the system. This CLI
enables you to specify a file containing a list of address pools to delete.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteAddrPoolCLI u <userId> -p <pswd>
-f <delete filename> [-d] [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteAddrPool.sh u <userId> -p <pswd>
-f <delete filename> [-d] [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteAddrPool.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes the address pools listed in the file addrpools.txt.
$INCHOME/etc/cli/DeleteAddrPool.sh u joe p joepwd f addrpools.txt

File Format

The input file format for DeleteAddrPool is the same as for ImportAddrPool. The
addr pool is identified by its Start Address or Name. Multiple addr pools to be deleted can be
specified.
Col

Field

Accepted Values

Required

Start Address

The IP Address of the first address in

the pool.

Yes

End Address

Ignored

No

92 IPControl CLI and API Guide

DeleteAddrPool

Col

Field

Accepted Values

Required

Address Pool Type

Ignored

No

Name

Address Pool name.

Yes

Share Name

Ignored

No

Container

Ignored

No

Primary Net Service

Ignored

No

Failover Net Service

Ignored

No

DHCP Option Set

Ignored

No

DHCP Policy Set

Ignored

No

Allow DHCP Client Classes

Ignored

No

Deny DHCP Client Classes

Ignored

No

PrefixLength

Ignored

No

Com mand Line Interfaces (CLI) 93

DeleteAggregateBlock

DeleteAggregateBlock
Overview

The DeleteAggregateBlock CLI allows the user to delete an intermediate level Aggregate
block from the block hierarchy. By specifying the block to be deleted, IPControl validates and
deletes the block. It also adjusts the parent block assignments of any child blocks.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteAggregateBlockCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteAggregateBlock.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteAggregateBlock.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes resource records described in the delaggblocks.csv file, place into the
delaggblocks.reject file any records that could not be deleted, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/DeleteAggregateBlock.sh u joe p joepwd f delaggblocks.csv
r delaggblocks.reject e importerrors.txt

94 IPControl CLI and API Guide

DeleteAggregateBlock

File Format
Col

Field

Accepted Values

Required

Container

Yes

Start Address

The name of the container holding the aggregate

block to be deleted. 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.
The start address of the aggregate block.

Block Size

The size of the block in short-notation (e.g., 24 for

a 255.255.255.0 network).

Yes

Block Type

The Block Type for the block If not specified, a

block type of Any is assumed.

No

Block Name

A name for the block. Defaults to system supplied

name of Address space/Block size.

No

Description

A description of the block.

No

SWIP Name

SWIP name for the block.

No

Allocation Reason

The name of a pre-existing Allocation Reason.

No

Allocation Reason
Description

A description of the reason for the allocation.

Wrap the statement in quotes if it contains any
commas.

No

Interface Name

If this block is being added to a device container,

the name of the interface to attach the block to.

No

Interface Offset or
Address

DEPRECATED. This field will be ignored.

No

Create Reverse
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

Domain Type

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

User Defined Fields

A series of name=value pairs, 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. For example,
UDFone=value one |UDFtwo=value two. If the
UDF type is Checkbox, the valid values are on or
off.

No

Parent Container

The name of the container where the parent block

resides.

No

Parent Block Address

The address of the parent block

No

Parent Block Size

The size of the parent block in short-notation (e.g.,

24 for a 255.255.255.0 network).

No

Yes

Com mand Line Interfaces (CLI) 95

DeleteBlock

DeleteBlock
Overview

The DeleteBlock CLI allows the user to remove blocks from the system. This CLI allows
you to specify a single block to delete on the command line, or to read a file containing a list
of blocks to delete.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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.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, where the file format lists the container name as
the first column and the block name as the 4 th column. When the x
flag is not present, the file format is blockname, containername.

-f <delete filename>

Either f or
b must be
specified.

The name of the CSV file listing blocks 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-b <block name>

Either f or
b must be
specified.

The name of the block to be deleted. This is typically the CIDR

address, e.g., 10.1.2.0/24. However, if the block name was set
manually during allocation, that value must be used instead.

-c <container name>

Must be
specified if
the block
name is not
unique.

The name of the container holding the block. If this parameter is

supplied, the container is searched for the block to delete.
Otherwise, the whole system is searched.

96 IPControl CLI and API Guide

DeleteBlock

Usage Example

This example deletes the block 10.1.2.0/24 from the system. As mentioned above, this
example assumes that there is only one block with this name in the system.
$INCHOME/etc/cli/DeleteBlock.sh u joe p joepwd b 10.1.2.0/24

File Format
Col

Field

Accepted Values

Required

Block Name

The name of the block to delete. This is typically

the CIDR address, e.g. 10.1.2.0/24. However, if
the block name was set manually during allocation,
that value must be used instead.

Yes

Container Name

The name of the container holding the block.

No

Com mand Line Interfaces (CLI) 97

DeleteContainer

DeleteContainer
Overview

The DeleteContainer CLI allows the user to remove individual containers from the
system. This CLI allows you to specify a file containing a list of containers to delete. Only
containers that contain no blocks, services or child containers are available for deletion.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteContainerCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteContainer.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteContainer.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes the containers listed in the file containers.txt.

$INCHOME/etc/cli/DeleteContainer.sh u joe p joepwd f containers.txt

98 IPControl CLI and API Guide

DeleteContainer

File Format

By design, the input file format for DeleteContainer is the same as for
ImportContainer. This way, 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

Container Name

The name of the container. The name can be

either qualified or unqualified. An unqualified
name must be unique. A qualified name must
start with the root container and include the
complete container path to the desired
container. The container names should be
separated by slashes.

Yes

Container Description

Ignored

No

Parent Container

Ignored

No

Container Type

Ignored

No

Rule1

Ignored

No

Rule2

Ignored

No

Rule3

Ignored

No

Rule4

Ignored

No

Rule5

Ignored

No

Information Template

Ignored

No

User Defined Fields

Ignored

No

Com mand Line Interfaces (CLI) 99

DeleteDevice

DeleteDevice
Overview

The DeleteDevice CLI allows the user to remove individual devices from the system. This
CLI allows you to specify a file containing a list of devices to delete.
Note that this is not used to delete devices of type Interface. Use the ImportChildBlock
CLI with the overwrite parameter to delete Interface-type devices.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteDeviceCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteDevice.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteDevice.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes the devices listed in the file devices.txt.

$INCHOME/etc/cli/DeleteDevice.sh u joe p joepwd f devices.txt

100 IPControl CLI and API Guide

DeleteDevice

File Format

By design, the input file format for DeleteDevice is the same as for ImportDevice. This
way, one can use the same file to the delete a set of devices and then re-add them without
copying data. In the simplest case, only the IP Address is required. 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. In this case, the Container is required to uniquely determine the
device.
Col

Field

Accepted Values

Required

IP Address

The IP Address of the Device

Yes

Address Type

Ignored

No

Host Name

Ignored

No

Device Type

Ignored

No

Hardware Type

Ignored

No

MAC Address

Ignored

No

Resource Record Flag

Ignored

No

Domain Name

Ignored

No

Container

The name of the container holding the

block to which the device belongs.

Yes, if overlapping
space is in use and
the block in which
the device resides is
ambiguous.

Com mand Line Interfaces (CLI) 101

DeleteDomain

DeleteDomain
Overview

The DeleteDomain CLI allows the user to remove individual domains from the system.
This CLI allows you to specify a file containing a list of domains to delete.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteDomainCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteDomain.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteDomain.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-v <verbose>

No

Produces verbose output.

Usage Example

This example deletes the domains listed in the file domains.txt.

$INCHOME/etc/cli/DeleteDomain.sh u joe p joepwd f domains.txt

102 IPControl CLI and API Guide

DeleteDomain

File Format

By design, the input file format for DeleteDomain is the same as for ImportDomain. This
way, one can use the same file to delete a set of domains and then re-add them without
copying data. In the simplest case, only the Domain Name is required. The Domain Type
might also be required if it is not Default.

Col

Field

Accepted Values

Required

Domain Name

The name of the domain being created.

Yes

Domain Type

Domain type name already defined to

IPControl. If not specified, the Default
domain type will be used.

Yes, when not

Default.

Managed

Ignored

No

Delegated

Ignored

No

Reverse

Ignored

No

Derivative

Ignored

No

Template Domain

Ignored

No

Serial Number

Ignored

No

Refresh

Ignored

No

Retry

Ignored

No

Expire

Ignored

No

Negative Cache TTL

Ignored

No

Default TTL

Ignored

No

Contact

Ignored

No

Information Template

Ignored

No

User Defined Fields

Ignored

No

Com mand Line Interfaces (CLI) 103

DeleteDeviceInterface

DeleteDeviceInterface
Overview

The DeleteDeviceInterface CLI allows the user to remove device interfaces from
multi-homed devices in the system. This CLI enables you to specify a file containing a list of
device interfaces to delete.
Note that this is not used to delete devices of type Interface. Use the ImportChildBlock
CLI with the overwrite parameter to delete Interface-type devices.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteDeviceInterfaceCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteDeviceInterface.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteDeviceInterface.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes the device interfaces listed in the file deviceInterfaces.txt.
$INCHOME/etc/cli/DeleteDeviceInterface.sh u joe p joepwd f deviceInterfaces.txt

104 IPControl CLI and API Guide

DeleteDeviceInterface

File Format

The input file format for DeleteDeviceInterface is the same as for ExportDevice.
The device is identified by its IP Address. The container must also be specified if the de vices
IP Address is not unique due to overlapping address space. The interface is identified by its
name. Multiple interfaces to be deleted can be specified.
Col

Field

Accepted Values

Required

IP Address

The IP address of the device. If multiple

interfaces are to be deleted, you may
specify their IP addresses delimited by |
(as output by ExportDevice), but only one
IP Address is required to identify the
device.

Yes

Address Type

Ignored

No

Host Name

Ignored

No

Device Type

Ignored

No

Hardware Type

Ignored

No

MAC Address

Ignored

No

Resource Record Flag

Ignored

No

Domain Name

Ignored

No

Container

The name of the container holding the

block to which the device belongs.

Yes, if overlapping
space is in use and
the block in which
the device resides is
ambiguous.

Domain Type

Ignored

No

Description

Ignored

No

User Defined Fields

Ignored

No

Aliases

Ignored

No

Ignore Warning

Ignored

No

Interface Names

Specify the names of the interfaces to be

deleted, delimited by |.

Yes

Exclude from Discovery

Flags

Ignored

No

Com mand Line Interfaces (CLI) 105

DeleteDeviceResourceRecord

DeleteDeviceResourceRecord
Overview

The DeleteDeviceResourceRecord CLI allows the user to delete DNS resource records
for a device from IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteDeviceResourceRecordCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$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.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes resource records described in the delresourcerecs.csv file, places into the
delresourcerecs.reject file any records that could not be deleted, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/DeleteDeviceResourceRecord.sh u joe p joepwd f delresourcerecs.csv
r delresroucerecs.reject e importerrors.txt

106 IPControl CLI and API Guide

DeleteDeviceResourceRecord

File Format
Col

Field

Accepted Values

Required

Domain

The name of the domain for this resource record.

Yes

DomainType

The domain type of the domain. Defaults to

Default

No

Owner

The OWNER section of the resource record.

Yes

Host Name

The device host name.

Yes, unless
IP Address
is
specified.

IP Address

The IP Address of the Device.

Yes, unless
Host
Name is
specified.

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. The container is then used to uniquely
determine the device.

Yes, if IP
Address in
overlapping space.

TTL

The Time To Live.

No

Class

The value currently supported is IN. If not

specified, defaults to IN.

No

Resource Record Type

The type of resource record being deleted.

Yes

Data

The text for the DATA area of the resource record.

Yes

Com mand Line Interfaces (CLI) 107

DeleteDomainResourceRecord

DeleteDomainResourceRecord
Overview

The DeleteDomainResourceRecord CLI allows the user to delete DNS resource records
for a DNS domain from IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteDomainResourceRecordCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteDomainResourceRecord.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteDomainResourceRecord.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes resource records described in the delresourcerecs.csv file, places into the
delresourcerecs.reject file any records that could not be deleted, and reports errors to the
deleteerrors.txt file.
$INCHOME/etc/cli/DeleteDomainResourceRecord.sh u joe p joepwd f delresourcerecs.csv
r delresroucerecs.reject e deleteerrors.txt

108 IPControl CLI and API Guide

DeleteDomainResourceRecord

File Format
Col

Field

Accepted Values

Required

Domain

The name of the domain for this resource record.

Yes

DomainType

The domain type of the domain. Defaults to

Default.

No

Owner

The OWNER section of the resource record.

Yes

TTL

The Time To Live.

No

Class

The value currently supported is IN. If not

specified, defaults to IN.

No

Resource Record Type

The type of resource record being deleted.

Yes

Data

The text for the DATA area of the resource record.

Yes

Com mand Line Interfaces (CLI) 109

DeleteNetElement

DeleteNetElement
Overview

The DeleteNetElement CLI enables the user to remove individual network elements from
the system. This CLI allows you to specify a file containing a list of network elements to
delete.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.DeleteNetElementCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteNetElement.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteNetElement.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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes network elements listed in the netelements.csv file, places into the
netelements.reject file any records that could not be deleted, and reports errors to the deleteerrors.txt
file.
$INCHOME/etc/cli/DeleteNetElement.sh u joe p joepwd f netelements.csv
r netelements.reject e deleteerrors.txt

110 IPControl CLI and API Guide

DeleteNetElement

File Format

By design, the input file format for DeleteNetElement is the same as the format for
ImportNetElement and ExportNetElement. This way, one can use the same file to
delete a set of network elements and then re-add them without copying data. Specify the
name or the IP address of the network element. If the IP address is not unique, the name
must be specified.
Col

Field

Accepted Values

Required

Name

The name of the Network Element.

Yes, unless a
unique IP
address is
specified

IP Address/FQDN

The IP address or fully-qualified domain name

(FQDN) of the Network Element.

Yes, unless the

name is
specified

Vendor

Ignored

No

Model

Ignored

No

Type

Ignored

No

Global Sync

Ignored

No

Agent Name

Ignored

No

Telnet user

Ignored

No

Telnet password

Ignored

No

Enable password

Ignored

No

Read community string

Ignored

No

Interface List

Ignored

No

V3 Username

Ignored

No

V3 Authentication
Protocol

Ignored

No

V3 Authentication
Password

Ignored

No

V3 Privacy Protocol

Ignored

No

V3 Privacy Password

Ignored

No

V3 Context Name

Ignored

No

V3 Engine ID

Ignored

No

Com mand Line Interfaces (CLI) 111

DeleteNetElementInterface

DeleteNetElementInterface
Overview

The DeleteNetElementInterface CLI allows the user to delete network element

interfaces from IPControl. This CLI allows you to specify a file containing a list of network
element interfaces to delete.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteNetElementInterfaceCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-v] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteNetElementInterface.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-v] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteNetElementInterface.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. See
below for the required file format.

-r <rejects file>

No

The name of the file that rejected (not deleted) records will be placed
in.

-e <error messages>

No

The name of the file that error messages will be reported in.

-v

No

Produces verbose output.

Usage Example

This example deletes Network Elements interfaces listed in the netelementinterfaces.csv file, places
into the netelementinterfaces.reject file any records that could not be deleted, and reports errors to
the deleteerrors.txt file.
$INCHOME/etc/cli/DeleteNetElementInterface.sh u joe p joepwd
f netelementinterfaces.csv r netelementinterfaces.reject e deleteerrors.txt

112 IPControl CLI and API Guide

DeleteNetElementInterface

File Format

By design, the input file format for DeleteNetElementInterface is the same as for
ImportNetElementInterface. This way, one can use the same file to the delete a set of
interfaces and then re-add them without copying data. Only the network element name and
interface name are required.
Col

Field

Accepted Values

Required

Name

The name of a Network Element already defined

to IPControl.

Yes

Interface Name

The name of the interface to delete.

Yes

Status

The status of the interface. This is not used for

delete.

No

Com mand Line Interfaces (CLI) 113

DeleteNetService

DeleteNetService
Overview

The DeleteNetService CLI enables the user to remove individual network services from
the system. This CLI allows you to specify a file containing a list of network services to delete.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.DeleteNetServiceCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteNetService.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteNetService.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.

-r <rejects file>

No

The name of the file that rejected (non-deleted) records will be placed
in.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes network services listed in the netservices.csv file, places into the
netservices.reject file any records that could not be deleted, and reports errors to the deleteerrors.txt
file.
$INCHOME/etc/cli/DeleteNetService.sh u joe p joepwd f netservices.csv
r netservices.reject e deleteerrors.txt

114 IPControl CLI and API Guide

DeleteNetService

File Format

By design, the input file format for DeleteNetService is the same as the format for
ImportNetService and ExportNetService. This way, one can use the same file to
delete a set of network services and then re-add them without copying data. Specify the name
and the type of the network service. If the type is not specified, it defaults to DHCP.
Col

Field

Accepted Values

Required

Name

The name of the Network Service. This can be any

combination of letters and numbers.

Yes

IP Address/FQDN

Ignored

No

Type

The type of Network Service. Accepted value is

dhcp. If this column is left blank, dhcp is
assumed.

No

Product name

Ignored

No

Agent name

Ignored

No

Global Sync

Ignored

No

Collection Method

Ignored

No

User name for

collection

Ignored

No

Password for collection

Ignored

No

Collection port

Ignored

No

Container(s)

Ignored

VendorInfo

Ignored

No

WarningThreshold

Ignored

No

Com mand Line Interfaces (CLI) 115

DeletePrefixPool

DeletePrefixPool
Overview

The DeletePrefixPool CLI allows the user to delete Prefix Pools in the system. This CLI
enables you to specify a file containing a list of prefix pools to delete.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeletePrefixPoolCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeletePrefixPool.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeletePrefixPool.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes the prefix pools listed in the file prefixpools.txt.
$INCHOME/etc/cli/DeletePrefixPool.sh u joe p joepwd f prefixpools.txt

116 IPControl CLI and API Guide

DeletePrefixPool

File Format

The input file format for DeletePrefixPool is the same as for ImportPrefixPool.
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

Start Addr

The Start address of the prefix pool.

Yes

Length

Ignored

No

Prefix Pool Type

Ignored

No

Name

Name of the prefix pool.

Yes

Container

Ignored

No

Delegated Prefix Length

Ignored

No

Longest Prefix Length

Ignored

No

Shortest Prefix Length

Ignored

No

Primary Net Service

Ignored

No

DHCP Option Set

Ignored

No

DHCP Policy Set

Ignored

No

Allow DHCP Client Classes

Ignored

No

Deny DHCP Client Classes

Ignored

No

Com mand Line Interfaces (CLI) 117

DeleteTask

DeleteTask
Overview

The DeleteTask CLI allows the user to delete tasks from the system.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteTaskCLI u <userId> -p <pswd>
[-t <idlist> | r <retain> | -d <date>] [-v] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteTask.sh u <userId> -p <pswd>
[-t <idlist> | r <retain> | -d <date>] [-v] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteTask.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, -r, or
d must be
specified.

One or more task IDs to delete. Multiple tasks are separated by

commas with no spaces. In Windows, enclose a list of tasks in quotes,
for example, -t 123,456.

-r <retain>

One of t, -r, or
d must be
specified.

The number of days of tasks to retain. For example, if r 30 is

specified, tasks older than 30 days will be deleted.

-d <date>

One of t, -r, or
d must be
specified.

Tasks older than this date will be deleted, in the format yyyy/mm/dd.
For example, for a date of 2005/12/31, all tasks prior to that date will
be deleted.

-v

No

Verbose option. The CLI will print out more information about the
request. In particular, it will print how many tasks were deleted.

Usage Example

This example deletes tasks older than 60 days.

$INCHOME/etc/cli/DeleteTask.sh u joe p joepwd r 60 -v

File Format

None. This CLI uses command line arguments only.

118 IPControl CLI and API Guide

DeleteZone

DeleteZone
Overview

The DeleteZone CLI enables the user to remove zones from the system. This CLI allows
you to specify a file containing a list of zones to delete.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.DeleteZoneCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteZone.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteZone.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.

-r <rejects file>

No

The name of the file that rejected (non-deleted) records will be placed
in.

-e <error messages>

No

The name of the file that error messages will be reported in.

-v <verbose>

No

Produces verbose output.

Usage Example

This example deletes zones listed in the zones.csv file, places into the zones.reject file any records
that could not be deleted, and reports errors to the deleteerrors.txt file.
$INCHOME/etc/cli/DeleteZone.sh u joe p joepwd f zones.csv
r zones.reject e deleteerrors.txt

Com mand Line Interfaces (CLI) 119

DeleteZone

File Format

By design, the input file format for DeleteZone is the same as the format for ImportZone.
This way, one can use the same file to delete a set of zones and then re-add them without
copying data.
Col

Field

Accepted Values

Required

Server

The network service name of the DNS Server.

Yes

Zone type

Ignored

No

Domain Name

Domain name already defined to IPControl.

Yes

Domain Type

Domain type name already defined to IPControl.

If not specified, the Default domain type will be
used.

No

Update Zone

Ignored

No

View

The name of the view containing the zone to be

deleted. If not specified, 'Default.' will be used.

No

Filename

Ignored

No

Automatic Generation
of NS/GLUE Records

Ignored

No

MNAME

Ignored

No

Allow Zone Transfers

to DNS Listener

Ignored

No

Masters

Ignored

No

Zone extensions Prior

Ignored

No

Zone extensions After

Ignored

No

Template Zone

Ignored

No

Alias Zone

Ignored

No

Galaxy Name

Ignored

No

Allow Update ACL

Ignored

No

Update Policy

Ignored

No

Dynamic Zone

Ignored

No

120 IPControl CLI and API Guide

DeleteZoneResourceRecord

DeleteZoneResourceRecord
Overview

The DeleteZoneResourceRecord CLI allows the user to delete DNS resource records
for a zone from IPControl.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DeleteZoneResourceRecordCLI u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DeleteZoneResourceRecord.sh u <userId> -p <pswd>
-f <delete filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DeleteZoneResourceRecord.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

Usage Example

This example deletes resource records described in the delresourcerecs.csv file, places into the
delresourcerecs.reject file any records that could not be deleted, and reports errors to the
importerrors.txt file.
$INCHOME/etc/cli/DeleteZoneResourceRecord.sh u joe p joepwd f delresourcerecs.csv
r delresroucerecs.reject e importerrors.txt

Com mand Line Interfaces (CLI) 121

DeleteZoneResourceRecord

File Format
Col

Field

Accepted Values

Required

Server

The network service name of the DNS Server.

Yes

View

The name of the view for this zone. If supplied

the view must exist. If not specified, 'Default' will
be used.

Yes

Zone

The name of the zone, which is the top level

domain name.

Yes

Owner

The OWNER section of the resource record.

Yes

TTL

The Time To Live. If specified, must match the

value in the record to be deleted.

No

Class

The value currently supported is IN. If not

specified, defaults to IN.

No

Resource Record Type

The type of resource record being deleted.

Yes

Data

The text for the DATA area of the resource record.

Yes

122 IPControl CLI and API Guide

ArpDiscoverNetElement Task

Tasks
ArpDiscoverNetElement Task
Overview

The ArpDiscoverNetElement CLI allows the user to create an ARP Discover task on a given
Net Element.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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.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, unless n
specified

IP Address of the Net Element to discover.

-n <Name>

Yes, unless i
specified

Name of the Net Element to discover.

--performnethostadds

No

If set, the task will add new hosts found during discovery.

--updatereclaim

No

If set, the task will update the last discovered counters for
blocks and hosts defined within the network element.

--ignoredups

No

If set, the task will ignore duplicate hostname errors when

adding new hosts.

-v

No

Verbose

Usage Example

This creates a task to perform an ARP discover on a Net Element with IP Address 10.40.23.6,
and to perform net host adds as part of the processing.

Com mand Line Interfaces (CLI) 123

$INCHOME/etc/cli/ArpDiscoveryNetElementCLI.sh u joe p joepwd i 10.40.23.6

--performnethostadds

Return codes

If the task is scheduled successfully, an errorlevel of 0 is set. If v is specified, the task

number is printed to the screen. That task number can then be passed to the TaskStatus
CLI to obtain the status of that task.
If the task is NOT scheduled successfully, the errorlevel returned is a non-zero number,
and an error message is printed to the console.

124 IPControl CLI and API Guide

DhcpConfigurationTask
Overview

The DhcpConfigurationTask CLI allows the user to create a DHCP Configuration task.
DHCP Configuration tasks generate and deploy configuration files for DHCP servers.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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.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, unless n specified

IP Address of the DHCP Server to configure.

-n <Name>

Yes, unless i specified

Name of Network Service (DHCP server) to configure.

-a

No

If set, the task will stop if errors are detected during the
configuration generation.

-f

No

If set, any associated failover servers will also have their

configurations generated and deployed.

-v

No

Verbose

Usage Example

This creates a task to perform a DHCP configuration deployment for the dhcp5 DHCP
server. In addition, if there are any failover servers associated with dhcp5, their
configurations are also deployed. Lastly, if there are any errors, the task will abort.
$INCHOME/etc/cli/DhcpConfigurationTask.sh u joe p joepwd n dhcp5 a -f

Com mand Line Interfaces (CLI) 125

DhcpConfigurationTask

Return codes

If the task is scheduled successfully, an errorlevel of 0 is passed, along with a string

including the task number. That task number can then be passed to the TaskStatus CLI to
obtain the status of that task.
If the task is NOT scheduled successfully, the errorlevel returned is a negative number,
and an error message is printed to the console.

126 IPControl CLI and API Guide

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.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.DHCPUtilizationCLI u <userId> -p <pswd>
[-n <network service name> | -i <network service ip address>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DHCPUtilization.sh u <userId> -p <pswd>
[-n <network service name> | -i <network service ip address>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DHCPUtilization.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. Required only if Network Element Name not
specified.

-n <Name>

Yes

Name of Network Service (DHCP server) to discover. Required

only if IP Address or FQDN not specified.

-v

No

Produces verbose output, providing the task id.

Usage Example

This example creates a task on the queue to perform a DHCP utilization collection for the
dhcp5 DHCP server.
$INCHOME/etc/cli/DHCPUtilization.sh u joe p joepwd n dhcp5

Return codes

If the task is scheduled successfully, an errorlevel of 0 is passed, along with a string

including the task number. That task number can then be passed to the TaskStatus CLI to
obtain the status of that task.
If the task is NOT scheduled successfully, the errorlevel returned will be a negative
number, and an error message will be printed to the console.

Com mand Line Interfaces (CLI) 127

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
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.DiscoverNetElementCLI u <userId> -p <pswd>
[-n <network element name> | -i <netelement address>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DiscoverNetElement.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. Required only if Network Element Name not
specified.

-n <Name>

Yes

Name of Network Element (device) to discover. Required only

if IP Address or FQDN not specified.

Usage Examples

This example creates a task on the queue to perform a Discover for the device found at the IP
address 10.10.23.4.
$INCHOME/etc/cli/DiscoverNetElement.sh u joe p joepwd i 10.10.23.4

This example creates a task to perform a Discover for the device with the DNS name
corerouter1.mycompany.com.
$INCHOME/etc/cli/DiscoverNetElement.sh u joe p joepwd i corerouter1.mycompany.com

This example creates a task to perform a Discover for the IPControl network element named
router3.
$INCHOME/etc/cli/DiscoverNetElement.sh u joe p joepwd n router3

128 IPControl CLI and API Guide

DiscoverNetElement

Return codes

If the task is scheduled successfully, an errorlevel of 0 is passed, along with a string

including the task number. That task number can then be passed to the TaskStatus CLI to
obtain the status of that task.
If the task is NOT scheduled successfully, the errorlevel returned will be a negative
number, and an error message will be printed to the console.

Com mand Line Interfaces (CLI) 129

DnsConfigurationTask

DnsConfigurationTask
Overview

The DnsConfigurationTask CLI allows the user to create a DNS Configuration task.
DNS Configuration tasks generate and deploy configuration and zone files for DNS servers.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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.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, unless n
specified

IP Address of the DNS Server to configure.

-n <Name>

Yes, unless i
specified

Name of DNS server to configure.

-a

No

By default, the task will abort if errors are detected during the
configuration generation. Set this option to continue with the
deployment in spite of errors.

-c

No

Changes only. With d, creates a task to send only changed resource

records. Without d, creates a task to push only changed zones.

-d

No

Use Dynamic DNS instead of recreating configuration and zone files.

With c, only changed resource records are sent. Without c, all
resource records are sent.

-g

No

By default, the generated configuration file is checked for errors.

Specify this option to suppress that check.

-k

No

By default, the generated zone files are checked for errors. Specify this
option to suppress that check.

-s

No

Sends only resource records created in IP Control. Dynamic DNS (-d)

must be specified. Use this option to periodically refresh the records in
Microsoft AD DNS to prevent their scavenging, while not interfering
with the intended scavenging of dynamic records.

-v

No

Verbose

130 IPControl CLI and API Guide

DnsConfigurationTask

Param eter

Required

Description

-w <View>

No

View name. This might be needed when multiple views are in use and
a single zone push is desired. If not specified, the value Default is
used.

-z <Zone>

No, unless w
specified

Zone name. Set this option to generate a configuration for this

selected zone, instead of the whole server.

Usage Examples

This example creates a task to push any changed zone files to the server dns1. The
configuration file is pushed if needed. Also, by default, the configuration file and zone files
are checked for errors.
$INCHOME/etc/cli/DnsConfigurationTask.sh u joe p joepwd n dns1

This example creates a task to push any changed zone files to the server dns1. The
configuration file is pushed if needed.
$INCHOME/etc/cli/DnsConfigurationTask.sh u joe p joepwd c n dns1

This example creates a task to push the zone file for zone acme.com to the server dns1.
Also, by default, the zone file is checked for errors.
$INCHOME/etc/cli/DnsConfigurationTask.sh u joe p joepwd n dns1 z acme.com

This example creates a task to send all of resource records for the zone acme.com via
Dynamic DNS to the server dns1.
$INCHOME/etc/cli/DnsConfigurationTask.sh u joe p joepwd d n dns1 z acme.com

This example creates a task to send the changed resource records for the zone acme.com via
Dynamic DNS to the server dns1.
$INCHOME/etc/cli/DnsConfigurationTask.sh u joe p joepwd c d n dns1 z acme.com

Return codes

If the task is scheduled successfully, an errorlevel of 0 is passed, along with a string

including the task number. That task number can then be passed to the TaskStatus CLI to
obtain the status of that task.
If the task is NOT scheduled successfully, the errorlevel returned is a negative number,
and an error message is ModifyBlockCLI printed to the console.

Com mand Line Interfaces (CLI) 131

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.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.GlobalRollupCLI u <userId> -p <pswd>
-t <#><period> [-?]

Via command script (Unix)

$INCHOME/etc/cli/GlobalRollup.sh u <userId> -p <pswd>
-t <#><period> [-?]

Via command script (Windows)

%INCHOME%/etc/cli/GlobalRollup.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. <#> indicates the number of periods.

<period> indicates the period type, where acceptable values are D, W,
M, Y (days, weeks, months, years).

Usage Examples

This example creates a task on the queue to perform a Global Rollup, and to use the last 90
days of data when forecasting future growth.
$INCHOME/etc/cli/GlobalRollup.sh u joe p joepwd t 90d

This example creates a task on the queue to perform a Global Rollup, and to use the last 6
months of data when forecasting future growth.
$INCHOME/etc/cli/GlobalRollup.sh u joe p joepwd t 6m

Return codes

If the task is scheduled successfully, an errorlevel of 0 is passed, along with a string

including the task number. That task number can then be passed to the TaskStatus CLI to
obtain the status of that task.
If the task is NOT scheduled successfully, the errorlevel returned will be a negative
number, and an error message will be printed to the console.

132 IPControl CLI and API Guide

GlobalSync

GlobalSync
Overview

The GlobalSync CLI allows the user to issue an immediate Global Synchronization task for
either network services or network elements.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.GlobalSyncCLI u <userId> -p <pswd>
-t <type> [-?]

Via command script (Unix)

$INCHOME/etc/cli/GlobalSync.sh u <userId> -p <pswd>
-t <type> [-?]

Via command script (Windows)

%INCHOME%/etc/cli/GlobalSync.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. Acceptable values are

netelement or netservice.

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.
$INCHOME/etc/cli/GlobalSync.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.
$INCHOME/etc/cli/GlobalSync.sh u joe p joepwd t netservice

Return codes

If the task is scheduled successfully, an errorlevel of 0 is passed, along with a string

including the task number. That task number can then be passed to the TaskStatus CLI to
obtain the status of that task.
If the task is NOT scheduled successfully, the errorlevel returned will be a negative
number, and an error message will be printed to the console.

Com mand Line Interfaces (CLI) 133

TaskStatus

TaskStatus
Overview

The TaskStatus CLI allows the user to query the status of tasks.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.TaskStatusCLI u <userId> -p <pswd>
-t <task number> [-v] [-?]

Via command script (Unix)

$INCHOME/etc/cli/TaskStatus.sh u <userId> -p <pswd>
-t <task number> [-v] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/TaskStatus.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.

-v

No

Verbose output. Detailed information about the task will be displayed.

Usage Example

This example queries task 37 and returns a one-word string indicating the status:
INPROGRESS
$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.0/2003-12-16
10:35:38.0/00:03:00
$INCHOME/etc/cli/TaskStatus.sh u joe p joepwd t 42 -v

Output

By default, TaskStatus returns the status of the queried task as:

NOTSTARTED

QUEUED

INPROGRESS

COMPLETE

134 IPControl CLI and API Guide

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, corresponding to the

following table:
Status

Errorlevel

NOTSTARTED

QUEUED

INPROGRESS

COMPLETE

COMPLETEWITHERRORS

ERROR

Com mand Line Interfaces (CLI) 135

DetachBlock

Updates
DetachBlock
Overview

The DetachBlock CLI enables the user to detach blocks from device containers. This CLI
allows you to specify a file containing a list of blocks to detach.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH task number
com.diamondip.netcontrol.cli.DetachBlockCLI u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [v] [-?]

Via command script (Unix)

$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.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. 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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-v <verbose>

No

Produce verbose output.

Usage Example

This example detaches blocks listed in the blocks.csv file, places into the blocks.reject file any
records that could not be deleted, and report errors to the detacherrors.txt file.
$INCHOME/etc/cli/DetachBlock.sh u joe p joepwd f blocks.csv r blocks.reject
e detacherrors.txt

136 IPControl CLI and API Guide

DetachBlock

File Format

Specify the name of the block, or its address and size, and the container it is to be detached
from.
Col

Field

Accepted Values

Required

Block Name

The name of the block to be detached. This is

typically the CIDR address: Address space/Block
size, e.g. 10.1.2.0/24. However, if the block
name was set manually during allocation, that
value must be used instead.

Yes, unless
block address
and block size
are specified

Block Address

The address space of the block to be detached.

Yes, unless
block name is
specified

Block Size

The size of the block in short-notation (e.g., 24

for a 255.255.255.0 network).

Yes, unless
block name is
specified

Container

The name of the container from which to

detach 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

Com mand Line Interfaces (CLI) 137

JoinBlock

JoinBlock
Overview

The JoinBlock CLI allows the user to join existing, adjacent blocks, forming a larger block.
The blocks must be in the same container, and of the same type. This CLI allows you to
specify a single block on the command line.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.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.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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-b <block name>

Yes

The name of the first block to be joined. This is typically the

CIDR address, e.g. 10.1.2.0/24. However, if the block name was
set manually during allocation, that value must be used instead.

-c <container name>

Must be specified
if the block name
is not unique.

The name of the container holding the block. If this parameter is

supplied, the container is searched for the block to join.
Otherwise, the whole system is searched.

Usage Example

This example joins the block 10.1.2.0/24 to the next adjacent block in the same container.
As mentioned above, this example assumes that there is only one block with this name in the
system.
$INCHOME/etc/cli/JoinBlock.sh u joe p joepwd b 10.1.2.0/24

138 IPControl CLI and API Guide

ModifyAddrpool

ModifyAddrpool
Overview

The ModifyAddrpool CLI alters existing address pools in the system.

Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ModifyAddrpoolCLI u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ModifyAddrpool.sh u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ModifyAddrpool.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. 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/ModifyAddrpool.sh u joe p joepwd -f updateaddrpools.txt
-r updateaddrpools.reject e updateaddrpool.err

Output

If successful, the CLI updates the address pools per the input file and exits.
File Format

The ModifyAddrpool 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
address 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 address pools and also indicates which can
be used to locate a record.

Com mand Line Interfaces (CLI) 139

ModifyAddrpool

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

End Address

endAddr

The IP Address of the last

address in the pool. This
address must be in the same
block as the Start Address. In
addition, the Start and End
addresses must not overlap any
other pools.

No

Address Pool Type

type

One of Dynamic DHCP,

Automatic DHCP, Static,
Reserved, Dynamic NA
DHCPv6, Automatic NA
DHCPv6, Dynamic TA
DHCPv6, Automatic TA
DHCPv6

No

Name

name

Address Pool name. Defaults to

Start Address-End Address

No

Share Name

sharename

The name used to link address

pools together.

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.

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.

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 address pools.
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 address
pools. Separate the list entries
with a vertical bar |.

No

Deprecated

140 IPControl CLI and API Guide

ModifyAddrpool

Each input line specifies the locator attribute-value pairs, followed by a colon, followed by the
modification attribute-value pairs. For example, to change the ending address for the pool
starting at address 10.1.2.3:
startAddr=10.1.2.3:endAddr=10.1.2.15

Separate multiple attribute-value pairs with commas. For example, to change both the end
address and the DHCP Server for the address pool starting at 10.1.2.3:
startAddr=10.1.2.3:endAddr=10.1.2.15,primaryNetService=newserver

This applies to the locator fields as well. For example, to change the end address for the pool
starting at 192.168.0.2 in Container Private:
startAddr=192.168.0.2,container=Private:endAddr=192.168.0.31

Some values are lists. Separate the list elements with a vertical bar. For example, to allow t wo
Client Classes for the pool starting at 10.1.2.3:
startAddr=10.1.2.3:allowClientClasses=allow1|allow2

For fields that are lists, existing values, if any, may be replaced or merged. For example, for
the pool starting at 10.1.2.3, to replace allow1 and allow2 with allow3 in the example
above write:
startAddr=10.1.2.3:allowClientClasses=allow3

To update only some of the values in a list use the notation += when specifying the attribute
and value. In the example above to allow a client class allow4 while keeping the allow3,
write:
startAddr=10.1.2.3: allowClientClasses+=allow4

To remove a value, specify the attribute but leave the value empty. For example, to remove
the allowClientClasses from the above pool:
startAddr=10.1.2.3:allowClientClasses=

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:
startAddr=2001::1:0#primaryNetService=newserver

Com mand Line Interfaces (CLI) 141

ModifyBlock

ModifyBlock
Overview

The ModifyBlock CLI alters existing blocks in the system.

Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ModifyBlockCLI u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ModifyBlock.sh u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ModifyBlock.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. 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/ModifyBlock.sh u joe p joepwd -f updateblocks.txt
-r updateblocks.reject e updateblock.err

Output

If successful, the CLI updates the blocks per the input file and exits.
File Format

The ModifyBlock 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 block
to be changed, and a second set specifies what fields to change and their new values.
The following table lists the available attributes for blocks, and also indicates which can be
used to locate a record.
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

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, for example,

24

Yes / No

Block Status

blockStatus

Block Status, one of Free, Reserved,

Aggregate, Deployed,
FullyAssigned

Yes / Yes

Block Type

blocktype

A valid block type name. (Validation

associated with modifying a blocks block
type will be applied.)

No / Yes

Container

container

An array of container names

Yes/ Yes

ignoreErrors

ignoreErrors

True/false. If true, any errors occurring

during a block reparent related to
inconsistent user defined field templates
will be ignored. For instance, moving a
block with a container/blocktype
information template to a container
which does not have the same template
will normally cause an error. To ignore
the error (and lose the user defined fields
associated with the old container) set the
flag to ignoreErrors=true.

No/No

Interface Name

interfaceName

The target interface name during a

reparent of a Device Container.

Yes / Yes

Description

description

The block description. Use \n to

separate lines.

No/ Yes
No/ Yes

Exclude from
Discovery

excludeFromDiscovery

Organization Id

organizationId

Flag indicating if this subnet should be

included in Host Discovery tasks.
Accepted values are true or false.
Valid only for Deployed blocks.
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.

No/ Yes

SWIP Name

swipname

SWIP Name for ARIN blocks

No/ Yes

User Defined Fields

userDefinedFields

Array of user defined fields. Each

element in the array has the format
name=value where name is the UDF
tag name.

No /Yes

Subnet

subnet

Block subnet policies. See below for

syntax. Valid only for Deployed blocks.

No/Yes

Primary Subnet
Flag

primarySubnet

Flag indicating if this subnet is primary.

Accepted values are true or false.
Valid only for Deployed blocks in
device containers.

No/Yes

Allocation
Template Name

allocationTemplate
Name

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.

No/Yes

No/ Yes

Com mand Line Interfaces (CLI) 143

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. See below for syntax.

No/Yes

Each input line specifies the locator attribute-value pairs, followed by a : or # , followed by
the modification attribute-value pairs. For example, to change the description for the block
starting at address 10.1.2.3:
blockAddr=10.1.2.3:description=updated description

Separate multiple attribute-value pairs with commas. For example, to change both the
description and the Organization Id for the block starting at 10.1.2.3:
blockAddr=10.1.2.3:description=updated description, rir=nationalISP

This applies to the locator fields as well. For example, to change the block status for a block:
blockAddr=10.1.2.3:blockStatus=Reserved

Some values are lists. Separate the list elements with a vertical bar. For example, to modify
two user defined fields for the block at 10.1.2.3:
blockAddr =10.1.2.3:userDefinedFields=state=PA|city=Exton

For values that are lists, existing values, if any, may be replaced or merged. For example, for
the block at 10.1.2.3 to replace theentire contents of the existing userDefinedFields write:
blockAddr =10.1.2.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. In the example above to update the city as Devon without changing or removing
the state value, write:
blockAddr =10.1.2.3:userDefinedFields+=city=Devon

To remove a value, specify the attribute but leave the value empty. For example, to remove
the description from the above block:
blockAddr =10.1.2.3: description =

V6 Addresses

To modify an IPV6 block, # must be used as the separator between the locator pairs and the
modification pairs, since : is part of the address:
blockAddr=3FFE:0000:0000:0010::#description="updated V6 description"

Updating Interface Addresses

To modify a blocks interface address(es), use ImportChildBlock with the overwrite option.
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. In the case of reparenting blocks
contained in device containers, a target interface name must also be provided.

144 IPControl CLI and API Guide

ModifyBlock

For example, to reparent the block starting at 192.168.192.0 to the new container
MovedTo:
blockAddr=192.168.192.0:container=MovedTo

To reparent the block starting at 192.168.196.134 from a device container to the new
device container Router1 on interface routerInterface1:
blockAddr=192.168.196.134:container=Router1,interfaceName=routerInterface1

Note: The Modify Block will either reparent, when a new container name different than
current parent container has been specified, or modify the block without a reparent. Both
cannot be performed during the same modify block invocation.
Modifying Block Subnet Policies

Use the subnet field to specify changes to block subnet policies. Subnet uses a nested data
structure syntax. The attributes of subnet policies are surrounded by braces.
For example, to update the policies for a block starting at 192.168.196.134 (line wrapped
for readability):
blockAddr=192.168.192.0: description=modifying policies,subnet={DHCPOptionsSet=Global
Option Set,DHCPPolicySet=Standard ISC DHCP 3.0 Policy
Set,DNSServers=ServerABC,defaultGateway=192.80.0.1,failoverDHCPServer=DHCPFailoverServer,fo
rwardDomains=test.com|example.com,forwardDomainTypes=Default|Internal,primaryDHCPServer=DHC
PServer,false,primaryWINSServer=192.80.0.2,reverseDomains=10.in-addr.arpa.|10.inaddr.arpa.,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.

No

DHCP Policy Set

DHCPPolicySet

The name of a DHCP Policy

Set defined within IPControl
that should apply to this subnet.

No

DNS Servers

DNSServers

The list of default DNS Servers

for this subnet. This list is
supplied to DHCP clients on
this subnet. The server name or
IP Address is valid. For multiple
servers, separate the server
names with a vertical bar (|).

No

Default Gateway

defaultGateway

The default gateway address for

this subnet. This address is
supplied to DHCP clients on
this subnet.

No

Failover DHCP Server

failoverDHCPServer

The name or IP Address of the

failover DHCP Server for this
address space.

No

Com mand Line Interfaces (CLI) 145

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,
separated by a vertical bar (|).
Not required when using the
default domain type.

No

Forward Domain
Names

forwardDomains

The list of DNS forward

domains for this address space,
separated by a vertical bar (|).
Use forwardDomainTypes to
specify the corresponding
domain types.

No

Primary DHCP Server

primaryDHCPServer

The name or IP Address of the

primary DHCP server for this
address space.

No

Cascade Primary DHCP

Server

cascadePrimaryDHCPS
erver

If address pool or individual IP

address objects within the
subnet reference a specific
DHCP server, this attribute can
be used to allow the
primaryDHCPServer attribute
value to cascade to these
address pool and IP address
objects. Note that address pool
and IP address objects that are
configured with Same as
Subnet for the primary DHCP
server will be unaffected.

No

Primary WINS Server

primaryWINSServer

The IP Address of the primary

WINS server for this subnet.
Used to provide this
information to DHCP for
Dynamic Address types.
Multiple WINS servers may be
specified, separated by commas.

No

Reverse Domain Types

reverseDomainTypes

The list of reverse domain types

corresponding with the list in
the reverseDomains field,
separated by a vertical bar (|).
Not required when using the
default domain type.

No

Reverse Domain Names

reverseDomains

The list of DNS reverse

domains for this address space,
separated by a vertical bar (|).
Use reverseDomainTypes to
specify the corresponding
domain types.

No

146 IPControl CLI and API Guide

ModifyBlock

Applying an Allocation Template

Use the addrDetails field to optionally specify attributes of any address allocations within
the allocation template specified by allocationTemplateName. You can apply a template
and specify address details when changing a blocks status to Deployed, or when modifying a
block that is already of status Deployed. The addrDetails uses a nested data structure
syntax, so its attributes are surrounded by braces.
For example (line wrapped for readability):
blockAddr=192.168.192.0: blockStatus=Deployed, description=applying allocation template,
allocationTemplateName=Standard DHCP,
addrDetails={startingOffset=3,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. This must
match the specification in the
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.

Yes

Network Service Name

netserviceName

The name of the network

service for this address
allocation.

No

Com mand Line Interfaces (CLI) 147

ModifyContainer

ModifyContainer
Overview

The ModifyContainer CLI alters existing containers in the system.

Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ModifyContainerCLI u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ModifyContainer.sh u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ModifyContainer.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.

-v

No

Produces verbose output.

Usage Example
$INCHOME/etc/cli/ModifyContainer.sh u joe p joepwd -f updatecontainers.txt
-r updatecontainers.reject e updatecontainers.err

Output

If successful, the CLI updates the containers per the input file and exits.
File Format

The ModifyContainer CLI uses attribute-value pairs to specify the records and fields to be
changed. 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.
If an attribute is not included in the modifier set, then its value is not changed.
The following table lists the available attributes for containers and also indicates which can be
used to locate a record.

148 IPControl CLI and API Guide

ModifyContainer

Field

Attribute Nam e

Accepted Values

Locator Field

Container Name

containerName

The name of the container.

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.
If using the long format, the
name must be the complete
path beginning at the top of
the container tree.

Yes

Container Description

description

A brief description of the

container. Use \n to
separate lines.

No

Parent Container

parentName

The name of the parent

container for this container.
Names can be in either short
or long format. Modification
indicates the container should
be moved to a different parent
container.

No

Information Template

informationTemplate

The name of a pre-existing

information template to be
associated with this container.

No

Allowed Block Types

allowedBlockTypes

A list of the valid block types

for this container, separated by
|. To specify information
templates for block types, use
the blockTypeInfoTemplates
field.

No

Block Type
Information Templates

blockTypeInfo
Templates

A list of the information

templates to be used for block
types, separated by |. Specify
the templates in the same
order as the block types in the
allowedBlockTypes field. If no
template is to be associated
with a particular block type,
leave it blank, but include the
separator. For example:
blockTypeInfoTemplates=
|template2
In this example, the first block
type listed in
allowedBlockTypes does not
use an information template.

No

Allowed Root Block

Types

allowedRootBlock
Types

A list of the block types

enabled for root block
creation, separated by |.

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, separated by |.

No

Com mand Line Interfaces (CLI) 149

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 |.

No

Allowed Device Types

allowedDeviceTypes

A list of the valid device types

for this container, separated by
|. To specify information
templates for devices, use the
deviceInfoTemplates field.

No

Device Information
Templates

deviceInfoTemplates

A list of the information

templates to be used for
devices, separated by |.
Specify the templates in the
same order as the device types
in the allowedDeviceTypes
field. If no template is to be
associated with a particular
device type, leave it blank, but
include the separator. For
example:
deviceInfoTemplates=
|template2
In this example, the first block
type listed in
allowedBlockTypes does not
use an information template.

No

User Defined Fields

userDefinedFields

List of name=value
parameters, separated by |. If
the UDF type is Checkbox,
the valid values are on and off.
If the UDF type is Textarea,
use \n to separate lines.

No

Ignore disallowing a
block type in use

ignoreBlocktypeInUse

Set this to true when

disallowing a block type in use
by the container, indicated by
the list in the
allowedBlockTypes field.

No

Maintain History
Records

maintainHistoryRecs

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.
Accepted values are true or
false. If not specified,
defaults to false.

No

150 IPControl CLI and API Guide

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, and
when the modify operation
involves moving a container.
In this situation, Subnet,
Address Pool, 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 containers
nearest anscestor. In order to
update these objects
associated DHCP servers as
part of the container move
operation, specify the name of
a DHCP server which is
valid for the target
container.

No

This will update only dynamic

V4 objects and must be a V4
capable DHCP server.
Replace V6 DHCP
Servers

replaceDhcpServerV6

This is similar to the above

replaceDHCPServer field,
but will update any dynamic
V6 objects and must be a V6
capable DHCP server.

No

Apply Replace DHCP

to Multiparented
Device Containers

applyDhcpToMultipar
entDevContainer

This attribute is used only in

conjunction with the
replaceDhcpServer attribute,
when replacing DHCP servers
in objects during a container
move operation. This flag
indicates if those changes
should affect objects attached
to multiparented device
containers, which may have
differing DHCP server
associations along each
container anscestory. Note:
Multiparented device
containers cannot be moved
using CLIs.This attribute
applies when moving a logical
container with a mulitparented
device container along the
logical container ancestory.

No

Com mand Line Interfaces (CLI) 151

ModifyContainer

Each input line specifies the locator attribute-value pair, followed by a colon, followed by the
modification attribute-value pairs. For example, to change the description for the container
East:
containerName=East:description=new description

Separate multiple attribute-value pairs with commas. For example, to change both the
description and the information template for the container East:
containerName=East:description=new description,informationTemplate=templateName

For fields that are lists, separate the list elements with a vertical bar. For example, 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, to set user
defined fields for container East:
containerName=East:userDefinedFields=udf1=value1|udf2=value2

For fields that are lists, existing values, if any, may be replaced or merged. For example, for
container East, to replace the entire contents of the existing user defined fields, 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. In the example above, to update the city as Devon without changing or removing
the state value, write:
containerName=East:userDefinedFields+=city=Devon

To remove a value, specify the attribute but leave the value empty. For example, to remove
the description for container East:
containerName=East:description=

To modify information templates for block and device types, specify the list of templates in
the same order as the list of block or device types. For example:
containerName=East:allowedBlockTypes=Any|blocktype1|blocktype2, blockTypeInfoTemplates=|newT
emplate|newTemplate,allowedDeviceTypes=Printer|Router|Switch,deviceInfoTemplates=xTemplate|
xtemplate|newTemplate

In the above example, block type Any has no template, while blocktype1 and
blocktype2 use newTemplate. Device types Printer and Router use xTemplate,
and Switch uses newTemplate.

152 IPControl CLI and API Guide

ModifyDevice

ModifyDevice
Overview

The ModifyDevice CLI alters existing devices in the system.

Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.netcontrol.cli.ModifyDeviceCLI u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ModifyDevice.sh u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ModifyDevice.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/ModifyDevice.sh u joe p joepwd -f updatedevices.txt
-r updatedevices.reject e updatedevices.err

Output

If successful, the CLI updates the devices per the input file and exits.
File Format

The ModifyDevice 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
device to be changed and a second set that specifies what attributes to modify.
If an attribute is not included in the modifier set, then its value is not changed.
The following table lists the available attributes for devices and also indicates which can be
used to locate a record.

Com mand Line Interfaces (CLI) 153

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.

Yes

Address Type

addressType

The address type of this device.

Accepted values are: Static,
Dynamic DHCP, Automatic
DHCP, Manual DHCP, and
Reserved.

No

Container

container

The Container that holds the

block for the IP Address.

Yes, if IP
Address in
overlapping
space.

Description

description

Text Description of the device.

Use \n to separate lines.

No

Device Type

deviceType

The device type of the device.

Should be one of the values
defined in the system. Defaults
to Unspecified

No

Domain Name

domainName

The name of the domain for

this device.

No

Domain Type

domainType

The domain type of the domain.

Defaults to Default

No

Duplicate Warning

dupWarning

Set this to true if duplicate

warnings should be ignored.

No

Host Name

hostname

The device Host name.

Yes

Hardware Type

hwType

Ethernet or Token Ring

No

Resource Record Flag

resourceRecordFlag

Accepted values are true or

false. If not specified, 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.
If the flag is true and there are
no resource records associated
with the device, resource
records will be generated for the
device. Note that the domain
name must be specified if the
block policy has no forward
domains. Also, the reverse
domain must exist in order for
the PTR record to be added.
User Defined Fields

154 IPControl CLI and API Guide

userDefinedFields

List of name=value parameters,

separated by a vertical bar. If the
UDF type is Checkbox, the
valid values are on and off. If
the UDF type is Textarea, use
\n to separate lines.

No

ModifyDevice

Field

Attribute Nam e

Accepted Values

Locator
Field

Aliases

aliases

List of alias names, separated by

a vertical bar. Only used if the
resource record flag is set.

No

Interfaces

interfaces

List of interfaces. See below for

syntax. Use this to modify a
multi-home device.

No

Primary DHCP Server

primaryDhcpServer

The name of the Primary

DHCP server for this device, if
the address type is Dynamic
DHCP, Automatic DHCP, or
Manual DHCP. If utilizing the
IPControl feature of attaching
DHCP servers to Containers,
then the DHCP server must be
valid for the container where
the device resides.

No

Each input line specifies the locator attribute-value pairs, followed by a colon, followed by the
modification attribute-value pairs. For example, to change the hostname for the device at
address 10.1.2.3:
ipAddress=10.1.2.3:hostname=newhostname

Separate multiple attribute-value pairs with commas. For example, to change both the
hostname and the description for the device at 10.1.2.3:
ipAddress=10.1.2.3:hostname=newhostname,description=New Host

This applies to the locator fields as well. For example, to change the hostname for the device
at 192.168.0.2 in Container Private:
ipAddress=192.168.0.2,container=Private:hostname=newhostname

Aliases, user defined fields, and interfaces values are lists. Separate the list elements with a
vertical bar. For example, to set two aliases for the device at 10.1.2.3:
ipAddress=10.1.2.3:aliases=alias1|alias2

User Defined Fields use a nested attribute=value syntax. For example, to set a user
defined field for IP Address 10.1.2.3:
ipAddress=10.1.2.3:userDefinedFields=udf1=value1|udf2=value2

For fields that are lists, existing values, if any, may be replaced or merged. For example, for IP
Address 10.1.2.3, to replace entire contents of the existing user defined fields, write:
ipAddress=10.1.2.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. Please note, the += notation does not apply to Interfaces when modifying multihome devices. In the example above, to update the city as Devon without changing or
removing the state value, write:
ipAddress=10.1.2.3:userDefinedFields+=city=Devon

Com mand Line Interfaces (CLI) 155

ModifyDevice

To remove a value, specify the attribute but leave the value empty. For example, to remove
the description from the above device:
ipAddress=10.1.2.3:description=

Modifying a Multi-Home Device

Working with Multi-Home devices is more complex. To locate a multi-home device, specify
either the devices host name, or any of its IP Addresses or MAC addresses.
To update the IP Addresses or MAC Addresses, do NOT use the ipAddress or MACAddress
primary attributes. Instead, specify them as attributes of the interfaces.
Interfaces use a nested data structure syntax. For example:
To update the interfaces for the device with hostname newhostname and to modify their IP
Address, use colons between the interface attributes (line wrapped for readability):
hostname=newhostname:interfaces={name=Defau lt}|{name=eth0:ipAddress=10.1.2.3}|
{name=eth1:ipAddress=10.1.2.4}

To update the interfaces for the device with hostname newhostname and to add new
interfaces, use commas between the interface attributes (line wrapped for readability):
hostname=newhostname:interfaces={name=Default}{name=eth0,ipAddress=10.1.2.3}|
{name=eth1,ipAddress=10.1.2.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. To do this, use the devices hostname or IP Address as a
locator, and then specify the new interfaces along with their attributes as given in the table
above. It is a must, to include the {name=Default} interface in the syntax, such as:
hostname=newhostname:interfaces={name=Default}|{name=eth0,ipAddress=10.1.2.3}|
{name=eth1,ipAddress=10.1.2.4}

Note: When adding or updating interfaces, all the existing interfaces need to be listed. Any
interfaces not specified will get deleted.
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:
ipAddress= 2001::2#hostname=newhostname,description=New Host

156 IPControl CLI and API Guide

ModifyDeviceResourceRecord

ModifyDeviceResourceRecord
Overview

The ModifyDeviceResourceRecord CLI alters existing device resource records in the

system.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ModifyDeviceResourceRecord u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ModifyDeviceResourceRecord.sh u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ModifyDeviceResourceRecord.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/ModifyDeviceResourceRecord.sh u joe p joepwd
-f updateeviceresourcerecs.txt -r updatedeviceresourcerecs.reject
e updatedeviceresourcerecs.err

Output

If successful, the CLI updates the device resource records per the input file and exits.
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.
The following table lists the available attributes for device resource records and also indicates
which can be used to locate a record.
Com mand Line Interfaces (CLI) 157

ModifyDeviceResourceRecord

Field

Attribute Nam e

Accepted Values

Locator
Field/
Required?

Domain Name

domain

The name of the domain for

this resource record.

Yes/Yes

Domain Type

domainType

The domain type of the domain.

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. Refer to the
appropriate RFC for exact text
that should be entered.

Yes/Yes

Host Name

hostname

The device host name.

Yes/Yes, unless
ipAddress is
specified

IP Address

ipAddress

The IP Address of the Device.

Yes/Yes, unless
hostname is
specified

Container

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. The
container is then used to
uniquely determine the device.

Yes/No

TTL

TTL

The Time to Live

No/No

Class

resourceRecClass

The value currently supported is

IN. If not specified, defaults to
IN.

Yes/No

Resource Record Type

resourceRecType

The type of resource record

being updated.

Yes/Yes

Data

data

The text for the DATA area of

the resource record. Note that
this section is specific to the
type of resource record. Refer to
the appropriate RFC for exact
text that should be entered.

Yes/No, unless
required to
uniquely identify
the record.

Comment

comment

Text to be appended to the

resource record.

No/No

158 IPControl CLI and API Guide

ModifyDeviceResourceRecord

Each input line specifies the locator attribute-value pairs, followed by a colon, followed by the
modification attribute-value pairs. For example, to change the data and TTL for a record:
domain=40.10.inaddr.arpa.,domainType=Default,owner=10.10,hostname=router00001,resourceRecClass=IN,resource
RecType=A:data="newDNS.ins.com",TTL=2400

This applies to the locator fields as well. For example, to change the owner for a record:
domain=40.10.inaddr.arpa.,domainType=Default,owner=10.10,hostname=router00001,resourceRecClass=IN,resource
RecType=A:owner=30.10

To remove a value, specify the attribute but leave the value empty. For example, to remove
the description from the above device:
domain=40.10.inaddr.arpa.,domainType=Default,owner=10.10,hostname=router00001,resourceRecClass=IN,resource
RecType=A:comment=

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,ipAddress=3FFE:0000:0000:0015 ::,res
ourceRecClass=IN,resourceRecType=AAAA#TTL=2400

Note on overlapping space:

If the device is in overlapping space, and the device in both spaces have A records with
identical owners, if the administrators role does not indicate Ignore for "Allow Duplicate
A Record (Owner) Checking", this CLI will fail with Duplicate Resource Record.

Com mand Line Interfaces (CLI) 159

ModifyDhcpServer

ModifyDhcpServer
Overview

The ModifyDhcpServer CLI alters existing DHCP servers in the system.

Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ModifyDhcpServerCLI u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ModifyDhcpServer.sh u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ModifyDhcpServer.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/ModifyDhcpServer.sh u joe p joepwd -f updatedhcp.txt
-r updatedhcp.reject e updatedhcp.err

Output

If successful, the CLI updates DHCP servers per the input file and exits.
File Format

The ModifyDhcpServer 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
DHCP server to be changed and a second set 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 DHCP servers and also indicates which
can be used to locate a record.

160 IPControl CLI and API Guide

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.

Yes

Product

product

The DHCP server product

name defined in IPControl.

No

Agent

agent

The name of an agent defined in

IPControl.

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

Start Script

startScript

Valid file name on host system.

No

Stop Script

stopScript

Valid file name on host system.

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.
Password for collection user.

CLI Command

cliCommand

Valid file name on host system.

No

CLI User Name

cliUserName

Valid user for collection

program.

No

CLI Password

cliPassword

Password for collection

program

No

CLI Arguments

cliArgs

No

Dynamic DNS

ddns

Arguments to pass to collection

command.
True or False

DHCP Option Set

optionSet

Valid Option Set defined in

IPControl

No

DHCP Policy Set

policySet

Valid Policy Set defined in

IPControl.

No

DHCP Client Classes

clientClasses

Valid DHCP Client Classes

defined in IPControl, separated
by a vertical bar (|).

No

DHCP Failover IP
Address

failoverIpAddress

Valid IP Address

No

DHCP Failover Port

failoverPort

1-65535

No

Configuration PreExtension

beginExtension

Text or file name. File names

must be prefixed by file:.

No

Configuration Postextension

endExtension

Test or file name. File names

must be prefixed by file:.

No

V4V6Both

v4v6both

v4, v6 or both

No

No

No

Com mand Line Interfaces (CLI) 161

ModifyDhcpServer

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. For example, to change the Client Classes for the server at
address 10.1.2.3:
ipAddress=10.1.2.3:clientClasses=allow1|allow2|deny3

For fields that are lists separated by vertical bars, existing values, if any, may be replace d or
merged. For example, for the server at address 10.1.2.3, to replace existing client classes
with allow3 in the example above, write:
startAddr=10.1.2.3:allowClientClasses=allow3

To update only some of the values in a list use the notation += when specifying the attribute
and value. In the example above, to allow a client class allow4 while keeping the allow3,
write:
containerName=East: allowClientClasses+=allow4

Separate multiple attribute-value pairs with commas. For example, to change both the option
set and the client classes for the server at 10.1.2.3:
ipAddress=10.1.2.3:optionSet=OptionSet1,clientClasses=allow1|allow2|deny3

The configuration extension fields can directly contain text or can specify a file name. For
example, to use the contents of the file beginext.txt as the extension at the beginning of
the configuration file:
name=dhcp123.com.com:beginExtension=file:beginext.txt

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:
ipAddress=3FFE:0000:0000:0015::#clientClasses=allow1|allow2|deny3

162 IPControl CLI and API Guide

ModifyDomainResourceRecord

ModifyDomainResourceRecord
Overview

The ModifyDomainResourceRecord CLI alters existing domain resource records in the

system.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.ModifyDomainResourceRecord u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/ModifyDomainResourceRecord.sh u <userId> -p <pswd>
-f <update filename> [-r <rejects file>] [-e <error messages>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/ModifyDomainResourceRecord.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/ModifyDomainResourceRecord.sh u joe p joepwd
-f updatedomainresourcerecs.txt -r updatedomainresourcerecs.reject
e updatedomainresourcerecs.err

Output

If successful, the CLI updates the domain resource records per the input file and exits.
File Format

The ModifyDomainResourceRecord 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.
The following table lists the available attributes for domain resource records and also indicates
which can be used to locate a record.
Com mand Line Interfaces (CLI) 163

ModifyDomainResourceRecord

Field

Attribute Nam e

Accepted Values

Locator
Field/Required

Domain Name

domain

The name of the domain for

this resource record.

Yes/Yes

Domain Type

domainType

The domain type of the domain.

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. Refer to the
appropriate RFC for exact text
that should be entered.

Yes/Yes

TTL

TTL

The Time to Live

No/No

Class

resourceRecClass

The value currently supported is

IN. If not specified, defaults to
IN.

Yes/No

Resource Record Type

resourceRecType

The type of resource record

being updated.

Yes/Yes

Data

data

The text for the DATA area of

the resource record. Note that
this section is specific to the
type of resource record. Refer to
the appropriate RFC for exact
text that should be entered.

Yes/No

Comment

comment

Text to be appended to the

resource record.

No/No

Each input line specifies the locator attribute-value pairs, followed by a colon, followed by the
modification attribute-value pairs. For example, to change the data and TTL for a record:
domain=40.10.in-addr.arpa.,domainType=Default,owner=10.10,
resourceRecClass=IN,resourceRecType=A:data="newDNS.ins.com", TTL=2400

This applies to the locator fields as well. For example, to change the owner for a record:
domain=40.10.inaddr.arpa.,domainType=Default,owner=10.10,resourceRecClass=IN,resourceRecType=A:owner=30.10

To remove a value, specify the attribute but leave the value empty. For example, to remove
the description from the above device:
domain=40.10.inaddr.arpa.,domainType=Default,owner=10.10,resourceRecClass=IN,resourceRecType=A:comment=

164 IPControl CLI and API Guide

ModifyDomainResourceRecord

Note on overlapping space:

If there are A records in overlapping space with identical owners, if the administrators 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 elements 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 administrators 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

ModifyPrefixPool

Each input line specifies the locator attribute-value pairs, followed by a pound sign, followed
by the modification attribute-value pairs. For example, 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 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,primaryNetService=newserver

This applies to the locator fields as well. For example, to change the length for the pool
starting at 2001:db8:0:1:: in Container Private:
startAddr=2001:db8:0:1::,container=Private#length=66

Some values are lists. Separate the list elements with a vertical bar. For example, 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, existing values, if any, may be replaced or merged. For example, for
the pool starting at 2001:db8:0:1::, 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. In the example above to allow a client class allow4 while keeping the allow3,
write:
startAddr=2001:db8:0:1::#allowClientClasses+=allow4

To remove a value, specify the attribute but leave the value empty. For example, to remove
the allowClientClasses from the above pool:
startAddr=2001:db8:0:1::#allowClientClasses=

172 IPControl CLI and API Guide

SplitBlock

SplitBlock
Overview

The SplitBlock CLI allows the user to split an existing block into smaller blocks. This CLI
allows you to specify a single block on the command line. Note that splitting a block attached
to multiple containers is not supported via the CLI.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.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.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.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.

-e <error messages>

No

The name of the file that error messages will be reported in.

-b <block name>

Yes

The name of the block to be split. This is typically the CIDR

address, e.g. 10.1.2.0/24. However, if the block name was set
manually during allocation, that value must be used instead.

-c <container name>

Must be specified
if the block name
is not unique.

The name of the container holding the block. If this

parameter is supplied, the container is searched for the block
to join. Otherwise, the whole system is searched.

-t <target start address>

No

The start address of the target block. This is useful for creating
a block using the specified start address and target block size.
If no start address is specified, the start address of the block
being split will be used.

-s <target size>

Yes

The desired CIDR block size after the split. This parameter
works in conjunction with the equalSizes parameter.

-q <equal sizes>

No

Specify true or false. If true, the block is split such that all
resulting blocks have the target size CIDR size. If false, the
block is split such that the fewest number of new blocks is
created, along with two blocks of targetSize. The default is
false.

Com mand Line Interfaces (CLI) 173

SplitBlock

Usage Example

This example splits the block 10.1.2.0/24 into 8 /27 blocks. If e were false, the result
would be one /25, one /26 and two /27 blocks.
$INCHOME/etc/cli/SplitBlock.sh u joe p joepwd b 10.1.2.0/24 s 27 q true

174 IPControl CLI and API Guide

UseNextReservedIPAddress

UseNextReservedIPAddress
Overview

The UseNextReservedIPAddress CLI is used to mark the next reserved IP Address in

the specified block, for the specified device type, to in-use. The block must have a status of
In Use/Deployed. Within this block, there should be a range of addresses with a type of
Reserved and a status of reserved for the given device type. This CLI should not be used
with address pools with a status of reserved. The next lowest or highest IP address within
the range will be assigned a type of Static and a status of in-use. If a hostname is
specified, it will be applied to the device associated with the IP Address. In addition, there is
an option to add resource records for the device.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.UseNextReservedIPAddress u <userId> -p <pswd>
-b <blockaddress> d <devicetype> [-h <hostname>] [-r <rr flag>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/UseNextReservedIPAddress.sh u <userId> -p <pswd>
-b <blockaddress> d <devicetype> [-h <hostname>] [-r <rr flag>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/UseNextReservedIPAddress.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, not in address pools, of the device type specified in the d
parameter.

-d <device type>

Yes

Device type of address to mark in-use.

-h <host name>

No

If specified, will be applied to the device associated with the IP

Address.

-r <resource record
flag>

No.
Defaults to
false.

Specify true or false. When true, resource records will be added

for the device.

Com mand Line Interfaces (CLI) 175

DhcpRelease

Utilities
DhcpRelease
Overview

Please note that the DhcpRelease CLI is applicable only for DHCPv4 environments.
The DhcpRelease CLI is used to force the release of a DHCP lease. 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. This CLI can be used in lieu of performing a release of the lease from the
client itself. Instead, this CLI will create a DHCP Release packet identifying the clients
hardware address and IP address, and send the request to the DHCP server. The DHCP
server will then free the lease as if the release was sent from the actual client. This then makes
the freed IP address available for lease assignment to another client on the subnet.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH
com.diamondip.ipcontrol.cli.DhcpReleaseCLI [s <server>] -m <macaddr> -i <ipaddr>
[-f <filename>] [-?]

Via command script (Unix)

$INCHOME/etc/cli/DhcpRelease.sh [s <server>] -m <macaddr> -i <ipaddr>
[-f <filename>] [-?]

Via command script (Windows)

%INCHOME%/etc/cli/DhcpRelease.cmd [s <server>] -m <macaddr> -i <ipaddr>
[-f <filename>] [-?]

Parameters
Param eter

Required

Description

-s <server>

No

DHCP Server IP Address (default = 127.0.0.1)

-m <macaddr>

Yes

Client MAC address formatted as hexadecimal characters separated

by colons e.g. a1:b2:c3:d4:e5:f6

-i <ipaddr>

Yes

The IP address to be released by the DHCP server. This IP address

should be associated with a lease for the client identified by the
macaddr parameter.

-?

No

Print help

-f <filename>

No

The name of the CSV file which defines leases to be released. See
below for the required file format.

Usage Examples

This example releases the lease for IP address 10.10.10.101 for the client with MAC address
de:ad:be:ef:ca:fe on the DHCP server at IP address 10.10.10.1.

176 IPControl CLI and API Guide

DhcpRelease

$INCHOME/etc/cli/DhcpRelease.sh s 10.10.10.1 m de:ad:be:ef:ca:fe i 10.10.10.101

This example issues a release for each lease identified in the dhcprelease.csv file.
$INCHOME/etc/cli/DhcpRelease.sh f dhcprelease.csv

Output

The output from the CLI indicates the specific parameters used to issue the DHCP Release.
These log entries can be found in the CLI logfile ($INCHOME/etc/cli/log/ns_webservice.log)
when the appropriate logging level is configured:
16:10:02,506 ()[main] INFO DHCPRelease - Building DHCP Release packet
16:10:02,606 ()[main] INFO DHCPRelease - Sending DHCP Release to server=10.10.10.1 for
MAC=de:ad:be:ef:ca:fe and IP=10.10.10.101

If successful, a corresponding entry for the DHCP release appears in the appropriate syslog
output file (/var/log/daemon.log for Sapphire Appliances) on the DHCP server:
Jan 2 16:11:16 sapphire dhcpd: DHCPRELEASE of 10.10.10.101 from de:ad:be:ef:ca:fe (client hostname) via eth0 (found)

File Format
Col

Field

Accepted Values

Required

Server IP Address

The IP Address of the DHCP Server

Yes

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. Only authorized network administrators should
attempt to run this CLI. A lease is a contract between a DHCP server and a DHCP client.
Using this CLI to simulate client behavior is potentially dangerous. For example, releasing an
active lease for a client that is still on the network could lead to duplicate IP address situations.

Therefore, 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 . Due to the different

DHCP client implementations, the results of releasing an active lease are unpredictable. If the
client is actively using the IP address when the lease is released, the client may immediately
loose network connectivity. If the client maintains the lease offline when the lease is released,
then the client may not be able to obtain network connectivity on the subnet for which the
lease was released.
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. Therefore, the CLI cannot verify that the release was
successful. In addition, the packet is sent via UDP, making it impossible to detect if the server
even received the release message.

Com mand Line Interfaces (CLI) 177

DhcpRelease

Network Connectivity

This CLI must be run from a network host which allows DHCP traffic to the DHCP server.
Specifically, the CLI will open a high numbered (1025+), ephemeral, port on the local host
and direct UDP packets to port 67 on the specified DHCP server. Router and firewall rules
must allow such traffic.
Localhost Usage

In many cases, to avoid network connectivity issues noted above, it is convenient to run the
CLI from the same host as the DHCP server and specify a server IP address of 127.0.0.1.
Each IPControl platform has different behavior with respect to running the CLI locally.

Solaris not supported, CLI must be run remotely.

Windows no known issues.

Sapphire/Linux supported only with ISC DHCP v3.x. ISC DHCP v4.x does not
support listening on the loopback address.
Linux kernel versions 2.6.18-2.6.26, inclusive, contain a bug that creates a bad UDP checksum
for packets sent on the localhost. If you are running a Sapphire Appliance or a Linux
distribution with a kernel version in this range, the DhcpRelease CLI will not function from
the localhost. You can verify your kernel version by running uname a in a console window.
Additionally, the server must be configured with the loopback subnet in the dhcpd.conf file. By
default, the appropriate statement is automatically added to the dhcpd.conf file when a DHCP
Configuration task is performed.
subnet 127.0.0.1 netmask 255.255.255.255 {
}

If the servers configuration does not include this statement, modify the DHCP servers
configuration via Topology Network Services Edit DHCP Server. Select the
Extensions tab and insert the above loopback subnet declaration to be appended to the end of
the configuration file. After making these changes, push the new configuration to the DHCP
server via Management Configuration/Deployment DHCP Configuration All Files.
Once the server has been restarted using the modified dhcpd_start script and is configured
with the loopback subnet, then the DhcpRelease CLI can be run from the localhost of the
DHCP server itself.

178 IPControl CLI and API Guide

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.
To configure the date constraint from which all older records will be deleted, specify a date ( c) or number of days from today (-d). NOTE: a date constraint is required to operate the
utility.
To limit the tables to purge, 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, the batch size can be
changed using the b parameter.
Database connection information is automatically derived from the IPControl jdbc.properties
found in the product CLASSPATH.
Usage
Direct
$INCHOME/jre/bin/java cp $CLASSPATH com.diamondip.ipcontrol.cli.purge
[-p] [-v] [-i] [-q] [-b size] [-t table,...] -c YYYY-MM-DD | -d days [-?]

Via command script (Unix)

$INCHOME/etc/purge.sh
[-p] [-v] [-i] [-q] [-b size] [-t table,...] -c YYYY-MM-DD | -d days [-?]

Via command script (Windows)

%INCHOME%/etc/cli/purge.cmd
[-p] [-v] [-i] [-q] [-b size] [-t table,...] -c YYYY-MM-DD | -d days [-?]

Parameters
Param eter

Required

Description

-p

No

Preview mode, writes dry run report to stdout.

-v

No

Verbose mode, writes verbose output to stdout.

-i

No

Interactive mode, prompts user for SQL execution permission.

-q

No

Quiet mode, suspends user prompting and progress reporting.

179

Purge

-b <size>

No

Overwrites default batch size (1000).

-c <YYYY-MM-DD>

Yes, if d not
specified.

Purge date. All records older than this date will be deleted.

-d <days>

Yes, if c not
specified.

Number of days from the current date to keep. All older records will
be deleted.

-t <table,...>

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.
$INCHOME/etc/cli/purge.sh -b 5 -c 2013-05-01 -t addrpoolhistory

-----------------------------------------------IPControl DB Purge CLI - Copyright BT Diamond IP

Version: v0.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.properties
+ JDBC properties file
= C:/ bin/IPControl/jdbc.properties
[
+
+
+
+

JDBC Properties ]
jdbc.driverClassName
jdbc.url
jdbc.username
jdbc.password

=
=
=
=

oracle.jdbc.driver.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 - #JOB# - Execute purge ADDRPOOLHISTORY by LOGDATE
2013-05-15 15:54:56 - + Purge recs older then: 2013-05-01
2013-05-15 15:54:56 - + Batch size: 5
2013-05-15 15:54:56 - + Recs found: 33
2013-05-15 15:54:56 - 33 ADDRPOOLHISTORY records will be deleted in 7 batches.
2013-05-15 15:54:56 - + DELETESQL = DELETE FROM ADDRPOOLHISTORY WHERE LOGDATE <
TO_DATE('2013-05-01', 'YYYY-MM-DD') AND ROWNUM <= 5
2013-05-15 15:54:56 - Batch 1 deleted 5 recs
2013-05-15 15:54:56 - Batch 2 deleted 5 recs
2013-05-15 15:54:56 - Batch 3 deleted 5 recs
2013-05-15 15:54:56 - Batch 4 deleted 5 recs
2013-05-15 15:54:56 - Batch 5 deleted 5 recs
2013-05-15 15:54:56 - Batch 6 deleted 5 recs
2013-05-15 15:54:56 - Batch 7 deleted 3 recs
2013-05-15 15:54:56 - #JOB# - Purge complete, deleted 33 recs, 16ms
2013-05-15 15:54:56
2013-05-15 15:54:56 - #DONE# - Processing completed, 17ms

180 IPControl CLI and API Guide

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. A full execution report
will also be logged to the location specified in
$INCHOME/etc/support/purge_log4j.properties for every run. By default the log will be
found under ${INCX_HOME}/log/purge.log.
Notes

This utility should be used with caution as deleted records can not be restored without a
database backup. For this reason its recommended to first run the purge utility in preview
mode (e.g. $INCHOME/etc/cli/purge.sh -p) to get an idea of the scope of the work that will
be done, followed by interactive mode (e.g. $INCHOME/etc/cli/purge.sh -i) to force a user
to confirm each table aggregate delete operation.

181

Application Program Interfaces (API)

Using the API

IPControl provides its API as a set of Web Services. Invoke the API by implementing web
service clients, using the client technology of your choice.
The interfaces are grouped into Imports, Gets, Tasks, Exports, Updates and Deletes. Each
service is explained in detail, including the WSDL applicable to each interface, in the sections
that follow.
To view the complete WSDL for each of the services, 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), using authentication handlers
that are invoked before the web service request is called. In order to use web services, the
client must pass the IPControl login name and password. IPControl will then validate that this
is a valid combination, and that the administrator is authorized to use web services (via the
Allow Command Line Interface Access checkbox on the Administrator Policies screen).
Below is a sample code fragment of a client using Java and Axis to invoke the
importDevice operation of the Imports web service. Note that the stubs used in the
example are generated by Axis wsdl2Java tool. For more information on Axis and wsdl stubs,
see
http://ws.apache.org/axis/java/user-guide.html

182 IPControl CLI and API Guide

// Axis-generated class
ImportsServiceLocator locator = new ImportsServiceLocator();
// Setup for authorization handlers
ImportsSoapBindingStub stub = (ImportsSoapBindingStub)locator.getImports(url);
stub.setUsername(incadmin);
stub.setPassword(incadmin);
// Set up input parameter structure
WSDevice wsdevice = new WSDevice();
wsdevice.setIpAddress(blockName);
wsdevice.setDeviceType(deviceType);
wsdevice.setHostname(hostName);
wsdevice.setResourceRecordFlag(resourceRecordFlag);
// Use Axis-generated class to call the web service
String address = stub.importDevice(wsdevice);
// Error handling shown in next section
return address;

Below is an example of a client using .NET to invoke the findNetService operation of the
Exports web service:
Public
Dim
Dim
Dim
Dim

Shared Sub findNetService()

myCred As New NetworkCredential("incadmin", "incadmin")
myWS As New localhost.ExportsService()
myNS As localhost.WSNetService()
i As Integer

myWS.Credentials = myCred
myWS.Url = "http://localhost:8081/inc-ws/services/Exports"
Try
myNS = myWS.findNetService("", "", "", "", "", "", "")
For i = 0 To myNS.Length - 1
Console.WriteLine("Name={0} IP={1} Type={2}",
myNS(i).name, myNS(i).ipAddress, myNS(i).type)
Next
Catch myErr As SoapException
dumpError(myErr)
Catch otherErr As Exception
Console.WriteLine(otherErr.ToString)
End Try
End Sub

Application Program Interfaces (API) 183

Error Processing

Error Processing
When the web service finds an error during processing, it uses the fault codes defined in
SOAP 1.1, along with additional information in the detail element, to convey the nature of the
error. Below is a sample of the XML that will be sent to the client.
<soapenv:Envelope
xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:xsi="http://www.w3.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. 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.getMessage();
System.err.println("Exception - " + errMsg);
if (ex instanceof AxisFault) {
// Retrieve Axis Fault detail
AxisFault fault = (AxisFault) ex;
Element[] elements =fault.getFaultDetails();
System.err.println("AxisFault returned:");
System.err.println(" faultcode: " + fault.getFaultCode());
System.err.println(" faultstring: "+fault.getFaultString());
System.err.println(" faultdetail tag: " + elements[0].getTagName());
System.err.println(" faultdetail node value: " +
elements[0].getFirstChild().getNodeValue());
} else {
ex.printStackTrace();
}
}

Other SOAP toolkits (e.g., .NET and Perl) can parse the XML for the details, or ignore those
tags if that level of detail about the exception is not required for the application.
Available Application Program Interface Matrix
Object
Address Pool

Import
X

Aggregate Block

Block

184 IPControl CLI and API Guide

Modify
X

Delete
X

Export

X
X

Available Application Program Interface Matrix

Object
Container
Device

Import
X

Modify
X

Delete
X

Export
X

Device Interface

Device RR

DHCP Server

Domain

Domain RR

Galaxy Domain

NetElement

NetElementInterface

Netservice

PrefixPool

RootBlock

Zone

Zone RR

Next Available IP

JoinBlock
Site (multiple block allocation)

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

GlobalRollup

DiscoverNetElement

DhcpUtilization

GetTask

Split Block

Detach Block

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

AddSite

Imports
Overview

This section explains the web services available for importing information to IPControl. Each
of these services is available as an operation in the Imports web service. 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.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the addSite request and response
messages.
< 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,
for example, 10.0.0.0/24, 10.0.1.0/25.
Request

The complex type WSSite, which is passed as input from the client to the web service, is
described in the next section.
Parameters
WSSite

Below is the portion of Imports.wsdl that describes WSSite, the parameter structure passed
to addSite. The elements are described in the table that follows.
<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

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.

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.
siteBlockDetails

A repeating structure of
parameters used in creating the
blocks from the template. See
below for details.

no

-214

Block details do not

match site template
details

The name of the site template

to be used in creating the site.

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.wsdl that describes WSSiteBlockDetails, included in

WSSite described above. The site block details must be specified in the order matching
the sequence of the Site Template Detail records in the IPControl GUI. The elements are
described in the table that follows.
<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

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. See
below for syntax.

no

The name of a preexisting Allocation

Reason. If Allocation
Reason is not
currently in
IPControl, this field
is skipped.

no

allocationReasonDescription

A description of the
reason for the
allocation. Wrap the
statement in
"quotes" if it
contains any
commas.

no

interfaceName

The target interface

name. This is a
locator field.

yes, for a device

container

SWIP name

yes, 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. Each
element in the array
has the format
"name=value"
where "name is the
UDF tag name.

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

WSAllocationTemplateDetails

Below is the portion of Imports.wsdl that describes WSAllocationTemplateDetails,

included in WSSiteBlockDetails described above. The elements are described in
the table that follows.
<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

-185

Invalid network
service name:
name

Specify true or false.

This must match the
specification in the
Allocation Template.

yes

The name used to

link address pools
together.

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

DetachBlock

DetachBlock
Overview

The DetachBlock API enables the web service client detach blocks from device containers
in IPControl.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the detachBlock request and response
messages.
<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, for example,
10.0.0.128/28.
Request

The complex type WSChildBlock, which is passed as input from the client to the web
service, is described in the next section.
Parameters
WSChildBlock

Below is the portion of Imports.wsdl that describes WSChildBlock, the parameter structure
passed to detachBlock. The elements are described in the table that follows.
<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

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
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, if
blockAddr is
not specified

-36

Block blockName not

found

blockSize

The size of the block in

short-notation (e.g., 24 for a
255.255.255.0 network).

yes, 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.
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

-42

Container required

-5

Container container not

found

-184

Block is only attached

to one container. Use
delete.

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

Im portAddressPool

ImportAddressPool
Overview

The ImportAddressPool API enables the web service client to import or modify
containers in IPControl.
Request and Response Messages

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.

Request

The complex type WSAddrpool, which is passed as input from the client to the web service,
is described in the next section.
Parameters
WSAddrpool

Below is the portion of Imports.wsdl that describes WSAddrpool, the parameter structure
passed to importAddressPool. The elements are described in the table that follows.
<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

Im portAddressPool

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 address pool is created.
If this is set, the address pool with
the matching identifier is updated.

No for
creates,
Yes for
updates.

-117

Addrpool 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 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. This address must be
in the same block as the Start
Address. In addition, the Start
and End addresses must not
overlap any other pools.

Yes for
IPv4
pools.

type

One of Dynamic DHCP,

Automatic DHCP, Manual
DHCP, Static, Reserved.
Dynamic NA DHCPv6,
Automatic NA DHCPv6,
Dynamic TA DHCPv6,
Automatic TA DHCPv6

Yes

name

Address Pool name. 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 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

primaryNet
Service

The name of the DHCP server

that will serve addresses from this
pool

Yes, when
a DHCP
server is
not
defined
for the
subnet.

-94

DHCP Server not found

Deprecated

194 IPControl CLI and API Guide

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. To use this field,
primaryNetService must also be
specified.

No

-94

DHCP Server not found

-96

Failover not valid without a

primary

The name of an Option Set used

with this 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.

-258

Missing Prefix length.

dhcpOptionSet

For IPV4 address pools, the

DHCP option set applies only to
non-CNR DHCP servers.
For IPV6 address pools, the
DHCP option set applies only to
CNR DHCP servers.
dhcpPolicySet

The name of a Policy Set used

with this pool.
For IPV4 address pools, the
DHCP policy set applies only to
non-CNR DHCP servers.

allowClient
Classes

denyClientClas
ses

prefixLength

For IPV6 address pools, the

DHCP policy set applies only to
CNR DHCP servers.
For Dynamic DHCP and
Automatic DHCP type pools:
An array of Client Classes that are
allowed in this address pools.
Each element of the array names a
different Client Class.
For Dynamic DHCP and
Automatic DHCP type pools:
An array of Client Classes that are
NOT allowed in this address
pools. Each array element names
a different Client Class.
CIDR size of an IPv6 pool. This
element is ignored for an IPv4
address pool.

Application Program Interfaces (API) 195

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. By specifying a parent
block, target block, and a container, the service will handle validating and inserting the desired
aggregate block. The service will also adjust the parent block assignments of any would-be
child blocks.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importAggregateBlock request and
response messages.
<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, which is passed as input from the client to the web
service, is described in the next section.
Parameters
WSAggregateBlock

Below is the portion of Imports.wsdl that describes WSAggregateBlock, the parameter

structure passed to importAggregateBlock. The elements are described in the table that
follows.
<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

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. 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

-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.

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.g., 24 for a

255.255.255.0 network).

Yes

-15

Block size invalid: <size>

blockType

The Block Type for the block

If not specified, a block type of
Any is assumed.

No

-13

Invalid block type <type>

blockName

A name for the block.

Defaults to system supplied
name of Address
space/Block size.

No

description

A description of the block.

No

SWIPname

SWIP 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>

-20

Missing interface name

-19

No interface found

-5

Could not find containerID=<id>

Allocation
Reason

The name of a pre-existing

Allocation Reason.

No

Allocation
Reason
Description

A description of the reason for

the allocation. Wrap the
statement in quotes if it
contains any commas.

No

Interface
Name

If this block is being added to

a device container, the name of
the interface to attach the
block to.

Yes, if
block is
being
added to
device
container.
Otherwise
, no.

DEPRECATED. This field

will be ignored.

No

Interface
Address

Application Program Interfaces (API) 197

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.
Accepted values are true or
false. If not specified, defaults
to false.

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. If
not specified, defaults to
Default.

No

-2

Exception retrieving domain type:

<type>

-81

Domain type not found: <type>

A series of name=value pairs,

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.
For example, UDFone=value
one |UDFtwo=value two. If
the UDF type is Checkbox, the
valid values are on or off.

Yes, for
UDFs
defined as
required
fields.

-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.

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.g., 24 for a
255.255.255.0 network).

198 IPControl CLI and API Guide

Yes

Yes

Im portChildBlock

ImportChildBlock
Overview

The ImportChildBlock API enables the web service client to import child blocks into
IPControl. This API is used to define sub-allocations of address space, taken from parent
address space. This space is allocated from the parent, and then marked with the status that is
specified in the request. The name of the block allocated is returned to the client application
in the response.
This API can also be used to attach existing blocks to another container by specifying an
existing blockAddr.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importChildBlock request and
response messages.
<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, for example,
10.0.0.128/28.
Request

The complex types WSChildBlock and WSSubnetPolicy, which are passed as input from
the client to the web service, are described in the next section.
Parameters
WSChildBlock

Below is the portion of Imports.wsdl that describes WSChildBlock, the first parameter
structure passed to importChildBlock. The elements are described in the table that
follows.
<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

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, 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. If Allocation
Reason is not currently in
IPControl, this field is skipped.

no

allocationReason
Description

A description of the reason for

the allocation.

no

allocationTemplate

If this block is being added to a

device container with
blockStatus=Deployed, the
name of the allocation template
to use to create address pools
from the newly created block.

no

blockAddr

The address block to allocate. If

no address block is specified,
space will be auto-allocated. If
the address is specified and
already exists, the block will be
attached to the specified
container.

no

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).

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.

-12

Invalid block address:

blockAddr

yes

-15

Invalid block size:

blockSize

The current status of the block.

Accepted values are: Deployed,
FullyAssigned, Reserved,
Aggregate.

yes

-17

Invalid block status:

blockStatus

The Block Type for the block

If not specified, a block type of
Any is assumed.

no

-13

Invalid block type:

blockType

Im portChildBlock

Elem ent

Description and accepted

values

Required

Return
Code

Faultstring

container

The name of the 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

-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.

createReverseDomains

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

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

interfaceAddress

The specific addresses, or offsets

from the beginning, for the
interface IP address(es). If an IP
address is specified, it should be
in the form xxx.xxx.xxx.xxx. If
an integer is specified, it will be
interpreted as an offset from the
beginning of the block (i.e. an
offset of 2 in a /24 block will
create an interface
xxx.xxx.xxx.2).

no

-18

Invalid interface
address: interfaceAddress

-21

Invalid interface offset:

interfaceAddress

-20
-19

Missing interface name

-24

No interface name
specified, could not
attach to device
container.

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.
An offset of 1 is assumed if
none is specified.
interfaceName

If this block is being added to a

device container, the name of
the interface to attach the block
to.

yes, for
device
containers
only

Invalid interface name:

interfaceName

Application Program Interfaces (API) 201

Im portChildBlock

Elem ent

Description and accepted

values

Required

Return
Code

Faultstring

ipv6

True if this is an IPV6 block. If

not specified, defaults to false.

No

primarySubnet

Flag indicating if this subnet is

primary. Accepted values are
true or false. If not specified,
defaults to false.

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, where the
name is the UDF name and the
value is the desired value, for
example, State=PA.

yes, 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. Accepted values are true
or false. If not specified,
defaults to false.

no

-82

excludeFromDiscovery
must be true or false:

Valid only for Deployed

blocks in device containers.
userDefinedFields

excludeFromDiscovery

value
-13

Invalid Block Type:

flag supported for
Deployed blocks
(Subnets)

WSSubnetPolicy

Below is the portion of Imports.wsdl that describes WSSubnetPolicy, the second parameter
structure passed to importChildBlock. The elements are described in the table that
follows.
<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.

no

-67

DHCP Option set set

not found

202 IPControl CLI and API Guide

Im portChildBlock

Elem ent

Description and accepted values

Required

Return
Code

Faultstring

DHCPPolicySet

The name of a previously defined DHCP

policy set.

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.

no

-93

DNS Server server not

found

defaultGateway

The default gateway that DHCP clients on

this subnet will use. Accepted value is an
IP address.

no

-26

Invalid IP Address:
ipaddress

failover
DHCPServer

The name of the DHCP server that will act

as failover for this subnet. This cannot be
the same as the primary DHCP server.

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. The first forward
domain in the list will be used when there
is a domain name DHCP option.

no

-95

Invalid forward DNS

Domain domain

forwardDomain
Types

The domain types corresponding to the

domains listed in forwardDomains. Only
required for non-default domain types.

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

-26

Invalid IP Address:
ipaddress

reverseDomains

The reverse domain names that will

available to the user when adding an IP
address to the system.

no

-95

Invalid reverse DNS

Domain domain

reverseDomain
Types

The domain types corresponding to the

domains listed in reverseDomains. Only
required for non-default domain types.

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. The administrator does not have rights to add any blocks OR the administrator
does not have rights to add blocks to the specified container.

Application Program Interfaces (API) 203

Im portContainer

ImportContainer
Overview

The ImportContainer API enables the web service client to import containers into
IPControl. These can be logical containers or device containers. It can also be used to modify
existing containers
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importContainer request and
response messages.
<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.

Request

The complex type WSContainer, which is passed as input from the client to the web service,
is described in the next section.
Parameters
WSContainer

Below is the portion of Imports.wsdl that describes WSContainer, the parameter structure
passed to importContainer. The elements are described in the table that follows.
<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

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.

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.

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 all device types
should be allowed, use ALL as the
first element in the array. To specify
that no device types should be
allowed, use NONE.
ALL is the default.

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 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. The order must match the
blocktypes listed in the
allowedBlockTypes parameter, and the
length of this array is the same as that
parameter. If a blocktype does not
have a template associated with it, set
that array element to null or blank.

no

-3

Error occurred while

updating device info
templates for container

-78

Invalid Information
Template: templateName

Application Program Interfaces (API) 205

Im portContainer

Elem ent

Description and accepted values

Required Return
Code

Faultstring

containerName

The name of the container.

yes

-3

Invalid arguments:
container name, 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,

this container name must match
exactly the name of a network element
already in the database or the request
will be rejected.

-132

containerType

Either logical or device.

yes

description

A brief description of the container.

Use \n to separate lines.

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. 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 a
device type does not have a template
associated with it, set that array
element to null or blank.

no

id

The internal ID of this container, as

provided by the getContainerByName
call. If this is set, the container is
updated instead of added.

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, 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, 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,
indicated by the list in the
allowedBlockTypes field.

no

-43

Blocktype in use by
container: container

The name of the information template

to be associated with this container.

no

-1

DB error retrieving
information template

-78

Invalid Information
Template: templateName

206 IPControl CLI and API Guide

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.
The history records are created each
time the Global Utilization Rollup task
is run. Accepted values are true or
false. If not specified, defaults to
false.

no

parentName

The name of the parent container for

this container. 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

replaceDHCPServ
er

This attribute is used only when

utilizing the IPControl feature of
attaching DHCP servers to
Containers, and when the modify
operation involves moving a container.
In this situation, Subnet, Address
Pool, 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
containers nearest anscestor. In order
to update these objects associated
DHCP servers as part of the container
move operation, specify the name of a
DHCP server which is valid for the
target container.

no

Faultstring

-3

Invalid arguments:
container name, parent
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.
replaceDHCPServ
erV6

requireSWIPName
BlockTypes

This is similar to the above

replaceDHCPServer field, but will
update any dynamic V6 objects and
must be a V6 capable DHCP server.

A string array containing a listing of

the block types enabled for Rule 4:
Require SWIP Names on blocks of
type.

no

no

Application Program Interfaces (API) 207

Im portContainer

Elem ent

Description and accepted values

Required Return
Code

userDefinedFields

The user defined fields associated with

this container, as listed in the
container information template
specified in parameter
informationTemplate.
Specify as 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.

yes, 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. (Root container not moveable; the new parent is a descendant of the
container; Move failed. )

-99

access denied

208 IPControl CLI and API Guide

Im portDevice

ImportDevice
Overview

The ImportDevice API enables the web service client to import devices into IPControl.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importDevice request and response
messages.
<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.

Request

The complex type WSDevice, which is passed as input from the client to the web service, is
described in the next section.
Parameters
WSDevice

Below is the portion of Imports.wsdl that describes WSDevice, the parameter structure passed
to importDevice. The elements are described in the table that follows.
<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

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.

Yes, if
hwtype is
specified
or if
address
type is
Manual
DHCP.

-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.

Accepted values are: Static, Dynamic
DHCP, Automatic DHCP, Manual
DHCP and Reserved. For DHCP
V6: Dynamic NA DHCPv6,
Automatic NA DHCPv6, Manual
NA DHCPv6, Dynamic TA
DHCPv6 and Automatic TA
DHCPv6.
Note that if Dynamic, Automatic or
Manual DHCP is specified, there
must be a DHCP server defined in the
subnet policies for this IP Address.

Yes

-73

Invalid address
type: type
Invalid Address
Type for IPv4|
IPv6: type

-260
-261

Devices of type Interface may not be

imported, but they can be modified
using overwrite. However, the
addressType and ipAddress cannot be
updated. Use ImportChildBlock to
modify or delete Interface IP
addresses.
Aliases

A string array containing the alias or

list of aliases for this hostname. When
you specify an alias, a CNAME record
is created. The alias may be fully
qualified (contains a trailing dot), or
not. When fully qualified, everything
that is after the first qualifier is
interpreted as a domain name. When
not fully qualified, the CNAME
record will be created in the same
domain as the device.
To use this element, 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'

Im portDevice

Elem ent

Accepted Values

Required

Return
Code

Faultstring

container

The name of the container that

contains the device.

Yes, if
overlappin
g space is
in use and
the block
name is
ambiguous
.

-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. Use \n

to separate lines.

No

deviceType

The name of a device type configured

in IPControl.

Yes, if
hostname
specifies
use of
naming
policy.

-47, -58

Device type not

found: type

-75

Device type
required when
using naming
policy

Yes, if
resource
Record
Flag is
true and
the block
policy has
no forward
domains.

-60

Domain not
found: domain

-71

Domain required
when adding
resource records

Domain type already defined to

IPControl. If not specified, the
Default domain type will be used.
DHCP Unique Identifier

No

-59

Domain type not

found: view

Yes, for
Address
Type
Manual
NA
DHCPV6
.

-259

DUID required
for Manual NA
DHCPV6

dupWarning

If the administrator policy of the user

indicates Warn for the Allow
Duplicate Hostnames Checking
option, 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 not specified, defaults to
false.

No

-80

Duplicate
hostname for
hostname

hostname

Valid host name or

APPLYNAMINGPOLICY.

Yes

domainName

domainType

duid

Domain name already defined to

IPControl

Application Program Interfaces (API) 211

Im portDevice

Elem ent

Accepted Values

Required

Return
Code

Faultstring

hwType

Specify Ethernet or Token Ring.

When hwtype is specified,
MACAddress must also be specified.
If MACAddress is specified, this will
default to Ethernet.

No

-72

Invalid Hardware
type: type

ipAddress

The IP Addresses of the Device.

To create multi-homed devices, use
the interfaces element.

Yes

-26
-226

To modify devices with multiple IP

Addresses on a single interface use the
interfaces element.

-227

To indicate that IPControl should use

the next available address in an IPV4
block, specify the block address,
followed by /from-start or /fromend, for example:
10.30.0.0/from-start

-228

resourceRecordFlag

Whether or not to add resource

records for this device. If not specified
as true, defaults to false.

No

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.

An array of WSInterface structures.

Each element in the array corresponds
to one interface for a multi-homed
device or to the only interface for a
single-homed device. The fields in the
WSInterface structure are described
below. Their accepted values are the
same as in the WSDevice structure,
unless otherwise noted:

Yes, for
mulithomed
devices

interfaces

- addressType
- container: reserved
- excludeFromDiscovery
- hwType
- id: The internal ID provided by a
GetDeviceBy call. Required for
modify requests.
- ipAddress
- macAddress
- name: Interface Name (Required)
- sequence: Provided by GetDeviceBy
call; not used
- virtual: reserved

212 IPControl CLI and API Guide

Yes, for all

modify
requests.

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.

-260

Cannot change
the ipaddress of
an interface

-261

Cannot change
the address type
to/from
'Interface'

Im portDevice

Elem ent

Accepted Values

Required

id

The internal ID of this device, as

provided by a GetDeviceBy call. If
this is set, the device is updated
instead of added.

Yes, for
modify

excludeFrom
Discovery

Flag indicating if this device should be

included in Host Discovery tasks.
Accepted values are true or false. If
not specified, defaults to false.

No

Return
Code

Faultstring

For multihomed devices, the flag must

be specified for each IP/Interface via
the WSInterface structure.

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

Im portDeviceResourceRecord

ImportDeviceResourceRecord
Overview

The ImportDeviceResourceRecord API enables the web service client to import DNS
resource records for a device into IPControl.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importDeviceResourceRecord

request and response messages.
<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.

Request

The complex type WSDeviceResourceRec, which is passed as input from the client to the
web service, is described in the next section.
Parameters
WSDeviceResourceRec

Below is the portion of Imports.wsdl that describes WSDeviceResourceRec, the parameter

structure passed to importDeviceResourceRecord. The elements are described in the
table that follows.
<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

Im portDeviceResourceRecord

Elem ent

Accepted Values

Required

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. The container is then used to
uniquely determine the device.

No

domainType

Domain type already defined to

IPControl. If not specified, the
Default domain type will be used.

domain

Domain name where resource records

are to be added.

hostname

ipAddress

owner

The device host name.

The IP Address of the Device.

The owner field of the resource record.

Return
Code

Faultstring

No

-108

Domain not found:

domainType/domain

Yes.

-108

Domain not found:

domainType/domain

-135

Domain required

N/A

Not authorized

Yes,
unless IP
Address is
specified.

-121

Hostname not
unique: hostname

-120

No device with
hostname:

Yes,
unless
Host
Name is
specified.

-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.

Defaults to IN.

No

resourceRecord
Type

The Type of the resource Record.

Yes

TTL

The Time To Live for the record.

No

data

The data portion of the resource

record. The format is dependent on
the type specified above.

Yes

comment

Comment text associated with the

resource record.

No

Application Program Interfaces (API) 215

Im portDhcpServer

ImportDhcpServer
Overview

The ImportDhcpServer API enables the web service client to create or DHCP servers in
IPControl.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importNetService request and
response messages.
<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.

Request

The complex type WSDhcpServer, which is passed as input from the client to the web
service, is described in the next section.
Parameters
WSDhcpServer

Below is the portion of Imports.wsdl that describes WSDhcpServer, the parameter structure
passed to importDhcpServer. The elements are described in the table that follows.
<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

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.

Yes

-29

Invalid agent:
agent

beginExtension

The text to be inserted at the start of the

configuration file. Separate lines with the
sequence \r\n, which is hexadecimal
0x0D followed by 0x0A.

No

cliArgs

Arguments for the command executed to

collect statistics. In particular, if the
server is a CNR DHCP agent, this value
should contain the cluster name.

No

cliCommand

Command to collect DHCP statistics.

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

-116

Invalid Client
Class: class

collectBackup
Subnets

Set to TRUE if the collection should also

process backup subnets from the server.
Defaults to false.

No

collectionPassword

The password used by the collection

method (scp or ftp) to log in to the
remote server. Used in conjunction with
the User name for collection.

Yes

collectionPort

The port number the collection method

(scp or ftp) is listening on. If no value is
specified, this will default to 22 if the
collection method is scp, and 21 if the
collection method is ftp.

No

-32

Invalid
collection port:
port

collectionType

The method by which the IPControl

Agent will collect data from the Network
Service. Accepted values are scp or ftp.

Yes

-31

Invalid
collection type:
type

collectionUser

The username used by the collection

method (scp or ftp) to log in to the
remote server.

Yes

configPath

The path to the configuration file of the

DHCP server.

Yes

ddns

Set to TRUE to enable DDNS updates

from this DHCP Server. Defaults to
FALSE.

No

Application Program Interfaces (API) 217

Im portDhcpServer

Elem ent

Accepted Values

Required

Return
Code

Faultstring

defaultThreshold

Default scope utilization warning

threshold. Provide warnings when usage
of a pool assigned to this service is
exceeded. If no value is specified, this will
default to 90.

No

-57

Invalid alert
threshold: value

endExtension

The text to be appended to the

configuration file. Separate lines with
\r\n, which is hexadecimal 0x0D and
0x0A, respectively.

failoverIpAddress

IP Address used by this DHCP Server for

failover communications.

No

failoverPort

Port used by this DHCP Server for

failover communications.

No

globalSync

Whether or not to include this server in

the Global Sync process. Accepted values
are True or False (case insensitive).

No

id

The internal ID of this server, as provided

by the getDhcpServer call. If this is set,
the server is updated instead of added.

No

ipAddress

The IP address or fully-qualified domain

name (FQDN) of the Network Service.
This must be a valid IPv4 or IPv6 IP
address, or a fully-qualified host name.

Yes

-26

Invalid IP
address: address

-112

Duplicate IP
Address

name

The name of the Network Service. This

can be any combination of letters and
numbers.

Yes

-112

Duplicate
name

optionSet

The name of a DHCP option set defined

in the system to be used by this 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.
Not used

product

The type of DHCP server being defined.

Yes

-123

Unknown
DHCP
Product: name

startScript

The full path of the script that starts the

server.

No

stopScript

The full path of the script that stops the

server.

No

218 IPControl CLI and API Guide

Im portDhcpServer

Elem ent

Accepted Values

Required

Return
Code

Faultstring

v4V6Both

v4, v6 or both

Yes

-191

Invalid value
v4V6Both
specified for
V4V6Both.Vali
d values are
'V4', '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. Additional information will appear in the
web service log.

Application Program Interfaces (API) 219

Im portDomain

ImportDomain
Overview

The ImportDomain API enables the web service client to import domains into IPControl.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importDomain request and response
messages.
<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.

Request

The complex type WSDomain, which is passed as input from the client to the web service, is
described in the next section.
Parameters
WSDomain

Below is the portion of Imports.wsdl that describes WSDomain, the parameter structure passed
to importDomain. The elements are described in the table that follows.
<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

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. For example, an email address of
'[email protected]', would be represented as
'root.ins.com'. If not specified a default
contact name will be formed by
prepending 'dnsadmin' to the domain
name as in 'dnsadmin.ins.com.'.
Default time to live. If not specified,
defaults to 86400; ignored if Managed
is False.
Indicates that this domain will be
associated directly with a zone file.
Accepted values are true or false. If not
specified, defaults to true.
Specify the role of this domain. This can
be one of STANDARD,
TEMPLATE, or ALIAS. The
default is STANDARD.
The name of the domain being created.

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. If not specified, the
Default domain type will be used.
Zone expire time. If not specified,
defaults to 604800; ignored if
Managed is False.
The internal ID of this domain, for
future use.

no

The name of the information template

to be associated with this container.
Indicates that this domain is fully
defined in IPControl. Accepted values
are true or false. If not specified,
defaults to true.

no

Zone negative cache time to live. If not

specified, defaults to 86400; ignored if
Managed is False.
Zone refresh interval. If not specified,
defaults to 10800; ignored if Managed
is False.
Zone retry interval. If not specified,
defaults to 3600; ignored if Managed
is False.
Indicates that this domain is a reverse inaddr.arpa domain. Accepted values are
true or false. If not specified, defaults to
false.

no

no
no

no

no
no
no

Application Program Interfaces (API) 221

Im portDomain

Elem ent

serialNumber
templateDomain

userDefinedFields

Description and accepted values

Zone serial number. If not specified,

defaults to 1; ignored if Managed is
False.
Name of template domain.

The user defined fields associated with

this domain, as listed in the domain
information template specified in
parameter infoTemplate.
Specify as a string array containing one
or more name=value pairs, where the
name is the UDF field name/tag and
the value is the desired value, for
example, 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, if
-60
Derivative
is
ALIAS
-135
yes, 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

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, but still appear in a zone file.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importDomainResourceRecord

request and response messages.
<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.

Request

The complex type WSDomainResourceRec, which is passed as input from the client to the
web service, is described in the next section.
Parameters
WSDomainResourceRec

Below is the portion of Imports.wsdl that describes WSDomainResourceRec, the parameter

structure passed to importDomainResourceRecord. The elements are described in the
table that follows.
<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

Im portDomainResourceRecord

Elem ent

Accepted Values

Required

Return
Code

Faultstring

domainType

Domain type already defined to

IPControl. If not specified, the
Default domain type will be
used.

No

-108

Domain not found:

domainType/domain

domain

Domain name where resource

records are to be added.

Yes.

-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.

Yes

resourceRecClass

The Class of the Resource Record.

Defaults to IN.

No

resourceRecord
Type

The Type of the resource Record.

Yes

TTL

The Time To Live for the record.

No

data

The data portion of the resource

record. The format is dependent
on the type specified above.

Yes

comment

Comment text associated with the

resource record.

No

224 IPControl CLI and API Guide

Im portGalaxyDomain

ImportGalaxyDomain
Overview

The ImportGalaxyDomain API enables the web service client to assign domains to
galaxies in IPControl.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importGalaxyDomain request and
response messages.
<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.

Request

The complex type WSGalaxyDomain, which is passed as input from the client to the web
service, is described in the next section.
Parameters
WSGalaxyDomain

Below is the portion of Imports.wsdl that describes WSGalaxyDomain, the parameter structure
passed to importGalaxyDomain. The elements are described in the table that follows.
<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

Im portGalaxyDomain

Elem ent

Accepted Values

Required

Return
Code

Faultstring

domainName

Domain name, already defined in

IPControl, to assign to the specified
galaxy.

Yes.

-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. Either
remove the server from
the GalaxyProfile or
remove the Zone from
the Server.

-157

Domain view
combination already
exists in this galaxy

domainType

The name of the domain type to

which the domain belongs. If not
specified, the Default domain type
will be used.

No

-81

Domain type not found:

domainType

galaxyName

Name of the galaxy to which to

assign this domain.

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.

226 IPControl CLI and API Guide

No

Im portNetElement

ImportNetElement
Overview

The ImportNetElement API enables the web service client to import network elements
into IPControl.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importNetElement request and
response messages.
<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, for
example, Saved netelement: name.
Request

The string array that is passed as input from the client to the web service is described in the
next section.
Parameters
String Array

The elements of the string array are described below. Note that the returnCode tag is not
used for this call. When an error occurs, the faultcode will be Server.userException,
with the faultstrings shown below.
Elem ent

Description

Accepted Values

Required

Name

The name of the Network

Element. This can be any
combination of letters and
numbers.

Yes

IP Address

The IP address or fullyqualified domain name

(FQDN) of the Network
Element. This must be a valid
IPv4 or IPv6 IP address, or a
full-qualified host name.

Yes

Vendor

The vendor of the Network

Element. Vendor must be
predefined in IPControl. If not
specified, defaults to
Unknown.

Yes when
Model is
specified.

Return
Code

Faultstring

Duplicate name
for Netelement:
name

no models found
for given
description:
description
deviceName: name,
vendorName:

Application Program Interfaces (API) 227

Im portNetElement

Elem ent

Description

Accepted Values

Required

Return
Code

Faultstring

Model

The model name of the

Network Element. Model must
be predefined in IPControl. If
not specified, defaults to
Unknown.

Yes when
Vendor is
specified

same as above

Type

The type of Network Element.

Accepted values are cmts,
router, switch or vpn.

Yes

same as above

Global Sync

Whether or not to include this

Network Element in the
Global Sync process. Accepted
values are True or False (case
insensitive).

Yes

Agent Name

The exact name of the

IPControl Agent that is
responsible for contacting this
Network Service.

Yes

Telnet User

A user name used to telnet to

this device.

No

Telnet
password

A password used by the telnet

user to telnet to this device.

No

Enable
password

Password used to enter

enabled or privileged
mode on the device.

No

10

Read
community
string

The community string used by

SNMP to read details from this
network element.

No

11

Interface List

Separated by vertical bars

(|).

No

12

V3 Username

Required if using SNMP V3.

No

SNMP V3
Username required

13

V3
Authentication
Protocol

Either MD5 or SHA1. Leave

blank or set to NONE if no
authentication.

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. Leave blank or set to
NONE if no privacy.

No

Unknown privacy
protocol: protocol

vendor

Privacy not
allowed without
authentication

16

V3 Privacy
Password

Required if field P is set to

DES.

No

17

V3 Context
Name

SNMP V3 Context name, if

needed.

No

18

V3 Engine ID

SNMP V3 Engine ID, if

needed.

No

228 IPControl CLI and API Guide

Privacy Password
required

Im portNetElementInterface

ImportNetElementInterface
Overview

The ImportNetElementInterface API enables the web service client to import

Network Element Interfaces into IPControl.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importNetElementInterface

request and response messages.
<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.

Request

The complex type WSNetElementInterface, which is passed as input from the client to
the web service, is described in the next section.
Parameters
WSNetElementInterface

Below is the portion of Imports.wsdl that describes WSNetElementInterface, the

parameter structure passed to importNetElementInterface. The elements are described
in the table that follows.
<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. If this is not set,
a new interface is created. If this is set,
the interface with the matching identifier
is updated.

No

Return
Code

Faultstring

Application Program Interfaces (API) 229

Im portNetElementInterface

Elem ent

Accepted Values

Required

Return
Code

Faultstring

interfaceName

The name of the interface being added or

modified.

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.

The status of the interface. This can be

one of Disabled, Enabled, or
Deployed. The default on an import is
Enabled.

Yes

No

Other returnCodes and faultstrings

Return Code

Faultstring

-2

Exception occurred trying to read the network element.

230 IPControl CLI and API Guide

Im portNetService

ImportNetService
Overview

The ImportNetService API enables the web service client to import DHCP network
services into IPControl.
Note: This API has been deprecated as of IPControl 6.0. Use the ImportDhcpServer API
instead. ImportNetService support will be removed in a future release.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importNetService request and
response messages.
<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

The complex type WSNetService, which is passed as input from the client to the web
service, is described in the next section.
Parameters
WSNetService

Below is the portion of Imports.wsdl that describes WSNetService, the parameter structure
passed to importNetService. The elements are described in the table that follows.
<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

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.

Yes

-29

Invalid
network service
agent: agent

collectionMethod

The method by which the IPControl

Agent will collect data from the Network
Service. Accepted values are scp or ftp.

No

-31

Invalid
network service
collection
method: method

collectionPort

The port number the collection method

(scp or ftp) is listening on. If no value is
specified, this will default to 22 if the
collection method is scp, and 21 if the
collection method is ftp.

No

-32

Invalid
network service
collection port:
port

container

No longer used.

globalSync

Whether or not to include this Network

Service in the Global Sync process.
Accepted values are True or False (case
insensitive). If no value is specified, this
will default to False.

No

-30

Invalid
network global
sync option:
option

ipAddress

The IP address or fully-qualified domain

name (FQDN) of the Network Service.
This must be a valid IPv4 or IPv6 IP
address, or a fully-qualified host name.

Yes

-26

Invalid
network service
address: address

name

The name of the Network Service. This

can be any combination of letters and
numbers.

Yes

threshold

Default scope utilization warning

threshold. Provide warnings when usage
of a pool assigned to this service is
exceeded. If no value is specified, this will
default to 90.

No

-57

Invalid alert
threshold: value

type

The type of Network Service. Accepted

value is dhcp. If this column is left
blank, dhcp is assumed.

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

userPassword

The password used by the collection

method (scp or ftp) to log in to the
remote server. Used in conjunction with
the User name for collection.

No

vendor

The Network Service product name. This

must be a value already defined in
IPControl, for example, INS DHCP or
CNR DHCP.

Yes

-47

productAction
failed

-99

Product not
found

-28

Unrecognized
collection type:
type

232 IPControl CLI and API Guide

Im portNetService

Elem ent

Accepted Values

Required

vendorInfo

A string array containing vendor specific

information for the products 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

Im portZone

ImportZone
Overview

The ImportDnsZone API enables the web service client to import zones into IPControl.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the importDnsZone request and response
messages.
<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.

Request

The complex type WSDnsZone, which is passed as input from the client to the web service, is
described in the next section.
Parameters
WSDnsZone

Below is the portion of Imports.wsdl that describes WSDnsZone, the parameter structure passed
to importDnsZone. The elements are described in the table that follows.
<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

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. If not specified, no
MNAME will be used. This field only
applies to master zones. It will be
ignored for all other zone types and
any zone designated as an Alias zone.
Accepted values are true or false. If
not specified, defaults to true. This
field only applies to master zones. It
will be ignored for all other zone
types.
Indicates if the imported zone is
intended to be a alias zone. 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. If
not specified, defaults to false.
Specifies the DNS allow -update
address match list a BIND based
server uses to filter DDNS update
requests against.

acceptZoneTransfers

aliasZone

allowUpdateACL

This free text field only applies to

master zone types and is accepted
without input validation.
Setting this field value to !BLANK!
on a zone update will serve to
completely remove the allow -update
option from the zone.

autogenNSGlue

This field is ignored for non-master

zones.
Accepted values are true or false. If
not specified, defaults to true.

domainName

Domain name already defined to

IPControl

domainType

Domain type name already defined to

IPControl. If not specified, the
Default domain type will be used.

Required Return
Code

Faultstring

No

-236

MNAME valid only for

master zones

-238

Domain is not an alias:

domain

No

No

Yes, when -252

Dynamic
Zone is
true, one
of Allow
Update
ACL or
Update
Policy
must be
specified.

Update option invalid for

non-dynamic zone

No

-241

autogenNSGlue must be
true or false, 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

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

ModifyBlock

Elem ent

Description

Modify?

Return
Code

Fault String

primarySubnet

Flag indicating if this subnet is

primary. Accepted values are
true or false.
Valid only for Deployed blocks
in device containers.

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. See below.

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.

Each element in the array has the
format name=value where
name is the UDF tag name.

Yes

Flag, 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.

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. In the case of reparenting blocks contained in device containers, a
target interface name must also be provided. To reparent 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, setting the new container name and in the case of device
container, the new interface name. Lastly, pass that modified structure to the ModifyBlock
API.
Note: ModifyBlock either reparents, when a new container name different than the
current parent container has been specified, or modifies the block without a reparent. Both
cannot be performed during the same modify block invocation.
Application Program Interfaces (API) 249

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.wsdl that describes WSSubnetPolicy, the structure passed in
WSGenericBlock as subnet. The elements are described in the table that follows.
<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.

yes

-67

DHCP Option Set name

not found

DHCPPolicySet

The name of a previously defined

DHCP policy set.

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.

yes

-93

DNS Server name not

found.

-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, this
attribute can be used to allow the
primaryDHCPServer attribute value
to cascade to these address pool and
IP address objects. 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.
Accepted value is an IP address.

yes

-26

Invalid IP Address
address

250 IPControl CLI and API Guide

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. This
cannot be the same as the primary
DHCP server.

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. 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. Only required for
non-default domain types.

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

-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.

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.

yes

-95

Invalid reverse DNS

Domain name

reverseDomain
Types

The domain types corresponding to

the domains listed in reverseDomains.
Only required for non-default domain
types.

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. You can apply a template
and specify address details when changing a blocks status to Deployed, or when modifying a
block that is already of status Deployed.
WSAllocationTemplateDetails

Below is the portion of Imports.wsdl that describes WSAllocationTemplateDetails, the

structure passed in WSGenericBlock as addrDetails. The elements are described in the
table that follows.
<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

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. This must

match the specification in the
Allocation Template. If not specified,
defaults to false.

Yes/No

sharename

The name used to link address pools

together.

No

Identify the address allocation within

the template. This must match the
specification in the Allocation
Template..

Yes/No

-174

Invalid starting offset:

offset for allocation
template: templateName

Deprecated
startingOffset

252 IPControl CLI and API Guide

ModifyPendingApproval

ModifyPendingApproval
Overview

The ModifyApproval API enables the web service client to approve or reject changes
submitted to the administrators pending approval queue.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the modifyPendingApproval request

and response messages.
<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.

Request

The complex type WSPendingApproval, which is passed as input from the client to the
web service, is described in the next section.
Parameters
WSPendingApproval

Below is the portion of Imports.wsdl that describes WSPendingApproval, the parameter

structure passed to modifyPendingApproval. The elements are described in the table that
follows.
<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.

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

Elem ent

Description

Modify?

reason

The text entered at creation for

the allocation reason.

No.

workflowId

The id of the pending approval

request retrieved using an
ExportItemPendingApproval, for
example,
ExportResourceRecordPendingA
pproval.

No

254 IPControl CLI and API Guide

Return
Code

Fault String

-162

Workflow id not
found: id

SplitBlock

SplitBlock
Overview

The SplitBlock API enables the web service client to split an existing block into smaller
blocks.
Request and Response Messages

Below is the portion of Imports.wsdl that describes the splitBlock request and response
messages.
<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.

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.
targetStartAddress

Specify the start address of the target block. This is useful for creating a block using the
specified start address and target block size. If no start address is specified, the start address of
the block being split will be used.
targetSize

Specify the desired CIDR block size after the split. This parameter works in conjunction with
the equalSizes parameter.
equalSizes

If true, the block is split such that all resulting blocks have the targetSize CIDR size. If
false, the block is split such that the fewest number of new blocks is created, along with two
blocks of targetSize.

Application Program Interfaces (API) 255

SplitBlock

For example, if a /24 is split with a target size of /27 with equalSizes set to true, the result
will be eight /27 blocks. If a /24 is split with a target size of /27 with equalSizes set to
false, the result will be one /25, one /26 and two /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

getAddressPool

Gets
Overview

This section explains the web services available for retrieving individua l objects from
IPControl. These services can be used in conjunction with Imports to modify IPControl
objects. Each of these services is available as an operation in the Gets web service. 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.
This call can be used in conjunction with the ImportAddressPool call to modify an
existing address pool. Use this call to retrieve an address pool based on its starting address.
Modify the returned structure as needed and pass the modified structure to
ImportAddressPool. ImportAddressPool will perform an update instead of a create
due to the presence of an ID element in the address pool structure.
Request and Response Messages

Below is the portion of Gets.wsdl that describes the getAddressPool request and response
messages.
<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, a WSAddrpool structure is filled in with its information. This
structure is also used by the ImportAddressPool API call.
Request

There are two parameters in the request.

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.

Only if startAddr is not

unique due to
overlapping blocks.

Return Codes

If the address pool is not found, the call will fail with an error code of -117.

Application Program Interfaces (API) 257

getBlock

getBlock
There are two calls to retrieve blocks:

getBlockByName

getBlockByIpAddress

Both calls return a WSGenericBlock data structure. (See the ModifyBlock call for a
description of WSGenericBlock.) As their names suggest, these calls differ in how the
block is located.
Use one of the above calls in conjunction with the ModifyBlock call to update an existing
block. Modify the returned structure as needed and pass the modified structure to
ModifyBlock. Note that the complete container path will be returned in the
WSGenericBlock.
Request and Response Messages

Below is the portion of Gets.wsdl that describes the getBlockByName and

getBlockByIpAddress request and response messages.
<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, a WSGenericBlock structure is filled in with its information. See the
ModifyBlock API call for more information.
getBlockByName Request

This request has two parameters.

Param eter Nam e

Description

Required

Name

The Name of the block, e.g. 10.0.0.0/24

Yes

Container

The container holding the block.

Only if name is not

unique.

258 IPControl CLI and API Guide

getBlock

getBlockByIpAddress Request

This request has four parameters.

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.

size

The blocks CIDR size.

Only if there are multiple blocks with

the same starting address, e.g.
10.0.0.0/8 (aggregate) and 10.0.0.0/24
(child block).

status

The blocks status. Valid values are Free,

Reserved, Aggregate, Deployed,
FullyAssigned

Only if there are multiple blocks with

the same starting address. This can
occur for aggregates where there is a
free block with the same starting
address and size.

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

getContainer

getContainer
There is one call to retrieve a container: getContainerByName.
This call returns a WSContainer data structure.
Use this call in conjunction with the ImportContainer call to modify an existing container.
Modify the returned structure as needed and pass the modified structure to
ImportContainer. ImportContainer will update the container based on the presence
of an ID element in the WSContainer structure.
Request and Response Messages

Below is the portion of Gets.wsdl that describes the getContainerBy request and response
messages.
<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, a WSContainer structure is filled in with its information. This
structure is also used by the ImportContainer API call.
getContainerByName Request

There is one parameter in the request.

Param eter Nam e

Description

Required

containerName

The name of the container.

Yes

Return Codes
Condition

Return Code

Container not found

-5

260 IPControl CLI and API Guide

getDevice

getDevice
There are three calls to retrieve a device:

getDeviceByIPAddr

getDeviceByMACAddress

getDeviceByHostname

All three calls return a WSDevice data structure. As their names suggest, they differ in how
the device is located.
Use any of the three calls in conjunction with the ImportDevice call to modify an existing
device. Modify the returned structure as needed and pass the modified structure to
ImportDevice. ImportDevice will update the device based on the presence of an ID
element in the WSDevice structure.
Request and Response Messages

Below is the portion of Gets.wsdl that describes the getDeviceBy request and response
messages.
<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, a WSDevice structure is filled in with its information. This structure
is also used by the ImportDevice API call.
getDeviceByIPAddr Request

There are two parameters in the request.

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.

Only if ipAddress is not

unique due to
overlapping blocks.

Application Program Interfaces (API) 261

getDevice

getDeviceByMACAddress Request

There is one parameter in the request.

Param eter Nam e

Description

Required

macAddress

The MAC address of the device

Yes

getDeviceByHostname 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

getDeviceResourceRec

getDeviceResourceRec
This operation retrieves information about a DNS resource record from IPControl.
This call can be used in conjunction with the ImportDeviceResourceRecord call to
modify an existing DNS resource record. 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. ImportDeviceResourceRecord will perform an
update instead of a create due to the presence of an ID element in the resource record
structure.
Request and Response Messages

Below is the portion of Gets.wsdl that describes the getDeviceResourceRec request and
response messages.
<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, a WSDeviceResourceRec structure is filled in with its

information. This structure is also used by the ImportDeviceResourceRecord API call.
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.

Defaults to Default.
The OWNER section of the resource record.

type

The type of resource record.

Yes

classtype

The value currently supported is IN.

No

rdata

The text for the data area of the record.

No

hostname

The device host name.

Yes, unless IpAddress is

specified.

ipAddress

The IP address of the device.

Yes, unless hostname is

specified.

container

The name of the container that holds the device.

Yes, if ipAddress is in
overlapping space.

No

Application Program Interfaces (API) 263

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

getDhcpServer

getDhcpServer
There are two calls for retrieving information about a DHCP server:

getDhcpServerByName

getDhcpServerByIpAddress

Both return a WSDhcpServer structure. As their names suggest, 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. Modify the returned structure as needed and pass the modified
structure to ImportDhcpServer. ImportDhcpServer will update the server based on
the presence of an ID element in the WSDhcpServer structure.
Request and Response Messages

Below is the portion of Gets.wsdl that describes the Dhcp Server request and response
messages.
<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, a WSDhcpServer structure is filled in with its information.
This structure is also used by the ImportDhcpServer API call.
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

getDom ainResourceRec

getDomainResourceRec
This operation retrieves information about a DNS resource record from IPControl.
This call can be used in conjunction with the ImportDomainResourceRecord call to
modify an existing DNS resource record. 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. ImportDomainResourceRecord will
perform an update instead of a create due to the presence of an ID element in the resource
record structure.
Request and Response Messages

Below is the portion of Gets.wsdl that describes the getDomainResourceRec request and
response messages.
<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, a WSDomainResourceRec structure is filled in with its

information. This structure is also used by the ImportDomainResourceRecord API call.
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.

No

owner

The OWNER section of the resource record.

No

type

The type of resource record.

Yes

classtype

The value currently supported is IN.

No

rdata

The text for the data area of the record.

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

getNetelementInterface

getNetelementInterface
There is one call to retrieve a network element interface: getNetElementInterface.
This call returns a WSNetElementInterface data structure.
Use this call in conjunction with the ImportNetElementInterface call to modify an
existing network element interface. Modify the returned structure as needed and pass the
modified structure to ImportNetElementInterface.
ImportNetElementInterface updates the network element interface based on the
presence of an ID element in the WSNetElementInterface structure.
Request and Response Messages

Below is the portion of Gets.wsdl that describes the getNetElementInterface request and
response messages.
<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, a WSNetElementInterface structure is filled

in with its information. This structure is also used by the ImportNetElementInterface
API call.
getNetelementInterface Request

There are two parameters in the request.

Param eter Nam e

Description

Required

neName

The name of the network element.

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

getPrefixPool

getPrefixPool
There are two calls for retrieving information about a Prefix Pool:

getPrefixPoolByName

getPrefixPoolByStartAddr

Both return a WSPrefixPool structure.

Use either of the calls in conjunction with the ImportPrefixPool call to modify an
existing Prefix Pool. Modify the returned structure as needed and pass the modified structure
to ImportPrefixPool. ImportPrefixPool will perform an update instead of a create
due to the presence of an ID element in the prefix pool structure.
Request and Response Messages

Below is the portion of Gets.wsdl that describes the Prefix Pool request and response messages.
<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, a WSPrefixPool structure is filled in with its information. This
structure is also used by the ImportPrefixPool API call.
getPrefixPoolByName Request

There is one parameter in the request.

Param eter Nam e

Description

Required

Name

The name of the Prefix Pool

Yes

getPrefixPoolByStartAddr Request

There is one parameter in the request.

Param eter Nam e

Description

Required

Addr

The Start Address of the Prefix Pool

Yes

Return Codes

If the prefix pool is not found, the call will fail with an error code of -262.

268 IPControl CLI and API Guide

ArpDiscoverNetElement

Tasks
Overview

This section explains the web services available for issuing tasks to IPControl, and for
querying the status of IPControl tasks. Each of these services is available as an operation in
the TaskInvocation web service. 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.
For more information, look for error messages in the web services log.
Code

Description

-1

System Error: Serious error preventing the operation from continuing, such as failure
to connect to the database.

-2

Access Denied: User failed security check.

-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 routers ARP cache.
Request and Response Messages

Below is the portion of TaskInvocation.wsdl that describes the arpDiscoverNetElement

request and response messages.
<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 web service returns the task number. Pass this task
number 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.

Application Program Interfaces (API) 269

DHCPUtilization

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
arpDiscoverNetElement. The individual parameters are described in the table that
follows.
<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.

performNetHostAdd

Set to true to automatically add new hosts that are found during

discovery.
updateReclaim

Set to true to update the last discovered counters for blocks and hosts

defined within the network element.

ignoreDuplicates

Set to true to ignore duplicate hostnames encountered while adding new

hosts.

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.
Request and Response Messages

Below is the portion of TaskInvocation.wsdl that describes the dhcpUtilization request and
response messages.
<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, the web service returns the task number. Pass this task
number 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.
270 IPControl CLI and API Guide

DHCPUtilization

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
dhcpUtilization. The individual parameters are described in the table that follows.
<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 administrators user id

Yes

password

IPControl administrators password

Yes

elementName

Name of the DHCP server for which IPControl will

collect statistics.

Yes, when IP Address

or FQDN is not
specified.

ipAddress

IP Address or fully-qualified (FQDN) of the DHCP

server for which IPControl will collect statistics.

Yes, when the

elementName is not
specified.

Application Program Interfaces (API) 271

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.
Request and Response Messages

Below is the portion of TaskInvocation.wsdl that describes the discoverNetElement request

and response messages.
<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, the positive integer returned by the web service
corresponds 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
discoverNetElement. The individual parameters are described below.
<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 administrators user ID

Yes

password

IPControl administrators password

Yes

elementName

Name of Network Element (device)

to discover.

Yes, when IP Address or FQDN is not

specified.

ipAddress

IP Address or fully-qualified
(FQDN) of the device to discover.

Yes, when the elementName is not

specified.

272 IPControl CLI and API Guide

GetTask

GetTask
Overview

The getTask API enables the web service client to query the status of tasks and receive
detailed information about those tasks.
Request and Response Messages

Below is the portion of TaskInvocation.wsdl that describes the getTask request and response
messages.
<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

Task ID

Service

Scope

Status

Process start time

Request

The input from the client to the web service is described in the next section.
Parameters

Below is the portion of TaskInvocation.wsdl that describes the parameter structure passed to
getTask . The parameter is described in the table that follows.
<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.

Yes

Application Program Interfaces (API) 273

GetTaskStatus

GetTaskStatus
Overview

The getTaskStatus API enables the web service client to query the status of tasks.
Request and Response Messages

Below is the portion of TaskInvocation.wsdl that describes the getTaskStatus request and
response messages.
<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, described next in this
section.
Request

The input from the client to the web service is described in the next section.
Parameters

Below is the portion of TaskInvocation.wsdl that describes the parameter structure passed to
getTaskStatus. The parameter is described below.
<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.

Yes

274 IPControl CLI and API Guide

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.
Request and Response Messages

Below is the portion of TaskInvocation.wsdl that describes the globalNetElementSync

request and response messages.
<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, 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
globalNetElementSync . The individual parameters are described below.
<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 administrators user id

Yes

password

IPControl administrators password

Yes

Application Program Interfaces (API) 275

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 administrators user id

Yes

password

IPControl administrators 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 administrators user id

Yes

password

IPControl administrators 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 objects 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

Name

The name of the Network Element. This can be

any combination of letters and numbers.

Yes

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

Vendor

The vendor of the Network Element. Vendor is

predefined in IPControl.

Yes when
Model is
specified.

Model

The model name of the Network Element. Model

is predefined in IPControl.

Yes when
Vendor is
specified.

Type

The type of Network Element. Accepted values

are CMTS, Router, Switch, or VPN.

Yes

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

Agent Name

The exact name of the IPControl Agent that is

responsible for contacting this Network Service.

Yes

Telnet user

A user name used to telnet to this device.

No

Telnet password

A password used by the telnet user to telnet to this

device.

No

Enable password

Password used to enter enabled or privileged

mode on the device.

No

Read community string

The community string used by SNMP to read

details from this network element.

No

Interfaces

A list of enabled interfaces. Multiple interfaces are

specified by separating each interface with the |
character.

No

V3 Username

Required if using SNMP V3.

No

V3 Authentication
Protocol

Either MD5 or SHA1. Leave blank or set to

NONE if no authentication.

No

V3 Authentication
Password

Required if field N is set to either MD5 or SHA1

No

V3 Privacy Protocol

Only DES supported at this time. Leave blank or

set to NONE if no privacy.

No

V3 Privacy Password

Required if field P is set to DES.

No

V3 Context Name

SNMP V3 Context name, if needed.

No

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

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. This API enables the web service
client to filter the list of Network Services retrieved.
Request and Response Messages

Below is the portion of Exports.wsdl that describes the exportNetServicesAsCSV request

and response messages.
<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. Each Network Service description is separated by a new line
character. The values within each Network Service description are separated by commas, and
described in the table below. Fields that are not required may not always contain values. Fields
H and I will not be exported, since these could contain sensitive information. The columns
are preserved to maintain conformity with the ImportNetService API.
Col

Field

Accepted Values

Required

Name

The name of the Network Service. This can be

any combination of letters and numbers.

Yes

IP Address/FQDN

The IP address or fully-qualified domain name

(FQDN) of the Network Service. This must be a
valid IPv4 or IPv6 IP address, or a fully-qualified
host name.

Yes

Type

The type of Network Service. This is always dhcp.

No

Product name

The Network Service product name. This is a value

already defined in IPControl, for example, INS
DHCP or CNR DHCP.

Yes

Agent name

The name of the IPControl Agent that is

responsible for contacting this Network Service.

Yes

Global Sync

Whether or not this Network Service is included in

the Global Sync process. Values are true or false.

Yes

Collection Method

The method by which the IPControl Agent collects

data from the Network Service. Values are scp or
ftp.

Yes

User name for

The username used by the collection method (scp

Yes

Application Program Interfaces (API) 283

ExportNetServicesAsCSV

Col

Field

Accepted Values

collection

or ftp) to log in to the remote server. This is

exported as username.

Required

Password for collection

The password used by the collection method (scp

or ftp) to log in to the remote server. Used in
conjunction with the User name for collection.
This is exported as password.

Yes

Collection port

The port number the collection method (scp or

ftp) is listening on.

No

Container(s)

No longer used.

VendorInfo

Vendor specific information for the products

collection type. Each item of information is
specified in this single field by separating each field
with the | character.

No

For collection types qip,adc, msft and isc, the

information includes the DHCP Configuration file
pathname and DHCP Active Lease file pathname.
For example,
/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

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 Services, use ExportAllNetServicesAsCSV.
Parameters

Below is the portion of Exports.wsdl that describes the parameter structure passed to
exportNetServicesAsCSV . 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="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

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.

ipAddress

IP Address or fully-qualified (FQDN) of the Network Service.

globalsync

Whether or not this Network Service is included 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 Service.

serviceType

The type of Network Service. Specify dhcp.

Application Program Interfaces (API) 285

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. To filter the request,
use the exportNetServicesAsCSV API.
Request and Response Messages

Below is the portion of Exports.wsdl that describes the exportAllNetServicesAsCSV

request and response messages.
<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. See the Response
section of ExportNetServicesAsCSV on page 283 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
exportAllNetServicesAsCSV.
<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. This request
string specifies a query which is used to filter the list of exported objects. The query syntax
consists of one or more selectors, combined into a Boolean expression. For example, to
export the Device with a hostname of mydevice, the request query string would be as
follows:
name=mydevice

Selectors which are based on a text field can support the keywords begins, ends, or
contains to support wildcarding. For example, to export all Devices with a hostname
beginning with my, 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, to export all Devices with a hostname beginning
with my and with a device type of PC, 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.
Each new export web service supports a specific set of selectors. Please refer to each API
definition on the following pages for the supported selector syntax.
Options
Some of the new web services APIs also support a second parameter, which is used to pass
options to the service. Refer to the WSDL and the sections that follow for more information.
Paging
The new web services APIs also support the concept of paging through the export results.
Some queries may result in thousands of exported objects. Due to memory and network
constraints, it is not feasible to return all the results in a single response. Therefore, the web
services client should specify the starting point within the list of results, as well as the number
of results to return. This is accomplished using the WSContext object.
Each new web service must be initialized by the client by calling the initialization method
associated with the export web service. Therefore, the client will always perform at least two
web service requests to export objects from IPControl. For example, when exporting devices,
the client must call initExportDevice first, followed by a call to exportDevice. The
export service initialization APIs take the query string as the request, and return a
WSContext object in the response. The export services APIs themselves take the
WSContext object as the request, and return an array of exported objects in the response.

Application Program Interfaces (API) 287

Sessions

Sessions
Initialization calls are linked to subsequent export calls by using sessions. The initialization call
creates a session and returns a session identifier as part of the SOAP envelope. This session
identifier must be provided on all subsequent export calls, or an error occurs.
If you are using the Java Axis package to generate your web services client, configure your
client to use the SimpleSessionHandler, as described in the documentation. If not, the
details of the session handling follow.
The session identifier is returned as part of the SOAP Header. The namespace is
http://xml.apache.org/axis/session. The element name is sessionID. An
example of the returned header follows, where the value of the sessionID is 12345678.
<soapenv:Header>
<ns1:sessionID soapenv:mustUnderstand="0" xmlns:ns1="http://xml.apache.org/axis/session">
12345678
</ns1:sessionID>
</soapenv:Header>

The response processing for the init* calls must capture this element and value. The
subsequent export* calls must include this element and value in the SOAP Header.
Without this, the export* calls cannot correlate with the init call, and return an error.
WSContext

Below is the portion of Exports.wsdl that describes WSContext, the parameter structure
returned by the initExport* APIs, and passed to the export* APIs. The elements are
described in the table that follows.
<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.

options

Reserved

query

Reserved

resultCount

Reserved

internalResultCount

Reserved

288 IPControl CLI and API Guide

ExportRootBlock

ExportRootBlock
Overview

The exportRootBlock API enables the web service client to issue a request to retrieve a
list of Root Blocks from IPControl. This service enables the client to filter the list of Root
Blocks retrieved.
Initialization

Before the exportRootBlock API is called, the web service client must call
initExportRootBlock to initialize the API. Below is the portion of Exports.wsdl that
describes the initExportRootBlock request and response messages.
<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. The query string syntax is defined previously. Supported selectors for exporting root
blocks are defined in the following table.
Selector

Description

Exam ple

name

The name of the block to export.

Partial names are supported using the
begins/ends/contains qualifiers.

name=My Block
name begins My
name ends Block
name contains Bl

block

The CIDR notation of the block to

export. The accepted format for
CIDR notation is
block_address/block_size.

block=10.0.0.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.

container=Exton

block=10.0.*/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.1

ipaddressrange

A range of IP addresses that span one

or more blocks starting and ending
addresses.

ipaddressrange=10.0.0.0-10.0.10.255

udf

The name and value of a UDF

attached to the block(s) to be exported.

UDF.myudf=myudf_value

Application Program Interfaces (API) 289

ExportRootBlock

Response

The response from the initExportRootBlock web service is a WSContext object

defined previously. This WSContext object must be included in each successive call to
exportRootBlock, as described below.
Service Invocation

The portion of Exports.wsdl that describes the exportRootBlock request and response
messages is shown below.
<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. This WSContext has the
maxResults field set to a default value of 100. When this context is provided to a
subsequent call to exportRootBlock, the number of exported blocks is limited to the first
100 that match the criteria in the given query filter. 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. However, the value specified
by the client cannot exceed 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 WSRootBlocks can
then be modified and/or imported using the importRootBlock API. The format of the
WSRootBlock matches that defined by the importRootBlock.
WSRootBlock

Below is the portion of Exports.wsdl that describes WSRootBlock, the array of structures
returned by exportRootBlock. 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: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

ExportRootBlock

</complexType>

Elem ent

Accepted Values

RIR

The Regional Internet Registry this space was obtained from.

SWIPname

SWIP/Net name for the block.

allocationReason

The name of a pre-existing Allocation Reason.

allocationReasonDescription

A description of the reason for the allocation.

allowOverlappingSpace

Whether or not to allow duplicate (overlapping) address space

in this block.

blockAddr

The starting address for the block.

blockName

A name for the block. Defaults to system supplied name of

Address space/Block size.

blockSize

The size of the block in short-notation (e.g., 24 for a

255.255.255.0 network).

blockType

The Block Type of the block. If not specified, a block type of

Any is assumed.

container

The name of the container holding the block.

createReverseDomains

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.

description

A description of the block.

domainType

The domain type of the reverse domain.

organizationId

The organization id for the Regional Internet Registry.

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.

Application Program Interfaces (API) 291

ExportChildBlock

ExportChildBlock
Overview

The exportChildBlock API enables the web service client to issue a request to retrieve a
list of Child Blocks from IPControl. This service enables the client to filter the list of Child
Blocks retrieved.
Initialization

Before the exportChildBlock API is called, the web service client must call
initExportChildBlock to initialize the API. The portion of Exports.wsdl that describes
the initExportChildBlock request and response messages is shown below.
<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. The query string syntax is defined previously. Supported selectors for exporting child
blocks are defined in the following table.
In addition, the initExportChildBlock service accepts a Boolean flag that specifies if the
free blocks maintained by IPControl should be included in the export.
Selector

Description

Exam ple

name

The name of the block to export. Partial

names are supported using the
begins/ends/contains qualifiers.

name=My Block
name begins My
name ends Block
name contains Bl

block

The CIDR notation of the block to export.

The accepted format for CIDR notation is
block_address/block_size.

block=10.0.0.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.

container=Exton

block=10.0.*/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 special
^container= declarative allows the container
name to be specified. This can be fully
qualified or not.

292 IPControl CLI and API Guide

parentName=172.16.0.0/23
parentName=172.16.0.0/23^container=North
parentName=172.16.0.0/23^container=
/InControl/Canada/North

ExportChildBlock

Selector

Description

Exam ple

Parent
Container

Only applied when parentBlock is

supplied. Specifies the name of the parent
blocks container. Useful in order to
eliminate ambiguity by specifying the
container name, fully qualified or not.

parentContainer=North

recursive

Only appied when paretnBlock is supplied.

When set to true, all child blocks of the
specified parent name recursively will be
exported.

recursive=true

status

The status of the block(s) to be exported.

Valid options are {free, aggregate,
reserved, subnet, fullyassigned}.

status=aggregate

interface

The name of an interface to which the

block is attached.

interface=eth0

ipaddress

An IP address that falls within the start and

ending addresses of a block to be exported.

ipaddress=10.0.0.1

ipaddressrange

A range of IP addresses that span one or

more blocks starting and ending addresses.

ipaddressrange=10.0.0.0-10.0.10.255

udf

The name and value of a UDF attached to

the block(s) to be exported.

UDF.myudf=myudf_value

parentContainer=/InControl/Canada/North

Response

The response from the initExportChildBlock web service is a WSContext object

defined previously, and must be included in each successive call to exportChildBlock, as
described below.
Service Invocation

Below is the portion of Exports.wsdl that describes the exportChildBlock request and
response messages.
<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, and has the maxResults field set
to a default value of 100. When this context is provided to a subsequent call to
exportChildBlock, the number of exported blocks is limited to the first 100 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 exportChildBlock service to modify
the size of the resultant WSChildBlock object array. However, the value specified by the
client cannot exceed 100.

Application Program Interfaces (API) 293

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 WSChildSubnetBlock structure consists of two substructures ( WSChildBlock and
WSSubnetPolicy) which can then be modified and/or imported using the
importChildBlock API. The format of the WSChildBlock and the WSSubnetPolicy
match that defined by the importChildBlock.
WSChildSubnetBlock

Below is the portion of Exports.wsdl that describes WSChildSubnetBlock.

<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.wsdl that describes WSChildBlock, the first parameter
structure passed to 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.

allocationReasonDescription

A description of the reason for the allocation.

294 IPControl CLI and API Guide

ExportChildBlock

Elem ent

Description and accepted values

allocationTemplate

Reserved

blockAddr

The starting address of the block.

blockName

The name of the block.

blockSize

The size of the block in short-notation (e.g., 24 for a 255.255.255.0

network).

blockStatus

The current status of the block. Possible values are: Deployed,

FullyAssigned, Reserved, Aggregate.

blockType

The Block Type for the block.

container

The name of the container holding the block.

createReverseDomains

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.

description

The description of the block.

domainType

The domain type of the reverse DNS domain.

excludeFromDiscovery

True when this subnet excluded from Host Discovery tasks.

interfaceAddress

The address(es) of the interface IP address.

interfaceName

If this block is in a device container, the name of the interface to

which its attached.

ipv6

True if this is an IPV6 block.

primarySubnet

True if this is a primary subnet.

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.

WSSubnetPolicy

The portion of Exports.wsdl that describes WSSubnetPolicy, the second parameter structure
passed to ImportChildBlock is shown below. The elements are described in the table that
follows.
<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.

DHCPPolicySet

The name of a previously defined DHCP policy set.

Application Program Interfaces (API) 295

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.

defaultGateway

The default gateway that DHCP clients on this subnet will use.
Accepted value is an IP address.

failoverDHCPServer

The name of the DHCP server that will act as failover for this
subnet. This cannot be the same as the primary DHCP server.

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.

forwardDomainTypes

The domain types corresponding to the domains listed in

forwardDomains. Only required for non-default domain types.

networkLinks

Reserved

primaryDHCPServer

The name of the DHCP server that will act as primary for this
subnet.

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.

reverseDomainTypes

The domain types corresponding to the domains listed in

reverseDomains. Only required for non-default domain types.

Optional Service

After the initExportChildBlock API is called to initialize the API, the web service client
can, optionally, call the initExportChildBlockUDFTags API. This service is used by the
ExportChildBlock CLI to create the header line used when exporting with the expanded
format option. The portion of Exports.wsdl that describes the
initExportChildBlockUDFTags request and response messages is shown below.
<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.
Response

The result returned from the initExportChildBlockUDFTags service is an array of

strings. 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.

296 IPControl CLI and API Guide

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.
Initialization

Before the exportContainer API is called, the web service client must call
initExportContainer to initialize the API. The portion of Exports.wsdl that describes the
initExportContainer request and response messages is shown below.
<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 query string syntax is defined previously. Supported selectors for exporting
devices are defined in the following table.
Selector

Description

Exam ple

Name

Exports container by container name.

Name=west;
Name ends est
Name begins wes
Name contains es

User Defined Fields

UDF.order=first
UDF.order begins fir

Exports container by user defined field

name and value. Usage
UDF.<fieldname>=<fieldvalue>

UDF.order ends rst

UDF.order contains irs

The options array is used to pass additional option information to the service. The valid
options for ExportContainer are described in the following table:
Option

Description and accepted values

ParentContainerFullPath

When this option is specified, the service populates the parent container field using
the long format, 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, as
described below.

Application Program Interfaces (API) 297

ExportContainer

Service Invocation

The portion of Exports.wsdl that describes the exportContainer request and response
messages is shown below.
<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, the number of exported containers is limited to the
first 100 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 exportContainer
service to modify the size of the resultant WSContainer object array. However, the value
specified by the client cannot exceed 100.
Response

The result returned from the exportContainer service is an array of WSContainer

objects matching the selection criteria specified in the query filter. The WSContainer can
then be modified and/or imported using the importContainer API. The WSContainer
object is described in the ImportContainer API section on page 204.

298 IPControl CLI and API Guide

ExportDevice

ExportDevice
Overview

The exportDevice API enables the web service client to issue a request to retrieve a list of
Devices from IPControl. This service enables the client to filter the list of Devices retrieved.
Initialization

Before the exportDevice API is called, the web service client must call
initExportDevice to initialize the API. The portion of Exports.wsdl that describes the
initExportDevice request and response messages is shown following.
<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.
The query string syntax is defined previously. Supported selectors for exporting devices are
defined in the following table.
In addition, the initExportDevice service accepts the options array, described following
the selectors table.
Selector

Description

Exam ple

Name

Exports device by hostname.

Name=host;
Name ends ost
Name begins hos
Name contains os

Container

Exports device by Container name.

Container=Exton;
Container ends ton
Container begins Ext
Container contains xto

IP Address

Exports device by IP Address.

IPAddress=10.0.0.1

Note , this filter should not be used on a

IP Address Range

multi-homed device, unless the desired

result is to export the device with only
the IP Address specified in the Selector
filter. Instead, use IPAddressRange,
Name, or multiple IPAddress (separated
by Or) Selector type filters.
Exports device by IP Address range.

IPAddressRange=10.0.0.1-11.0.0.1

Application Program Interfaces (API) 299

ExportDevice

Selector

Description

Exam ple

Device type

Exports device by Device type.

DeviceType=Router
DeviceType ends uter
DeviceType begins Rou
DeviceType contains out

Domain

Exports device by Domain name.

Domain=ins.com.
Domain begins ins.c
Domain ends .com.
Domain contains s.com

Block

Exports device by Block name.

Block=10.0.0.0/24
Block begins 10.0.0
Block ends .0/24
Block contains .0.0.0

Block Type

Exports device by Block type.

BlockType=Any
BlockType begins An
BlockType ends ny
BlockType contains n

User Defined Fields

Exports device by user defined field name

and value. Usage
UDF.<fieldname>=<fieldvalue>

UDF.order=first
UDF.order begins fir
UDF.order ends rst
UDF.order contains irs

Address Type

Exports device by address type. 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. When true

is indicated, devices will be exported
when an associated IP address is virtual.

Virtual=1 (for true)

Virtual=0 (for false)

The options array is used to pass additional option information to the service. 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. This flag is ignored if
a Container Selector is not included.

300 IPControl CLI and API Guide

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, as described
below.
Service Invocation

The portion of Exports.wsdl that describes the exportDevice request and response messages
is shown following.
<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. When this context is provided to a subsequent call to exportDevice,
the number of exported blocks is limited to the first 100 or less (see Paging), 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 exportDevice service to modify the size
of the resultant WSDevice object array. However, the value specified by the client cannot
exceed 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. Because of this and for performance, 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.
It will, however, always guarantee the number of results to be the max results value or less.
Response

The result returned from the exportDevice service is an array of WSDevice objects
matching the selection criteria specified in the query filter. The WSDevices can then be
modified and/or imported using the importDevice API. The format of the WSDevice
matches that defined by the importDevice.
WSDevice

Below is the portion of Exports.wsdl that describes WSDevice, the array of structures returned
by exportDevice. The elements are described in the table that follows.
<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

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.

DEPRECATED: This is now returned in the WSInterface structure for all
devices.

addressType

The address type of this device. Accepted values are: Static, Dynamic
DHCP, Automatic DHCP, Manual DHCP, Reserved, Dynamic NA
DHCPv6, Automatic NA DHCPv6, Dynamic TA DHCPv6, and
Automatic TA DHCPv6

Aliases

A string array containing the alias or list of aliases for this hostname. When
you specify an alias, a CNAME record is created. The alias may be fully
qualified (contains a trailing dot), or not. When fully qualified, everything that
is after the first qualifier is interpreted as a domain name. When not fully
qualified, the CNAME record will be created in the same domain as the
device.
To use this element, you must also specify resourceRecordFlag as true.

container

The name of the container that contains the device.

description

A description of the device.

deviceType

The name of a device type configured in IPControl.

domainName

Domain name already defined to IPControl

domainType

Domain type already defined to IPControl. If not specified, the Default

domain type will be used.

duid

DHCP Unique Identifier

dupWarning

If the administrator policy of the user indicates Warn for the Allow
Duplicate Hostnames Checking option, 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 not specified, defaults to false.

302 IPControl CLI and API Guide

ExportDevice

Elem ent

Accepted Values

hostname

Valid host name or APPLYNAMINGPOLICY.

hwtype

Specify Ethernet or Token Ring. When hwtype is specified, MACAddress

must also be specified.
DEPRECATED: This is now returned in the WSInterface structure for all
devices.

ipAddress

The IP Address of the device.

DEPRECATED: This is now returned in the WSInterface structure for all
devices.

resourceRecordFlag

Whether or not to add resource records for this device. If not specified as
true, defaults to false.

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.

Interfaces

An array of WSInterface structures. Each element in the array corresponds

to one interface for a multi-homed device, or the single interface for a singlehomed device. The fields in the WSInterface structure are listed below.
Except where noted, their value is the same as in the WSDevice structure.
- addressType
- container: reserved
- excludeFromDiscovery
- hwType
- id: The internal ID; provide this on a modify request
- ipAddress
- macAddress
- name: Interface Name
- sequence: reserved
- virtual: reserved

id

Internal id; provide this on a modify request

excludeFromDiscovery

Flag indicating if this device should be included in Host Discovery tasks.

Accepted values are true or false. If not specified, defaults to false.
DEPRECATED: This is now returned in the WSInterface structure for all
devices.

Optional Service

After the initExportDevice API is called to initialize the API, the web service client can,
optionally, call the initExportDeviceUDFTags API. 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.wsdl that describes the initExportDeviceUDFTags
request and response messages is shown below.
<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.
Application Program Interfaces (API) 303

ExportDevice

Response

The result returned from the initExportDeviceUDFTags service is an array of strings.

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.

304 IPControl CLI and API Guide

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. This service
enables the client to filter the list of resource records retrieved by device.
Initialization

Before the exportDeviceResourceRecord API is called, the web service client must call
initExportDeviceResourceRec to initialize the API. The portion of Exports.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. The query string
syntax is defined previously. Supported selectors for exporting device resource records by
device are defined in the following table.
In addition, 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. Specify the option parameter as recurseContainerHierarchy.
Selector

Description

Exam ple

Name

Select device by hostname.

Name=host;
Name ends ost
Name begins hos
Name contains os

Container

Select device by Container name.

Container=Exton;
Container ends ton
Container begins Ext
Container contains xto

IP Address

Select device by IP Address.

IPAddress=10.0.0.1

Note , this filter should not be used on a

multi-homed device, unless the desired

result is to export the device with only
the IP Address specified in the Selector
filter. Instead, use IPAddressRange,
Name, or multiple IPAddress (separated
by Or) Selector type filters.
IP Address Range

Select device by IP Address range.

IPAddressRange=10.0.0.1-11.0.0.1
Application Program Interfaces (API) 305

ExportDeviceResourceRecord

Selector

Description

Exam ple

Device type

Select device by Device type.

DeviceType=Router
DeviceType ends uter
DeviceType begins Rou
DeviceType contains out

Domain

Select device by Domain name.

Domain=ins.com.
Domain begins ins.c
Domain ends .com.
Domain contains s.com

Domain Type

Select device by domain type.

DomainType=Internal
DomainType begins abc
DomainType ends xyz
Domain Type contains lmnop

Block

Select device by Block name.

Block=10.0.0.0/24
Block begins 10.0.0
Block ends .0/24
Block contains .0.0.0

Block Type

Select device by Block type.

BlockType=Any
BlockType begins An
BlockType ends ny
BlockType contains n

User Defined Fields

Select device by user defined field name

and value. Usage
UDF.<fieldname>=<fieldvalue>

UDF.order=first
UDF.order begins fir
UDF.order ends rst
UDF.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, as described below.
Service Invocation

The portion of Exports.wsdl that describes the exportDeviceResourceRec request and

response messages is shown following.
<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

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. When this context is provided to a subsequent call to
exportDeviceResourceRec, the number of exported resource records is limited to the
first 5000 devices, or less (see Paging), 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. However, the value specified by the client cannot
exceed 5000.
Paging

A device in IPControl is normalized within the database and thus may be represented by more
than a single row in multiple tables. Because of this and for performance, 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. It will, however, always guarantee the
number of results to be the max results value or less.
Response

The result returned from the exportDeviceResourceRec service is an array of

WSDeviceResourceRec objects matching the selection criteria specified in the query filter.
The WSDeviceResourceRecs can then be modified and/or imported using the
importDeviceResourceRecord API. The format of the WSDeviceResourceRec
matches that defined by the importDeviceResourceRecord.
WSDeviceResourceRec

The portion of Exports.wsdl that describes WSDeviceResourceRec, the array of structures

returned by exportDeviceResourceRec is shown following. The elements are described
in the table that follows.
<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

ExportDeviceResourceRecord

Elem ent

Accepted Values

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. The container is then used to uniquely determine the device.

domainType

Domain type already defined to IPControl. If not specified, the Default

domain type will be used.

domain

Domain name where resource records are to be added.

hostname

The device host name.

ipAddress

The IP Address of the Device.

owner

The owner field of the resource record.

resourceRecClass

The Class of the Resource Record. Defaults to IN.

resourceRecordType

The Type of the resource Record.

TTL

The Time To Live for the record.

data

The data portion of the resource record. The format is dependent on the
type specified above.

comment

Comment text associated with the resource record.

308 IPControl CLI and API Guide

ExportPrefixPool

ExportPrefixPool
Overview

The exportPrefixPool API enables the web service client to issue a request to retrieve a
list of Prefix Pools from IPControl. This service enables the client to filter the list of Prefix
Pools retrieved.
Initialization

Before the exportPrefixPool API is called, the web service client must call
initExportPrefixPool to initialize the API. The portion of Exports.wsdl that describes
the initExportPrefixPool request and response messages is shown following.
<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. The query string syntax is defined previously. Supported selectors for exporting
prefix pools are defined in the following table.
In addition, the initExportPrefixPool service accepts the options array, described
following the selectors table.
Selector

Description

Exam ple

Name

Exports prefix pool by name.

Name=pool1

Container

Exports prefix pool by Container name.

Container=Exton

Net Service

Exports prefix pool by assigned DHCP

server

Netservice=DhcpServer1

.
IP Address

Exports the prefix pool that contains that

address.

IPAddress=2001:db8::1

IP Address Range

Exports prefix pool by address range in

address/length format.

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, as
described below.
Service Invocation

The portion of Exports.wsdl that describes the exportPrefixPool request and response
messages is shown following.
Application Program Interfaces (API) 309

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. When this context is provided to a subsequent call to
exportPrefixPool, the number of exported pools is limited to the first 100, 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 exportPrefixPool service to modify
the size of the resultant WSPrefixPool object array. However, the value specified by the
client cannot exceed 100.
Response

The result returned from the exportPrefixPool service is an array of WSPrefixPool

objects matching the selection criteria specified in the query filter. The WSPrefixPools can
then be modified and/or imported using the importPrefixPool API. The format of the
WSPrefixPool matches that defined by the importPrefixPool.
WSPrefixPool

Below is the portion of Exports.wsdl that describes WSPrefixPool, the array of structures
returned by exportPrefixPool. 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>

310 IPControl CLI and API Guide

ExportPrefixPool

Elem ent

Description

id

The internal identifier for this address pool object

startAddr

The IP Address of the first address in the pool.

Length

Length of the prefix pool

type

One of Dynamic PD DHCPv6, Automatic PD DHCPv6

name

Address Pool name.

container

The name of the container that holds the block in which the pool is defined.

delegatedPrefixLength

Specifies the default length of the delegated prefix

shortestPrefixLength

Specifies the shortest length of the delegated prefix. CNR only.

longestPrefixLength

Specifies the longest length of the delegated prefix. CNR only.

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.

allowClient
Classes

An array of Client Classes that are allowed in this address pools. Each element of
the array names a different Client Class.

denyClientClasses

An array of Client Classes that are NOT allowed in this address pools. Each array
element names a different Client Class.

Application Program Interfaces (API) 311

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. This service enables the client to filter the list of resource records
retrieved by requesting administrator, domain name/type and the requested action.
Initialization

Before the exportResourceRecordPendingApproval API is called, the web service

client must call initExportResourceRecordPendingApproval to initialize the API.
The portion of Exports.wsdl that describes the
initExportResourceRecordPendingApproval request and response messages is
shown following.
<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.

The query string syntax is defined previously. Supported selectors for exporting device
resource records by device are defined in the following table.
Currently, there are no options defined for this service.
Selector

Description

Exam ple

Domain

Select resource records by domain name.

Domain contains ins.com

Domain Type

Select resource records by domain type.

Domain Type contains Internal

pendingAction

Select resource records based on the

request to create, update or delete
that resource record

pendingAction='create'

Select resource records by the login id of

the administrator requesting the resource
record change.

adminLoginId='someuser'

adminLoginId

pendingAction='delete'
pendingAction=update

Response

The response from the initExportResourceRecordPendingApproval web service is

a WSContext object defined previously. This WSContext object must be included in each
successive call to exportResourceRecordPendingApproval, as described below.

312 IPControl CLI and API Guide

ExportResourceRecordPendingApproval

Service Invocation

The portion of Exports.wsdl that describes the

exportResourceRecordPendingApproval request and response messages is shown

following.
<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. When this context is provided to a
subsequent call to exportResourceRecordPendingApproval, the number of exported
resource records is limited to the first 5000 resource record change requests, or less (see
Paging), 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
exportResourceRecordPendingApproval service to modify the size of the resultant
WSResourceRecPendingApproval object array. However, the value specified by the
client cannot exceed 5000.
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. Because of this and for
performance, 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. It will,
however, always guarantee the number of results to be the max results value or less.
Response

The result returned from the exportResourceRecordPendingApproval service is an

array of WSResourceRecPendingApproval objects matching the selection criteria
specified in the query filter. The workflowId returned in
WSResourceRecPendingApproval can then be used to invoke the
modifyPendingApproval API.
WSResourceRecPendingApproval

The portion of Exports.wsdl that describes WSResourceRecPendingApproval, the array of

structures returned by exportResourceRecordPendingApproval is shown following.
The elements are described in the table that follows.

Application Program Interfaces (API) 313

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.

action

The request update, create or delete

admin

The login id of the requesting administrator

comment

Comment text associated with the resource record.

container

The name of the container that holds the device for this resource record. This is
required only if there is overlapping address space in use and the ip address is in
overlapping space. The container is then used to uniquely determine the device.

data

The data portion of the resource record. The format is dependent on the type
specified above.

dateTime

The date and time of the approval request.

domain

Domain name of resource record.

domainType

Domain type of resource record.

hostname

The device host name.

ipAddress

The IP Address of the Device.

owner

The owner field of the resource record.

resourceRecClass

The Class of the Resource Record. Defaults to IN.

resourceRecordType

The Type of the resource Record.

server

The Time To Live for the record.

view

The name of the view for the domains of this resource record

workflowid

This is required as input to modifyPendingApproval.

zone

The name of the DNS network service as defined in IPControl to import the zone
data into.

314 IPControl CLI and API Guide

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. These updates include those to create, update or delete a resource
record.
Initialization

Before the exportResourceRecordPendingApprovalStatus API is called, the web

service client must call initExportResourceRecordPendingApprovalStatus to
initialize the API. The portion of Exports.wsdl that describes the
initExportResourceRecordPendingApprovalStatus request and response
messages is shown following.
<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. Supported selectors for exporting
device resource records by device are defined in the following table.
Currently, there are no options defined for this service.
Selector

Description

Exam ple

Domain

Select resource records by domain name.

Domain contains ins.com

Domain Type

Select resource records by domain type.

Domain Type contains Internal

pendingAction

Select resource records based on the

request to create, 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. This WSContext object must be included
in each successive call to exportResourceRecordPendingApprovalStatus as
described below.

Application Program Interfaces (API) 315

ExportResourceRecordPendingApprovalStatus

Service Invocation

The portion of Exports.wsdl that describes the

exportResourceRecordPendingApprovalStatus request and response messages is

shown below.
<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. When this context is provided
to a subsequent call to exportResourceRecordPendingApprovalStatus, the number
of exported resource records is limited to the first 5000 resource record change requests, or
less (see Paging), 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
exportResourceRecordPendingApprovalStatus service to modify the size of the
resultant WSResourceRecPendingApproval object array. However, the value specified
by the client cannot exceed 5000.
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. Because of this and for
performance, 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.
It will, however, always guarantee the number of results to be the max results value or less.
Response

The result returned from the exportResourceRecordPendingApprovalStatus

service is an array of WSResourceRecPendingApproval objects matching the selection
criteria specified in the query filter.
WSResourceRecPendingApproval

The portion of Exports.wsdl that describes WSResourceRecPendingApproval, the array of

structures returned by exportResourceRecordPendingApprovalStatus is shown
following. The elements are described in the table that follows.

316 IPControl CLI and API Guide

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.

action

The request update, create or delete

admin

The login id of the requesting administrator

comment

Comment text associated with the resource record.

container

The name of the container that holds the device for this resource record.
This is required only if there is overlapping address space in use and the ip
address is in overlapping space. The container is then used to uniquely
determine the device.

data

The data portion of the resource record. The format is dependent on the
type specified above.

dateTime

The date and time of the approval request.

domain

Domain name of resource record.

domainType

Domain type of resource record.

hostname

The device host name.

ipAddress

The IP Address of the Device.

owner

The owner field of the resource record.

resourceRecClass

The Class of the Resource Record. Defaults to IN.

resourceRecordType

The Type of the resource Record.

server

The Time To Live for the record.

view

The name of the view for the domains of this resource record

workflowid

This is required as input to modifyPendingApproval.

zone

The name of the DNS network service as defined in IPControl to import the
zone data into.

Application Program Interfaces (API) 317

UseNextReservedIPAddress

Updates
This section explains the web services available for updating information in IPControl.
UseNextReservedIPAddress
Overview

The UseNextReservedIPAddress API enables the web service client to mark the next
reserved IP Address in the specified block, for the specified device type, to in-use. The block
must have a status if In Use/Deployed. Within this block, there should be a range of
addresses with a type of Reserved and a status of reserved for the given device type. The
next lowest IP address within the range will be assigned a type of Static and a status of inuse. If a hostname is specified, it will be applied to the device associated with the IP Address.
In addition, there is an option to add resource records for the device.
This service is available as an operation in the IncUseNextReservedIPAddress web
service. 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.wsdl that describes the

UseNextReservedIPAddress request and response messages.
<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.
Request

The complex type WSDevice, which is passed as input from the client to the web service, is
described in the next section.
Parameters
WSDevice

The portion of IncUseNextReservedIPAddress.wsdl that describes WSDevice, the parameter

structure passed to UseNextReservedIPAddress, is shown following. The elements are
described in the table that follows.
<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

<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. Accepted values are
true or false. If not specified,
defaults to false.

No

MACAddress

Not used

deviceType

The device type associated

with the reserved IP address.

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

DeleteAddrPool

Deletes
The Delete APIs allow a client program to delete objects in the system. Each of these services
is available as an operation in the Deletes web service. 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 . By specifying the address pool to be deleted, the web service will validate and delete
the address pool.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteAddrPool request and response
messages is shown following.
<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.

Request

The complex type WSAddrpool, which is passed as input from the client to the web service,
is described in the next section.
Parameters
WSAddrpool

The portion of Deletes.wsdl that describes WSAddrpool, the parameter structure passed to
DeleteAddrPool, is shown following. The elements are described in the table that follows.

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

Startaddr

The start Address of the address pool

to be deleted.

Yes

-117

Address Pool not

found

Container

The container in which the address pool

resides in. This is to disambiguate the
address pool.

Yes

-117

Address Pool not

found

Application Program Interfaces (API) 321

DeleteAggregateBlock

DeleteAggregateBlock
Overview

The DeleteAggregateBlock API enables the web service client to delete an intermediate
level Aggregate block from the block hierarchy. By specifying the block to be deleted, the
web service will validate and delete the block. It will also adjust the parent block assignments
of any child blocks.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteAggregate request and response
messages is shown following.
<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.

Request

The complex type WSBlock4Delete, which is passed as input from the client to the web
service, is described in the next section.
Parameters
WSBlock4Delete

The portion of Deletes.wsdl that describes WSBlock4Delete, the parameter structure passed
to DeleteAggregateBlock, is shown following. The elements are described in the table that
follows.
<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.

Yes

-127

Block start and

parent block

322 IPControl CLI and API Guide

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.g., 24 for a 255.255.255.0 network).

Yes

-15

Block size
invalid: <size>

container

The name of the container from which

to delete the aggregate 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

-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

DeleteBlock

DeleteBlock
Overview

The DeleteBlock API enables the web service client to delete blocks from IPControl.
Request and Response Messages

The portion of Deletes.wsdl that describes the DeleteBlock request and response messages is
shown following.
<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.

Request

The request takes two parameters, block name and container name. Their use is described in
more detail in the next section.
Parameters
Elem ent

Accepted Values

Required

Return
Code

Faultstring

blockName

The name of an existing block. This is

often the address followed by CIDR
size, e.g. 10.0.0.0/8. However, if the
block name was changed during
allocation, then the modified value
should be supplied here.

Yes

-36

Block not found

-97

Block not unique

-98

Parent not found.

-100

Cannot delete
free aggregate.

-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. This is required if overlapping
space is in use and the block overlaps
another in the system.

324 IPControl CLI and API Guide

No, unless
block is
overlappe
d.

DeleteContainer

DeleteContainer
Overview

The DeleteContainer API enables the web service client to delete containers from
IPControl.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteContainer request and response
messages is shown following.
<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.

Request

The request contains a single string parameter, fullName.

Parameters
fullName

This is name of the container. The name can be either qualified or unqualified, but must be
unique. A qualified name must start with the root container and include the complete
container path to the desired container. The container names should be separated by slashes.
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

DeleteDevice

DeleteDevice
Overview

The DeleteDevice API enables the web service client to delete devices from IPControl.
Note that this is not used to delete devices of type Interface. Use the ModifyBlock API to
delete Interface-type devices.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteDevice request and response
messages is shown following.
<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.

Request

The complex type WSDevice, which is passed as input from the client to the web service, is
described in the next section. For consistency, this is the same structure that is passed to
ImportDevice. However, only two of the fields are used.
Parameters
WSDevice

The portion of Deletes.wsdl that describes WSDevice, the parameter structure passed to
DeleteDevice, is shown following. The required elements are described in the table that
follows. The other elements are ignored.
<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

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, if
overlapping
space is in
use and the
device is in
an
overlapped
block.

-28

IP Address
ambiguous

Application Program Interfaces (API) 327

DeleteDeviceInterface

DeleteDeviceInterface
Overview

The DeleteDeviceInterface API enables the web service client to delete device
interfaces from IPControl.
Note that this is not used to delete devices of type Interface. Use the ModifyBlock API to
delete Interface-type devices.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteDeviceInterface request and

response messages is shown following.
<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.

Request

The complex types WSDevice and WSInterface, which are passed as input from the client
to the web service, are described in the next section. For consistency, these are the same
structures that are passed to ImportDevice. However, only three of the fields are used.
Parameters
WSDevice

The portion of Deletes.wsdl that describes WSDevice and WSInterface, the parameter
structures passed to DeleteDeviceInterface, are shown following. The elements are
described in the table that follows.
<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

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.

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

Elem ent

Accepted Values

Required

Return
Code

Faultstring

interfaces

An array of WSInterface
structures. Each element
in the array corresponds to
one interface to be deleted.
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. Use
DeleteDevice.

name: Interface Name

(Required)
The following are ignored:
- addressType
- container
- excludeFromDiscovery
- hwType
- id
- ipAddress
- macAddress
- sequence
- virtual

id

Ignored

No

excludeFrom
Discovery

Ignored

No

330 IPControl CLI and API Guide

DeleteDeviceResourceRecord

DeleteDeviceResourceRecord
Overview

The DeleteDeviceResourceRecord API enables the web service client to delete

resource records from IPControl that are affiliated with a device.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteDeviceResourceRecord request and

response messages is shown following.
<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.

Request

The complex type WSDeviceResourceRec, which is passed as input from the client to the
web service, is described in the next section.
Parameters
WSDeviceResourceRecord

The portion of Deletes.wsdl that describes WSDeviceResourceRec, the parameter structure

passed to DeleteDeviceResourceRecord, is shown following. The elements are
described in the table that follows.
<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

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 is required only if there
is overlapping address space in use and
the ip address is in overlapping space.
The container is then used to uniquely
determine the device.

Only if
ipAddress
in
overlappin
g space

data

The RData portion of the record to

delete. This must match the RData
exactly.

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.

Defaults to Default.

No

-81

Domain type not

found: domainType

hostname

The device host name.

Yes, 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.
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 must match exactly.

Yes, unless
host name
is specified

Yes

resourceRecClass

The Resource Record class. This

defaults to IN

No

resourceRecType

The type of resource record being

deleted

Yes

332 IPControl CLI and API Guide

DeleteDeviceResourceRecord

Other returnCodes and faultstrings

ReturnCode

Faultstring

-2

Exception reading domain, 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

DeleteDomain

DeleteDomain
Overview

The DeleteDomain API enables the web service client to delete domains from IPControl.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteDomain request and response messages
is shown following.
<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.

Request

The complex type WSDomain, which is passed as input from the client to the web service, is
described in the next section.
Parameters
WSDomain

The portion of Deletes.wsdl that describes WSDomain, the parameter structure passed to
DeleteDomain, is shown following. The elements are described in the table that follows.
<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

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.

Yes

Return
Code

Faultstring

-60

Domain not found:

domainType/domain

-95

Cannot delete .
domain from Default
domain type.

-135

Domain required

-232

Cannot delete domain

because it is a parent
domain.

-233
domainType

expire

Domain type name already defined

to IPControl. If not specified, the
Default domain type will be
used.
Ignored

Yes, when not

Default.

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.
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

DeleteDomainResourceRecord

DeleteDomainResourceRecord
Overview

The DeleteDomainResourceRecord API enables the web service client to delete

resource records from IPControl that are affiliated with a domain.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteDomainResourceRecord request and

response messages is shown following.
<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.

Request

The complex type WSDomainResourceRec, which is passed as input from the client to the
web service, is described in the next section.
Parameters
WSDomainResourceRecord

The portion of Deletes.wsdl that describes WSDomainResourceRec, the parameter structure

passed to DeleteDomainResourceRecord, is shown following. The elements are
described in the table that follows.
<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

DeleteDomainResourceRecord

Elem ent

Accepted Values

Required

TTL

Time To Live

No

comment

Ignored

data

The RData portion of the record to

delete. This must match the RData
exactly.

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.

Defaults to Default.
Ignored

No

-81

Domain type not

found: domainType

The owner field of the record to be

deleted. This must match 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

defaults to IN.

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

DeleteNetElement

DeleteNetElement
Overview

The DeleteNetElement API enables the web service client to delete network element from
IPControl.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteNetElement request and response
messages is shown following.
<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.

Request

The complex type WSNetElement , which is passed as input from the client to the web
service, is described in the next section. Only the first two elements are used for this API.
Parameters
WSetElement

The portion of Deletes.wsdl that describes WSNetElement, the parameter structure passed to
DeleteNetElement, is shown following. The elements are described in the table that
follows.
<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

DeleteNetElement

</sequence>
</complexType

Elem ent

Accepted Values

Required

Return
Code

Faultstring

name

The name of the Network Element.

This can be any combination of letters
and numbers.

Yes,
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,
unless the
name is
specified

-33

Network element
not found by ip
address: addr

-28

Specify network
element name,
not unique by ip
address: addr

ipAddress

The IP address or fully-qualified

domain name (FQDN) of the Network
Element. This must be a valid IPv4 or
IPv6 IP address, or a full-qualified host
name.

Other returnCodes and faultstrings

ReturnCode

Faultstring

-2

Exception reading network element record (database error)

401

<401>Unauthorized

Application Program Interfaces (API) 339

DeleteNetElementInterface

DeleteNetElementInterface
Overview

The DeleteNetElementInterface API enables the web service client to delete network
element interfaces from IPControl.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteNetElementInterface request and

response messages is shown following.
<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.

Request

The complex type WSNetElementInterface , which is passed as input from the client to
the web service, is described below. For consistency, this is the same structure that is passed
to ImportNetElementInterface. However, only two of the fields are used.
Parameters
WSNetElementInterface

The portion of Deletes.wsdl that describes WSNetElementInterface, the parameter

structure passed to DeleteNetElementInterface, is shown following. The elements are
described in the table that follows.
<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

DeleteNetElementInterface

Elem ent

Accepted Values

Required

id

The internal identifier for this network

element interface object. If this is not
set, a new interface is created. If this is
set, the interface with the matching
identifier is updated.

No

interfaceName

The name of the interface being added

or modified.

Yes

netElementName

status

The name of a Network Element

already defined to IPControl.

The status of the interface. This can be

one of Disabled, Enabled, or
Deployed. The default on an import
is Enabled.

Yes

No

Return
Code

Faultstring

-39

Cannot delete
interface: interface
for network
element: name
because there are
blocks attached.

-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

DeleteNetService

DeleteNetService
Overview

The DeleteNetService API enables the web service client to delete network service from
IPControl.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteNetService request and response
messages is shown following.
<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.

Request

The complex type WSNetService, which is passed as input from the client to the web
service, is described below. Only the first two elements are used for this API.
Parameters
WSNetService

The portion of Deletes.wsdl that describes WSNetService, the parameter structure passed to
DeleteNetService, is shown following. The elements are described in the table that
follows.
<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

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. If this

column is left blank, 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

DeletePrefixPool

DeletePrefixPool
Overview

The DeletePrefixPool API enables the web service client to delete Prefix Pools from
IPControl. This will also delete the Delegated Prefixes inside the Prefix Pool.
Request and Response Messages

The portion of Deletes.wsdl that describes the DeletePrefixPool request and response
messages is shown following.
<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.

Request

The complex types WSPrefixPool, which are passed as input from the client to the web
service, are described in the next section. For consistency, these are the same structures that
are passed to ImportPrefixPool. However, only two of the fields are used.
Parameters
WSPrefixPool

The portion of Deletes.wsdl that describes WSPrefixPool, the parameter structure passed to
DeletePrefixPool, is shown following. 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>
344 IPControl CLI and API Guide

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

DeleteTaskByDate

DeleteTaskByDate
Overview

The DeleteTaskByDate API enables the web service client to delete tasks from IPControl
that are older than a given date.
Request and Response Messages

The portion of Deletes.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. Any tasks older than this date are deleted.
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

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.
<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.

Request

The request takes one parameter which is the number of days of tasks to retain. Any task s
older than the current date minus this parameter are deleted.
Parameters
Elem ent

Accepted Values

Required

Return
Code

Faultstring

Days

A positive integer.

Yes

-109

Invalid Days
value

Application Program Interfaces (API) 347

DeleteTaskById

DeleteTaskById
Overview

The DeleteTaskByID API enables the web service client to delete one or more tasks from
IPControl.
Request and Response Messages

The portion of Deletes.wsdl that describes the DeleteTaskById request and response
messages is shown following.
<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 an array of integers. Each integer is a Task ID.
Parameters
Elem ent

Accepted Values

Required

Return
Code

Faultstring

ids

The Task IDs to delete, one per

element in the array.

Yes

-106

Task Not found

-108

Missing IDs

348 IPControl CLI and API Guide

DeleteZone

DeleteZone
Overview

The DeleteZone API enables the web service client to delete zones from IPControl.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteZone request and response messages is
shown following.
<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.

Request

The complex type WSDnsZone, which is passed as input from the client to the web service, is
described in the next section.
Parameters
WSDnsZone

The portion of Deletes.wsdl that describes WSDnsZone, the parameter structure passed to
DeleteZone, is shown following. The elements are described in the table that follows.
<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

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.

Yes

domainType

Domain type of the domain for

the zone. If not specified, the
Default domain type will be
used.

dynamicZone

Ignored

Yes, when not

Default.

Ignored

No

galaxyName

Ignored

No

masters

Ignored

No

server

The network service name of the

DNS Server for the zone.

Yes

templateZone

Ignored

No

updatePolicy

Ignored

No

updateZone

Ignored

No

zoneExtensionsAfter

The name of the view in which

the zone exists. If not specified,
Default will be used.

Faultstring

-135

Domain required

-60

Domain not found:

domainType/domain

-81

Domain type not

found: domainType

No

filename

view

Return
Code

Yes, when not

Default.
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 - 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

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.
Request and Response Messages

The portion of Deletes.wsdl that describes the deleteZoneResourceRecord request and

response messages is shown following.
<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.

Request

The complex type WSZoneResourceRec, which is passed as input from the client to the
web service, is described below.
Parameters
WSResourceRecord

The portion of Deletes.wsdl that describes WSZoneResourceRec, the parameter structure

passed to DeleteZoneResourceRecord, is shown following. The elements are described
in the table that follows.
<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

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 the RData
exactly.

Yes

-91

Data field
required

Owner

The owner field of the record to be

deleted. This must match exactly.

Yes

-89

Owner field
required

resourceRecClass

The Resource Record class. This

defaults to IN.

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. Defaults to Default.

No

zone

The Name of the zone in which the

resource record exists.

Yes

352 IPControl CLI and API Guide

-88

Zone not found.

Other Interfaces

Callout Manager
The Callout Manager is a facility within IPControl that notifies other applications of alerts
and programmatic events. 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. The file is
written as XML, or as name-value pairs, as dictated by the configuration (see
below).

Execute the script that is configured for this event, passing it the name of the
temporary file.
When the message queue is empty, the callout manager simply waits.
Note that the callout manager does not wait for the user script to complete. Hence, the
user script must delete the temporary file passed to it.
When building your scripts, if you do not specify fully qualify output paths, then your
defined output would be written to C:\Program Files\Diamond
IP\InControl\etc on Windows, or /opt/incontrol/etc on Solaris or Linux.
Assuming that path is where you installed InControl. For example, if your script had
[echo hello world > output.txt], rather than [echo hello world >
/opt/incontrol/tmp/out.txt], then the output.txt file would be found under
/opt/incontrol/etc.
Configuration
The Callout Manager is configured through a text file known as a properties file. The
Callout Managers properties file can be found in $INCHOME/callout_manager.properties.
The properties file contains directives that control the Callout Manager behavior. Any
Other Interfaces 353

Other Interfaces

changes made to this file require that the Callout Manager service be restarted for the
changes to take effect.
The following table lists those properties. Locate the property or properties within
callout_manager.properties that you want to use and uncomment it (remove the # in front of
the line), and specify a custom path and script name. For example:
block.add = /opt/scripts/blockadd_callout.sh
Property

Required

Description

log.config.filename

Yes

Specifies the name of the file that holds

the logging directives.

queue.connections.names

Yes

Specifies the JMS Queue Name. This

should not be changed from its shipped
value.

queue.connections.callout.factory.name

Yes

Specifies the Java class that manages the

Queue creation. Should not be changed
from its shipped value

queue.connections.callout.thread.count

Yes

Specifies the number of threads for

receiving callout messages. Should not be
changed from its shipped value.

queue.connections.callout.reconnect.retry

Yes

Specifies the reconnection retry count if

the Callout manager is disconnected from
JMS. Should not be changed from its
shipped value.

queue.connections.callout.reconnect.delay

Yes

Specifies the retry interval should the

Callout Manager be disconnected from
JMS. Should not be changed from its
shipped value.

output.path

No

Specifies the directory where the

temporary files will be created for the
events. Defaults to $INCHOME/tmp. If
specified, the string must end with a path
separator.

output.xml

No

Specifies the format of the temporary file.

If false (default), the file contains
name=value pairs. If true, the file
contains XML.

alertcallout

No

The name of the command to execute

when an alert is raised. For example, on
Windows, an example of the property
value would be c:\\Program
Files\\Diamond
IP\\InControl\\bin\\alertcallout.bat. On
Solaris or Linux, an example of the
property value would be
/opt/incontrol/bin/alertcallout.sh.

354 IPControl CLI and API Guide

Other Interfaces

Property

Required

Description

block.add

No

The name of the command to execute

when a block is added to IPControl. For
example, on Windows, an example of the
property value would be c:\\Program
Files\\Diamond IP\\InControl\\bin\\
blockadd_callout.bat. On Solaris or Linux,
an example of the property value would
be
/opt/incontrol/bin/blockadd_callout.sh.

block.modify

No

The name of the command to execute

when a block is modified within
IPControl. For example, on Windows, an
example of the property value would be
c:\\Program Files\\Diamond
IP\\InControl\\bin\\
blockmodify_callout.bat. On Solaris or
Linux, an example of the property value
would be
/opt/incontrol/bin/blockmodify_callout.
sh.

block.delete

No

The name of the command to execute

when a block is deleted within IPControl.
For example, on Windows, an example of
the property value would be c:\\Program
Files\\Diamond IP\\InControl\\bin\\
blockdelete_callout.bat. On Solaris or
Linux, an example of the property value
would be
/opt/incontrol/bin/blockdelete_callout.s
h

device.add

No

The name of the command to execute

when a device is added within the
IPControl GUI. For example, on
Windows, an example of the property
value would be c:\\Program
Files\\Diamond IP\\InControl\\bin\\
deviceadd_callout.bat. On Solaris or
Linux, an example of the property value
would be
/opt/incontrol/bin/deviceadd_callout.sh

device.modify

No

The name of the command to execute

when a device is modified within the
IPControl GUI. For example, on
Windows, an example of the property
value would be c:\\Program
Files\\Diamond IP\\InControl\\bin\\
devicemodify_callout.bat. On Solaris or
Linux, an example of the property value
would be
/opt/incontrol/bin/devicemodify_callout
.sh

Other Interfaces 355

Other Interfaces

Property

Required

Description

device.delete

No

The name of the command to execute

when a device is deleted within the
IPControl GUI. For example, on
Windows, an example of the property
value would be c:\\Program
Files\\Diamond IP\\InControl\\bin\\
devicedelete_callout.bat. On Solaris or
Linux, an example of the property value
would be
/opt/incontrol/bin/devicedelete_callout.s
h

task.complete

No

The name of the command to execute

when a task is launched with the
IPControl GUI. For example, on
Windows, an example of the property
value would be c:\\Program
Files\\Diamond
IP\\InControl\\bin\\taskcomplete_out.
bat. On Solaris or Linux, an example of
the property value would be
/opt/incontrol/bin/taskcomplete_callout.
sh

Appliance Events
The Sapphire Appliance logs several event messages to the IPControl database. The types
of events which are logged include starting and stopping of services and changes in state
of any monitored service. Specifically, the events included are those that are listed on the
Details screen from the Appliance Dashboard. As each event is logged to the database, a
message containing the details of the event is sent to the Callout Manager. This allows the
administrator to provide scripts which send a notification to the appropriate party when
certain appliance events warrant it. Scripts are configured in the Callout Managers
properties file, as indicated above. The property name that identifies the event is of the
form source.category.message. For example, if an administrator were to stop the
DNS server on a Sapphire Appliance through the Manage link of the Appliance
Dashboard, two events would be logged:

dnsserver.action.stopped

dnsserver.status.down

The first event identifies the action performed by the administrator, whereas the second
event identifies the state of the DNS server as determined by the IPControl monitoring
software. The administrator can choose to provide a script for one or both events, as
needed. Configuring the script is performed as indicated above, by providing the property
name and callout script name-value pair in the $INCHOME/callout_manager.properties file.
A script can be configured for each individual event message, or at the category or source
level, as desired. For example:
dnsserver.action.stopped = /opt/incontrol/bin/dnsstoppped_callout.sh
dnsserver.status.down = /opt/incontrol/bin/dnsdown_callout.sh

356 IPControl CLI and API Guide

Other Interfaces

This configuration provides individual scripts for specific event messages. Alternatively,
the scripts could be configured at the category level of the event. For example:
dnsserver.action = /opt/incontrol/bin/dnsaction_callout.sh
dnsserver.status = /opt/incontrol/bin/dnsstatus_callout.sh

In this case, all action events (stopped, started) would be handled by the
dnsaction_callout.sh script, and all status events (down, running) would be
handled by the dnsstatus_callout.sh script.
Finally, the script mapping can be provided at the highest level of the event, the source.
For example:
dnsserver = /opt/incontrol/bin/dnsev ent_callout.sh

In this case, all DNS server events would be handled by the dnsevent_callout.sh
script. This includes all action (stopped, started) and status (down, running) events. The
contents of the XML or name-value pair file that is passed to the script contains the
details, which include the source, category, and message, to allow the script to provide its
own conditional processing based on the particular event.
Please refer to section 5.11.1 - Appliance Details in the IPControl User Guide for a
complete, detailed list of all appliance events.

Other Interfaces 357

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. This includes
templates for ARIN and RIPE. This support is provided via sample scripts that can be
called via the IPControl Callout Manager. The scripts include the ability to automatically
send an email with the appropriate content to the RIR.
For further details about RIR templates, visit the ARIN and/or RIPE websites at
http://www.arin.net or http://www.ripe.net.
Configuration
ARIN File Generation

IPControl provides a set of sample scripts that can be used, via the Callout Manager, to
generate the proper ARIN Reassign - Simple template, commonly referred to as a SWIP
(Shared WhoIs Project) template. The Callout Manager can be configured to call these
scripts on each Add, Delete, or Modify of a block within IPControl. To configure the
callout manager to call the SWIP scripts on these events, modify the following properties
in the $INCHOME/callout_manager.properties file. (The examples assume that $INCHOME
= /opt/nc.)
block.add = /opt/nc/etc/callout/addSwip.pl
block.modify = /opt/nc/etc/callout/modifySwip.pl
block.delete = /opt/nc/etc/callout/deleteSwip.pl

The scripts can be configured with default information to be used when generating the
data files. The default properties are stored in a properties file called
$INCHOME/etc/callout/swip.properties. The following table lists those properties.
Property

Required

Description

from_address

Yes

The email address of the sender of the template email.

to_address

Yes

The email address of the recipient of the email address. Typically, this
should be [email protected].

subject

No

The subject of the email. For a Reassign Simple template, this should be
REASSIGN SIMPLE

customer_name

No

Specifies the default name of the customer to which the block has been
reassigned.

customer_address

No

Specifies the default street address for the customer being assigned this
block.

customer_city

No

Specifies the default city for the customer being assigned this block.

customer_state

No

Specifies the default state for the customer being assigned this block.

customer_postal_code

No

Specifies the default postal code for the customer being assigned this block.

customer_country_code

No

Specifies the default country code for the customer being assigned this
block.

358 IPControl CLI and API Guide

Other Interfaces

RIPE File Generation

IPControl provides a set of sample scripts that can be used, via the Callout Manager, to
generate the proper RIPE inetnum or inet6num templates. These templates are used to
update the RIPE database directly via email. The Callout Manager can be configured to
call these scripts on each Add, Delete, or Modify of a block within IPControl. To
configure the callout manager to call the RIPE scripts on these events, modify the
following properties in the $INCHOME/callout_manager.properties file. (The examples
assume that $INCHOME = /opt/nc.)
block.add = /opt/nc/etc/callout/addRipe.pl
block.modify = /opt/nc/etc/callout/modifyRipe.pl
block.delete = /opt/nc/etc/callout/deleteRipe.pl

The scripts can be configured with default information to be used when generating the
data files. The default properties are stored in a properties file called
$INCHOME/etc/callout/ripe.properties. The following table lists those properties.
Property
from_address

Required
Yes

Description
The email address of the sender of the template email.

to_address

Yes

The email address of the recipient of the email address. Typically, this should
be [email protected].

orgname

No

Specifies the text that will appear in the descr field of the in inetnum (or
inet6num) templates. Typically this is the name of the organization that will
use the address space.

adminc

No

Specifies the email address of the administrative contact for this address space.
This corresponds to the admin-c field in the inetnum (or inet6num)
template.

techc

No

Specifies the email address of the technical contact for this address space. This
corresponds to the tech-c field in the inetnum (or inet6num) template.

revsrv

No

Specifies the reverse server address for this address space. This corresponds to
the rev-srv field in the inetnum (or inet6num) template.

notify

No

Specifies the email address of the RIPE contact for this address space. This
corresponds to the notify field in the inetnum (or inet6num) template.

status

No

Specifies the default values of the status field in the inetnum or inet6num
templates.
All inetnum objects under APNIC Whois Database must have a status
attribute. 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. The status attribute must be one of the following values:
ALLOCATED PORTABLE
ALLOCATED NON-PORTABLE
ASSIGNED PORTABLE
ASSIGNED NON-PORTABLE

Other Interfaces 359

Other Interfaces

Property
mntby

Required

Description
The default value to use as the identifier of a registered mntner object used for
authorization and authentication.

mntlower

Sometimes there is a hierarchy of maintainers. In these cases, mnt-lower is used

as well as mnt-by. This field specifies the default value to use.

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.

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.

remarks

General remarks. May include a URL or instructions on where to send abuse

complaints.

changed

The email address of who last updated the database object and the date it
occurred.
The changed attribute is not a network contact address, as it merely records
who made the most recent change to the registration information. All RIPE
addresses will initially record an RIPE address in this attribute, as RIPE creates
the first database object.

source

The name of the database from which the data was obtained. This is either
RIPE or a designation for the NIR, LIR or ISP that allocates/assigns the
address.

password

The default password to use if the either the CRYPT-PW or MD5

authentication is used with the mntner object.

delete_reason

The default text to use when deleting an address space. This will be placed in
the Delete: field, if a delete has taken place.

Operation
ARIN File Generation Scripts

In order to support the automatic file generation of ARIN SWIP templates and emails,
there are three scripts that can get called by the Callout Manager when a block is added,
modified, or deleted and they are addSwip.pl, modifySwip.pl, and deleteSwip.pl. (For
information on configuring the Callout Manager to perform these tasks please see the
section above called Configuration ARIN File Generation.)
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. PERL 5 is NOT
supplied with IPControl. Although fully functional, the scripts are provided as examples.
The ARIN scripts all operate in a similar fashion. They accept as their first argument a
filename. This filename should point to a file that contains block information formatted
as name-value pairs. The scripts parse this file to pull out any required data and decide
whether or not to proceed with the template processing. The key decision point is the
presence of a property called swipname in the data file. If the property is present and is
non-empty, then the scripts will proceed with creating a Reassign-Simple template for
adding, modifying, or deleting an address space. After creating the template, it will attempt
to send an email to the address specified in the to_address field, as defined in the
swip.properties file.
360 IPControl CLI and API Guide

Other Interfaces

Note: All scripts delete the data file before exiting.

Expected User Defined Field Mappings

The SWIP Perl scripts expect to make use of both standard and User Defined Fields. The
following table shows a mapping of the fields used by the scripts and their relation to the
standard and User Defined Fields.
NC Tags

SWIP Field

UDF

startaddrstring / blocksize

IP Address and Prefix

swipname

Network-Name

org_name

Customer Name

street_address

Customer Address

city

Customer City

state

Customer State

postal_code

Customer Postal Code

country_code

Customer Country Code

public_comments

Public Comments

RIPE File Generation Scripts

In order to support the automatic file generation of RIPE inetnum or inet6num templates
and emails, there are three scripts that can get called by the Callout Manager when a block
is added, modified, or deleted and they are addRipe.pl, modifyRipe.pl, and deleteRipe.pl.
(For information on configuring the Callout Manager to perform these tasks please see the
section above called Configuration RIPE File Generation.)
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. PERL 5 is NOT
supplied with IPControl. Although fully functional, the scripts are provided as examples.
The RIPE scripts all operate in a similar fashion. They accept as their first argument a
filename. This filename should point to a file that contains block information formatted
as name-value pairs. The scripts parse this file to pull out any required data and decide
whether or not to proceed with the template processing. The key decision point is the
presence of a property called swipname in the data file. If the property is present and
is non-empty, then the scripts will proceed with creating an inetnum or inet6num template
for adding, modifying, or deleting an address space. After creating the template, it will
attempt to send an email to the address specified in the toaddress field, as defined in
the ripe.properties file.
Note: All scripts delete the data file before exiting.
Expected User Defined Field Mappings

The RIPE Perl scripts expect to make use of both standard and User Defined Fields. The
following table shows a mapping of the fields used by the scripts and their relation to the
standard and User Defined Fields.

Other Interfaces 361

Other Interfaces

NC Tags

RIPE Field

UDF

startaddrstring - endaddrstring

inetnum (or inet6num)

swipname

netname

orgname

descr

country_code

country

admin_contact

admin-c

tech_contact

tech-c

rev_srv

rev-srv

status

status

remarks

remarks

notify

notify

mntby

mnt-by

mntlower

mnt-lower

mntroutes

mnt-routes

changed

changed

source

source

362 IPControl CLI and API Guide

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.
The DNS Listener process imports DNS resource records collected via an incremental
zone transfer (IXFR) from a DNS server into IPControl. It does this by sequentially
reading each resource record contained in an IXFR, processing each one according to a set
of rules described below, and then inserting some portion of the resulting data into
IPControl. Resource records are processed using rules specific to each resource records
Type field. The type-specific rules are listed in detail further down in this appendix.
Usage
Starting the DNSListener on Unix
$INCHOME/etc/dl_start [-c <listener.properties>]

Stopping the DNSListener on Unix

$INCHOME/etc/dl_stop

Starting or Stopping DNSListener via Windows GUI

Follow these steps.

1. Click on Start -> Control Panel -> Administrative Tools.
2. Double-click on Administrative Tools.
3. Double-click on Services.
4. Scroll down to InControl DNS Listener.
5. Right-click on InControl DNS Listener.
6. Choose which status you want, either Start or Stop.
Configuration
Configure the DNS Listener

Make sure the listener is not running by using the appropriate stop command (see
Usage above).
2. The Listener listens on port 5053 by default. If you require it to listen on another
port, edit the dns_listener.properties file.
1.

Note: For the Listener to listen on a port numbered from 1-1023 on UNIX, you must run
the Listener as root so that the process can access privileged ports.
3.

Start the DNS Listener by using the appropriate start command (see Usage
above).

Other Interfaces 363

Other Interfaces

Configure DNS
BIND 8.0 or newer

In the BIND configuration file, usually /etc/named.conf, add the also-notify option to
the zones that you want IPControl to stay synchronized with. For example, the alsonotify option in this file would cause bind to send notify messages to the address
192.168.0.1 on port 5053 when it updates zones example.com. and 0.168.192.inaddr.arpa.:
Options {
directory /var/lib/named;
notify no;
};
zone example.com. {
type master;
file db.example;
also-notify { 192.168.0.1 port 5053; };
};
zone 0.168.192.in-addr.arpa. {
type master;
file db.0.168.192;
also-notify { 192.168.0.1 port 5053; };
};

Microsoft DNS Server

Follow these steps.

1. Start the Microsoft DNS Server application: Control Panel->Administrative
Tools->DNS
2. Click the plus symbol '+', next to the machine icon to open the zones that server is
responsible for.
3. Open the Forward Lookup Zones or Reverse Lookup Zones.
4. Right click on the name of the zone that you want to keep synchronized in
IPControl and select Properties from the menu.

364 IPControl CLI and API Guide

Other Interfaces

4. Click on the Zone Transfers tab and then click the Notify... button.

5. Select The following servers from the radio button group.

6. Add the IP address of the DNS Listener, and any other DNS servers that you
want notified when zones are updated.
7. Click OK.
Note: Microsoft DNS can only send Notify messages on port 53, so the Listener will
need to be configured to listen on port 53 by editing the dns_listener.properties file.

Other Interfaces 365

Other Interfaces

Record Processing Rules

RR Type

Description

SOA

Data from the SOA record is used to update a domain in IPControl. The domain name is taken from
the name field of the resource record. If the domain does not exist in IPControl processing for that
record stops. If the domain exists in IPControl, data from the imported record is used to update the
serial number of the domain.

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. Note that:

if a domain name that matches the zone name is not defined in IPControl then processing of the
resource record stops.

if the name field contains the zone name, with additional fields to the left of the domain name
then an IP address and device will be created.

if the name field matches exactly the zone name then no IP address and device will be created.

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.

if the address found in the rdata field of the resource record can be located within a block
defined in IPControl, an IP address will be created using the rdata field, and a device will be
created using the name field. The device and IP address will also be associated with the resource
record in addition to the domain.

if no block is defined that contains the address then the address device pair will not 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, the host name will be taken from the name field of the
resource 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.

NS

NS records are ignored by the DNS Listener daemon.

MX

MX records are imported into IPControl and attached to the domain supplied in the name field.

SRV

The data from SRV records are processed in the same way as other resource records with the
exception of the name field. The name field of SRV records specifies a service available for the
domain for which it is a part of. The service type and protocol is encoded in the left portion of its
name field. To avoid collision with the rest of the domain name space, leading under-bars are
prepended to the labels that describe the service. 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. 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.
For example in the following SRV record:
_ldap._tcp.pdc._msdcs.sw.ins.com. 600 SRV 0 100 400 pdc.sw.ins.com.

The service specification part w ould be: _ldap._tcp.pdc._msdcs

and the domain name part would be: sw.ins.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. If the domain can not be found in IPControl
processing of the resource record will stop. If the domain is found in IPControl, a resource record
object is created using the data supplied by the imported record, and it is linked to the domain.

366 IPControl CLI and API Guide

Other Interfaces

Detailed Description
The DNS Listener is a small multi-threaded program that listens for messages from DNS
servers. 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. In this way IPControl is kept synchronized with the DNS as hosts join
and leave the network.
The listener is composed of three long lived threads, one queue, and a short lived thread.
See Figure 1. The notify thread is responsible for listening for notify messages from DNS
servers. When changes are made to the affected zones the DNS server will send a
NOTIFY message to the listener. Notify messages sent by DNS servers are sent to port
53 by default, which is a privileged port on most UNIX systems. For this reason the DNS
Listener defaults to port 5053. Both the port the server sends to and the port the listener
listens on can be changed as described below.
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 the number of notify messages exceeds the listener.notifythreshold property, and
the transfer manager is not in the paused state, the transfer manager thread will create and
start a transfer thread. The transfer thread will request an IXFR from the appropriate
DNS server, place the resulting resource records on the queue, and then exit.
The resource record input manager thread is notified when records are placed on the
queue. When this happens the input manager compares the number of records on the
queue with the listener.maxrecords property. If there are more records than the
listener.maxrecords specifies, the input manager thread will send a pause message to t he
transfer manager thread. When the transfer manager is in the pause state it will continue
to process notify messages from the notify thread, but will not start any new transfer
threads. The input thread will then sequentially remove the resource records from the
queue and process them as described above. When the number of records remaining on
the queue is less than the listener.maxrecords, a restart message will be sent to the transfer
manager.

Other Interfaces 367

Other Interfaces

Figure 1 DNS Listener

The DNS Listener can use a properties file to set certain operational properties. The
properties are:
listener.port
The port on which the listener should listen for NOTIFY
messages from a DNS server. The default is 5053 if this
property is not supplied.
Note: For the listener to listen on port 53 on *NIX, you
must run dl_start as root.
listener.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 one NOTIFY message.

Other Interfaces

listener.maxrecords

High water mark that controls NOTIFY message

processing. If more than listener.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. This helps
limit the amount of memory the listener can claim at any
one time. 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. The details of this script are as follows:

The script is called by the remote agent, that is, the one that resides on the actual
DNS server.

The name of the script is not configurable. It is always

$INCHOME/etc/dns_callout.sh (or %INCHOME%\etc\dns_callout.cmd for
Windows).

The script gets called just before we attempt to Restart the server (on a DNS
Config - All Files push) or call rndc (for Selected/Changed Zone Filebased pushes).

The script gets passed one parameter which is the full path name of the new
named.conf file.

The agent will wait for the completion of script before moving on, but only for at
most 60 seconds.

The agent will report the return code of the script in the task result messages,
however it does not interrogate this return value and thus will always continue
even if the script fails.

369

Appendix A API Changes

IPControl 6.0
WSAddrpool

One element was added to WSAddrpool, the parameter structure

passed to importAddrpool:
<element name="prefixLength" nillable="true" type="soapenc:string"/>

In addition, the sharename element has been marked for

deprecation and will be ignored beginning with IPControl 6.0.
Refer to the importAddrpool section of the API chapter for more
detailed information.
WSAllocationTemplateDetails

The sharename element of WSAllocationTemplateDetails has

been marked for deprecation and will be ignored beginning with
IPControl 6.0.
This affects the AddSite and ModifyBlock APIs.
WSAggregateBlock

The interfaceAddress element of WSAggregateBlock has

been marked for deprecation and will be ignored beginning with
IPControl 6.0.
This affects the ImportAggregateBlock API. This field was
always ignored by the DeleteAggregateBlock API.

370 IPControl CLI and API Guide

Appendix A

WSChildBlock

One element, primarySubnet, was added to WSChildBlock.

One element, interfaceAddress, 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. This structure is used by the
ImportChildBlock, ExportChildBlock and DetachBlockAPIs.
WSContainer

One additional element, replaceDHCPServerV6, was added

to WSContainer.
<element name="replaceDHCPServerV6" nillable="true" type="soapenc:string"/>

Additional details are described in the ImportContainer API section. This will
affect the ModifyContainer CLI as well as the ImportContainer and
ExportContainer APIs.
WSDevice

One element was added to WSDevice, the parameter structure

passed to importDevice, 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.
Note that devices with only the default interface will export the
following fields in the WSInterface structure: MACAddress,
hwtype, ipAddress and excludeFromDiscovery.
These fields will no longer be exported as part of the WSDevice
structure. Please refer to the exportDevice section of the API
chapter for more detailed information.

Appendix A

API Changes 371

Other Interfaces

WSDhcpServer

One element was added to WSDhcpServer, 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 affects the ImportDhcpServer,
ModifyDhcpServer and GetDhcpServer APIs.
WSDnsZone

Two elements were added to WSDnsZone, 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 structure is also used by the deleteZone
API.
WSGenericBlock

One element was added to WSGenericBlock:

<element name="primarySubnet" type="xsd:boolean"/>

Refer to the ModifyBlock API section for more detailed

information. This affects the ModifyBlock and GetBlock APIs.
WSInterface

Two elements were added to WSInterface, the parameter structure

passed to importDevice, 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.
WSPrefixPool

This is a new structure described in the ImportPrefixPool

section of the API chapter.

372 IPControl CLI and API Guide

Appendix A

WSSubnetPolicy

One element was added to WSSubnetPolicy:

<element name="networkLinks" nillable="true" type="soapenc:string"/>

This affects the ImportChildBlock, ExportChildBlock,

GetBlock and ModifyBlock APIs. This element is reserved for
future implementation.

ImportNetService

This ImportNetService API and CLI have been deprecated as of IPControl 6.0. Use the
ImportDhcpServer API and CLI instead. ImportNetService support will be removed in a
future release.

Appendix A

API Changes 373