TeemIp provides its own set of WEB services through the REST/JSON interface available by default in iTop. These services enable a remote application to automatize basic IP management tasks:

• get the number of registered IPs in subnets and their status
• automatically create an IP in a subnet
• automatically create an IP in an IP range
• automatically create a subnet in an IP block
• get a DNS zone db file

The additional operations provided by TeemIp can be listed with the standard list_operations command that is already available in iTop.

As a reminder, the syntax of the json_data input is:

{
   "operation": "list_operations"
}

The reply will look like:

Array
(
    [version] => 1.3
    [operations] => Array
        (
            [0] => Array
                (
                    [verb] => core/create
                    [description] => Create an object
                    [extension] => CoreServices
                )
                
            [...] Other iTop core services
                        
            [7] => Array
                (
                    [verb] => teemip/get_webservices_version
                    [description] => Provides the WEB services version currently in use
                    [extension] => TeemIpServices
                )

            [8] => Array
                (
                    [verb] => teemip/get_nb_of_registered_ips_in_subnet
                    [description] => Get the number of registered IPs in subnet(s)
                    [extension] => TeemIpServices
                )

            [9] => Array
                (
                    [verb] => teemip/pick_ip_address_in_subnet
                    [description] => Automatically pick and register an IPv4 or IPv6 address in a given subnet
                    [extension] => TeemIpServices
                )

            [10] => Array
                (
                    [verb] => teemip/pick_ip_address_in_range
                    [description] => Automatically pick and register an IPv4 or IPv6 address in a given IP range
                    [extension] => TeemIpServices
                )

            [11] => Array
                (
                    [verb] => teemip/pick_subnet_in_block
                    [description] => Automatically pick and register an IPv4 or IPv6 subnet in a given IP block
                    [extension] => TeemIpServices
                )

            [12] => Array
                (
                    [verb] => teemip/get_zone_file
                    [description] => Generate and provide the text file that describes the specified DNS zones
                    [extension] => TeemIpServices
                )

        )

    [code] => 0
    [message] => Operations: 12
)

Provides the version of TeemIp specific services currently in use.

Passing the following json_data:

{
   'operation': 'teemip/get_webservices_version',
}

… the reply will look like:

Array
(
    [code] => 0
    [message] => TeemIp WEB Services version running is: 1.1
)

Get the number of registered IPs in one subnet or in a list of subnets. Answer will contain the following details, for each of the requested subnets:

• Attributes
  • Organization name
  • Subnet Name
  • Subnet IP address
  • Mask
• Subnet size
• Number of IPs
  • Allocated
  • Released
  • Reserved
  • Unassigned
  • Totaly registered
  • Free

Example 1

Passing the following json_data:

{
	'operation' => 'teemip/get_nb_of_registered_ips_in_subnet',
	'class' => 'IPv4Subnet',
	'key' => array(
		'org_id' => 3,
		'ip' => '10.129.2.0',
	),
	'fields' => array(
	),
	'comment' => '',
}

… will provide the reply:

Array
(
    [objects] => Array
        (
            [IPv4Subnet::6] => Array
                (
                    [code] => 0
                    [message] => computed
                    [class] => IPv4Subnet
                    [key] => 6
                    [fields] => Array
                        (
                            [org_name] => Demo
                            [name] => HQ-VLAN50
                            [ip] => 10.129.2.0
                            [mask] => 255.255.254.0
                        )
                    [subnet_size] => 512
                    [nb_of_ips] => Array
                        (
                            [allocated] => 4
                            [released] => 0
                            [reserved] => 2
                            [unassigned] => 12
                            [total registered] => 18
                            [free ips] => 492
                        )
                )
        )
    [code] => 0
    [message] => Found: 1
)

Example 2

Other forms of “key” may be used, like:

{
	'operation' => 'teemip/get_nb_of_registered_ips_in_subnet',
	'class' => 'IPv4Subnet',
	'key' => "SELECT IPSubnet WHERE org_id = 3",
	'fields' => array(
	),
	'comment' => '',
}

