IPAM

Pull

Synopsis

Director sweeps one IPv4 subnet from where it runs and writes which of its addresses are in use as ECS documents. Every address gets an ICMP echo and a TCP connect to each of a few ports; an address that answers either is in use, and its names are looked up in reverse DNS. Nothing is installed on the subnet: Director probes the addresses as any host on the network could. What the device writes is decided by the datasets and profiles assigned to it, as for SNMP and VMware vSphere devices — see IPAM Datasets.

One device sweeps one subnet, a /20 at most. A sweep probes one address at a time, so the size of the subnet is the size of the work. A larger range is split into several devices, which may run on several Directors.

The device dials every address and binds nothing, so IPAM devices never collide on a port. One Director owns each device.

note

The IPAM device needs Director 2.2.3 or later. With no Director or cluster at that version selected, the wizard shows IPAM devices are unavailable on directors or clusters below version 2.2.3 and the device cannot be created.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: ipam
  tags: <string[]>
  status: <boolean>
  properties:
    subnet: <string>
    icmp: <boolean>
    ports: <numeric[]>
    reverse_dns: <boolean>
    resolver: <string>
    timeout: <numeric>
    concurrency: <numeric>
    rate: <numeric>
    addresses_per_reading: <numeric>
  definitions: <definition[]>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be ipam
tags	N	-	Optional tags
status	N	true	Enable/disable the device

Subnet

Field	Required	Default	Description
subnet	Y	-	The IPv4 network to sweep, in CIDR notation, a /20 or smaller. Written with host bits set (192.0.2.10/24), it is the network they are in (192.0.2.0/24), and the device's log says so. See The Subnet

Probe Settings

Field	Required	Default	Description
icmp	N	true	An echo request to every address, and a second one when the first gets no reply
ports	N	[22, 80, 443, 445, 3389]	The TCP ports every address is connected to, 32 at most. A list, one port, or text separated by commas. [] connects to none
reverse_dns	N	true	Looks up the names of every address that answers: its PTR records
resolver	N	the system's	Where the names are asked: an address or a host name, with :port when it is not 53. Left out, the first name server the Director's system lists. See Probes

icmp: false with ports: [] is refused: no address could answer.

Datasets

The device's definitions are its datasets, each named after its type, ipam_<dataset>_collector. In the console they are the datasets and profiles assigned to the device. For the dataset types and their fields, see IPAM Datasets.

With no dataset assigned, the device sweeps nothing.

Advanced Configuration

Field	Required	Default	Description
addresses_per_reading	N	1024	The slice of the subnet a reading sweeps, from 1 to 4096 addresses. See Pace
rate	N	50	Probes started a second at most, echoes, connects, and reverse lookups together, from 1 to 1000
concurrency	N	32	Addresses probed at once, from 1 to 256
timeout	N	1	Seconds each echo, connect, and reverse lookup waits for its answer, from 1 to 10

Every bound is enforced when the configuration is read: a value outside it stops the device with Configuration error, and the message says which. A number is read whole — a fraction, or text that is not a number, is refused rather than converted. A switch (icmp, reverse_dns) is true or false; anything else is refused, never read as false.

The Subnet

• A /20 at most. A /20 holds 4,096 addresses, 4,094 of them probed. A /19 or larger is refused when the configuration is read, with a message that says to split it into devices of a /20 or smaller.
• IPv4 only. IPv6 is refused: a /64 holds 2⁶⁴ addresses, and its hosts pick theirs anywhere in it, so no prefix small enough to sweep would find them.
• Refused ranges. Multicast (224.0.0.0/4), the reserved range (240.0.0.0/4, the limited broadcast with it), and 0.0.0.0/8 are refused.
• Network and broadcast addresses are skipped. They name no host. A /31's two addresses (a point-to-point link) and a /32's one address are probed.

Probes

An address answers when it replies to an echo request or takes a connect to one of the ports.