… answer may be, then, much longer:

Array
(
    [objects] => Array
        (
            [IPv4Subnet::5] => Array
                (
                    [code] => 0
                    [message] => computed
                    [class] => IPv4Subnet
                    [key] => 5
                    [fields] => Array
                        (
                            [org_name] => Demo
                            [name] => GRE-VLAN50
                            [ip] => 10.128.0.0
                            [mask] => 255.255.254.0
                        )
                    [subnet_size] => 512
                    [nb_of_ips] => Array
                        (
                            [allocated] => 0
                            [released] => 0
                            [reserved] => 0
                            [unassigned] => 0
                            [total registered] => 0
                            [free ips] => 510
                        )
                )

            ... other subnets ...
            
            [IPv6Subnet::19] => Array
                (
                    [code] => 0
                    [message] => computed
                    [class] => IPv6Subnet
                    [key] => 19
                    [fields] => Array
                        (
                            [org_name] => Demo
                            [name] => 
                            [ip] => fc01:0:1964:aff::
                            [mask] => 64
                        )
                    [subnet_size] => 1.844674407371E+19
                    [nb_of_ips] => Array
                        (
                            [allocated] => 0
                            [released] => 0
                            [reserved] => 0
                            [unassigned] => 0
                            [total registered] => 0
                            [free ips] => 1.844674407371E+19
                        )
                )
        )
    [code] => 0
    [message] => Found: 7
)

TeemIp specific error messages may be:

• The current user does not have enough permissions for reading data of class <class specified in the request>
• IP addresses cannot be counted within an object of class <class specified in the request> if target class is not a subnet class.

Pick and register an available IP in a given subnet. The first available IP will be registered unless an offset has been set for this operation in which case the first available IP next to the offset will be taken. The offset is defined in the Global IP Settings for the organization.

The request may specify the attributes to be given to the IP. Similarly, output fields may be specified in the request.

Example

Passing the following json_data:

{
	'operation' => 'teemip/pick_ip_address_in_subnet',
	'class' => 'IPv4Subnet',
	'key' => array(
		'org_id' => 3,
		'ip' => '10.129.2.0',
	),
	'fields' => array(
		'status' => 'reserved',
		'comment' => 'Hello',
		'requestor_id' => array(
			'name' => 'Kahlo',
			'first_name' => 'Frida',
		),
		'short_name' => 'my-test-ip',
		'domain_id' => array(
		        'name' => 'demo.com.',
		),
	),
	'comment' => '',
	'output_fields' => 'ip, short_name, domain_name, status',
}

… will provide the reply:

Array
(
    [objects] => Array
        (
            [IPv4Address::42] => Array
                (
                    [code] => 0
                    [message] => created
                    [class] => IPv4Address
                    [key] => 42
                    [fields] => Array
                        (
                            [ip] => 10.129.2.5
                            [short_name] => my-test-ip
                            [domain_name] => demo.com.
                            [status] => reserved
                        )
                )
        )
    [code] => 0
    [message] => 
)

TeemIp specific error messages may be:

• IP addresses cannot be created within an object of class <class specified in the request> if target class is not an IPv4 or IPv6 subnet class.
• The current user does not have enough permissions for creating data of class <class specified in the request>
• The subnet does not exist
• There is no free IP in the subnet (above configured offset, if any)

Pick and register an available IP in a given IP range. The first available IP will be registered and no offset can be used here.

The request may specify the attributes to be given to the IP. Similarly, output fields may be specified in the request.

Example

Passing the following json_data:

{
	'operation' => 'teemip/pick_ip_address_in_range',
	'class' => 'IPv6Range',
	'key' => 22,
	'fields' => array(
		'status' => 'reserved',
		'comment' => 'Hello',
		'requestor_id' => array(
			'name' => 'Kahlo',
			'first_name' => 'Frida',
		),
		'short_name' => 'my-test-ip',
		'domain_id' => array(
			'name' => 'demo.com.',
		),
	),
	'comment' => '',
	'output_fields' => 'ip, short_name, domain_name, status',
}