• ICMP echo. Up to two echo requests per address, the second only when the first gets no reply.
• TCP connect. One connect to each port, made to the address and closed as soon as it is made. A service on an open port sees a connection opened and closed, which it may log. The default ports are the ones that answer on most hosts that drop echo requests: SSH (22), HTTP (80), HTTPS (443), SMB (445), and RDP (3389).
• Reverse DNS. One PTR question for each address that answered, over UDP, and again over TCP when the answer comes back truncated. It goes to resolver, or to the first name server the Director's system lists (/etc/resolv.conf, or on Windows the first network adapter that is up). The hosts file is not read. An address that did not answer is not looked up.

A refused connect is no answer. A firewall answers for the addresses behind it with a reset, and counting that would find a whole subnet in use behind a firewall that rejects.

A probe that could not be sent is never read as silence. Each address ends a sweep in one of three states:

State	When
Used	It answered an echo or a connect
Free	Every probe of it was sent and nothing answered
Not known	It did not answer, and a probe of it could not be sent — no route to the network, the Director's own firewall, too many open files — so that probe might have been answered

Only a free address is free. A Director that loses its route to the subnet finds nothing free and marks nothing removed.

Permission to Ping

On Linux the Director sends echoes through an unprivileged ICMP socket, which the kernel allows for the groups net.ipv4.ping_group_range names. systemd sets the range to every group; a distribution without systemd may leave it empty. Failing that, the Director uses a raw socket, which needs root or CAP_NET_RAW. On Windows the Director needs nothing.

A Director that may not send echoes fails the reading with Initialization error, and the message names both sockets it tried. Nothing is written, and the sweep stays where it was. Allow the Director to ping, or set icmp: false and rely on the TCP ports.

Pace

A sweep never floods the network it sweeps.

• Slices. A reading sweeps addresses_per_reading addresses, and the next reading goes on from the first address it did not reach. A sweep is one pass over the whole subnet, over one reading or several. At the default, a /22 or smaller is swept whole at every reading, and a /20 over four readings.
• Rate. rate caps every probe the device starts — echoes, connects, and reverse lookups together — at one every 20 ms by default. With the defaults an address gets at most seven probes: two echoes and five connects.
• Duration. At the default pace a /24 is swept in about 40 seconds, and a /20 takes four readings of about two and a half minutes each, about 10 minutes of sweeping in all.
• Progress survives a restart. Where the sweep stands is kept in the Director cluster's replicated store, so a restart, or another Director the device moves to, goes on from there. Editing the subnet starts the new one from the beginning.

The device reads at the shortest interval among its datasets, since both are written from the same sweep. A reading that runs longer than the interval delays the next one, which starts a second after it ends.

Connection States

State	When
Connected	A reading probed its slice
Connection error	No address of a reading could be probed: the Director has no route to the subnet, or its own firewall refuses the probes. The message names the first probe that failed
Initialization error	The Director may not send ICMP echoes. See Permission to Ping
Configuration error	The configuration does not validate, or reverse DNS has no resolver to ask

Console

In the console, go to Fleet Management > Devices > IPAM and click Add new device. The wizard's steps are:

1. General settings, as on every device.
2. Sweep settings: Subnet; then, under Probes, ICMP echo, TCP ports (Optional), Reverse DNS, and Resolver (Optional), shown while reverse DNS is on. With ICMP echo on, the wizard notes that the Director needs permission to ping.
3. Advanced settings: Addresses per reading, Probes per second, Workers (concurrency), and Timeout.
4. Data collection: the datasets or profile the device writes. A device receives datasets or a profile, never both.
5. Review and create.

Simulation

The IPAM device is not simulated. Its records are the addresses of its subnet that answer, marked against the last sweep, and the subnet's usage, which one generic sample cannot stand in for.

Examples

Office Subnet

Sweeping a /24 with the default probes, writing the addresses in use and the subnet's usage every five minutes...

devices: - id: 512300190 name: office-lan type: ipam status: true properties: subnet: "192.0.2.0/24" definitions: - name: ipam_address_collector - name: ipam_usage_collector

No ICMP

Sweeping a network whose firewall drops echo requests, finding its hosts through three TCP ports alone, at a slower rate...

devices: - id: 512300191 name: dmz-no-icmp type: ipam status: true properties: subnet: "198.51.100.0/24" icmp: false ports: [22, 443, 8443] reverse_dns: false rate: 20 definitions: - name: ipam_address_collector properties: interval: 600