… will result into something like:

Array
(
    [objects] => Array
        (
            [IPv6Address::44] => Array
                (
                    [code] => 0
                    [message] => created
                    [class] => IPv6Address
                    [key] => 44
                    [fields] => Array
                        (
                            [ip] => fc01:0:1964:404:a::
                            [short_name] => my-test-ip
                            [domain_name] => demo.com.
                            [status] => reserved
                        )
                )
        )
    [code] => 0
    [message] => 
)

TeemIp specific error messages may be:

• IP addresses cannot be created within an object of class <class specified in the request> if target class is not an IPv4 or IPv6 range class.
• The current user does not have enough permissions for creating data of class <class specified in the request>
• The IP range does not exist
• There is no free IP in the IP range

Pick and register an available subnet in a given IP block. The first available subnet will be registered and no offset can be used here.

The request may specify the attributes to be given to the subnet. Similarly, output fields may be specified in the request.

Example

Passing the following json_data:

array
(
	'operation' => 'teemip/pick_subnet_in_block',
	'class' => 'IPv6Block',
	'key' => 15,
	'fields' => array(
		'name' => 'Vlan - '.$i, 
                'mask' => '64',
		'status' => 'reserved',
		'comment' => 'Hello',
		'requestor_id' => array(
			'name' => 'Kahlo',
			'first_name' => 'Frida',
		),
	),
	'comment' => '',
	'output_fields' => 'name, ip, mask, status, type, requestor_id',
)

… will provide the following answer.

Array
(
    [objects] => Array
        (
            [IPv6Subnet::181] => Array
                (
                    [code] => 0
                    [message] => created
                    [class] => IPv6Subnet
                    [key] => 181
                    [fields] => Array
                        (
                            [name] => Vlan - 3377
                            [ip] => fc01:0:1964:407::
                            [mask] => 64
                            [status] => reserved
                            [type] => DC Server LAN
                            [requestor_id] => 7
                        )
                )
        )
    [code] => 0
    [message] => 
)

TeemIp specific error messages may be:

• Subnets cannot be created within an object of class <class specified in the request> if target class is not an IPv4 or IPv6 subnet class
• The current user does not have enough permissions for creating data of class <class specified in the request>
• The IP block does not exist
• There is no space left for a new subnet in the IP block

Get, under standard BIND format, the master db file that describes a DNS zone.

The request specifies the zone, the view it belongs to (if any) and the output order for records: by records or by char.

Example

Passing the following json_data:

array
(
	'operation' => 'teemip/get_zone_file',
	'class' => 'Zone',
	'key' => array(
		'org_id' => 3,
		'name' => 'demo.com.',
        'view_id' => 1,
	),
	'format' => 'sort_by_record',
)

… will give the following text file

Array
(
    [objects] => Array
        (
            [Zone::13] => Array
                (
                    [code] => 0
                    [message] => computed
                    [class] => Zone
                    [key] => 13
                    [fields] => Array
                        (
                        )

                    [text_file] => $TTL 86400
@ IN SOA ns0.demo.com. hostmaster.demo.com. (
                 10      ; Serial
                 900     ; Refresh
                 600     ; Retry
                 604800  ; Expire
                 300 )   ; Negative caching

;
; Name servers
;

;
; IPv4 addresses for the canonical names
;

;
; IPv6 addresses for the canonical names
;

;
; Aliases
;

;
; Mail exchangers
;

;
; Locate services
;

;
; Text
;

                )
        )
    [code] => 0
    [message] => Found: 1
)

TeemIp specific error messages may be:

• No TeemIp zone management extension has been installed
• The current user does not have enough permissions for reading data of class Zone