DEVELOPMENT SERVER: content may be inaccurate

Host Records

Introduction

A Host record allows a single primary Name (fully-qualified domain name) to be associated with any of the following, managed collectively in Grid Manager as a single database object:

  • one or more IPv4 addresses, which manifest as matching pairs of A and PTR records
  • one or more IPv6 addresses, which manifest as matching pairs of AAAA and PTR records
  • one or more Host Aliases, which manifest as CNAME records pointing to the primary name
  • optional DHCP fixed address configuration for each IP address

Host records provide several advantages compared to managing an equivalent collection of Stand-alone DNS Records, the most important of which is that if you change one part of a Host record, the other parts will automatically update to stay in sync.

The trade-off is that you must be VERY careful when deleting a Host record!

Best Practice Recommendations:

  • In general, use Host records instead of stand-alone A, AAAA, and PTR records, except when you do not want matching pairs.
  • Do not create multiple Host records for the same IP address.
  • Use stand-alone CNAME records instead of Host Aliases if the desired alias name resides in a different zone (from the primary name) which is not managed by the same set of people.
  • In general, use DHCP-enabled Host records instead of DHCP Fixed Addresses.

For more information, see When should I use stand-alone A records? and When should I use stand-alone CNAME records?

Creating a Host record

To create a new Host record:

  1. Open the DNS Zone which will contain the desired primary name.  (alternative: open a Network in IPAM View and select the desired IP address).  Opening Zones and Networks is described in Getting Started with IPAM.
  2. Click the dropdown arrow next to the Add (+) icon above the table in the main workspace, then choose “Host”, and finally “Host” again.

    screenshot

    This opens the Add Host dialog box. (alternative: in IPAM View click Add, then “Host”, then “New Host”)

  3. If necessary, click the “Select Zone” button and choose the zone which will contain the desired primary name (e.g. to create “myhost.sandbox.illinois.edu”, you would select the zone “sandbox.illinois.edu”).

    If you opened a DNS zone in the main workspace, it will be automatically pre-selected for you.

  4. Type the leading portion of the Name (e.g. “myhost“) into the text box to the left of the selected zone name, so that both pieces together form the desired fully-qualified domain name.

    screenshot

    • You may leave the text box empty to create a record with the same name as the zone itself (e.g. “sandbox.illinois.edu”).
    • You may type e.g. “foo.bar” in the text box to create a record named “foo.bar.sandbox.illinois.edu” even if there is no zone “bar.sandbox.illinois.edu”.
  5. If necessary, add one or more IPv4 Addresses to your Host: click the drop-down arrow next to the Add (+) icon just above the IPv4 Addresses table and choose “Add Address” to place a new row in the table, then click the IPv4 Address field in that row and type the desired IPv4 address. Press return or click elsewhere when you are done typing.

    screenshot

    If you opened a Network and selected an IPv4 address in the main workspace, it will be automatically pre-populated for you.

    Adding more than one IPv4 address to a Host will create multiple matching pairs of A and PTR records for the same primary Name, resulting in “round-robin DNS” behavior.

  6. If necessary, add one or more IPv6 Addresses to your Host.
  7. Add a comment in the “Comment” field (optional).
  8. Click “Next” at the bottom of the dialog window.
  9. If desired, add one or more Extensible Attributes (e.g. “Property Tag”).

  10. Click “Next”.
  11. If desired, you may schedule this change to occur at a later time instead of taking effect immediately (see Scheduled Tasks).
  12. Click “Save & Close” at the bottom of the dialog window.

Editing a Host Record

Before changing the primary Name of a Host record, it is advisable to perform a Basic Search by DNS Name for the current primary Name (fully-qualified domain name), in order to identify any Stand-alone DNS Records (CNAME, MX, etc) pointing to it.

  1. Navigate to the Host record you want to edit (see Getting Started with IPAM); you can find it either by name or by IP.
  2. Select the checkbox for the Host record and click the Edit (notepad) icon above the table.

    screenshot

    This opens the Edit Host dialog.

  3. Make any desired changes (several possibilities are discussed below).
  4. Click “Save & Close” at the bottom of the dialog window.

Adjusting TTL

For changes to high-profile DNS records (e.g. migrating a live production service), Technology Services recommends that you temporarily lower the TTL of the record in question (e.g. to 1 minute) at least one hour prior to making the actual change, and then restore the TTL to the campus default (1 hour) after the change is complete and you have confirmed that everything is working properly.

To set a custom TTL for a Host record:

  1. Choose the “TTL” subscreen in the Edit dialog.
  2. Click “Override” next to the TTL value, and enter the new desired value (e.g. 1 Minute).

    screenshot

  3. Click “Save & Close”.

When your high-profile change is complete, Edit the record again and click “Inherit” on the same TTL subscreen to resume using the campus default.

screenshot

 

You may find it helpful to add the TTL column to the table of Records in a Zone.  Note that this column only displays customized TTLs; it is left blank for records which inherit the default TTL.

Adding Host Aliases

A Host Alias is functionally equivalent to a stand-alone CNAME record which points to the Host’s primary Name, but carries trade-offs with respect to ease of future maintenance.  For more information, see When should I use stand-alone CNAME records?

To add a Host Alias to a Host Record:

  1. Choose the “Aliases” subscreen in the Edit dialog

  2. Click the Add (+) icon to place a new row in the table, then click the Aliases field in that row and type the new fully-qualified domain name that should point to this Host.  Press return or click elsewhere when you are done typing.

    screenshot

  3. Click “Save & Close”.

Enabling DHCP for Host addresses

Enabling DHCP within a Host record is functionally equivalent to creating a stand-alone DHCP Fixed Address, but makes it easy to keep the DNS and DHCP configuration for a client in sync (in case you later decide to migrate the same client to a different IP address or retire it altogether).

To enable DHCP for an IP address in a Host record (either while adding a new Host record or while editing an existing one):

  1. Click the DHCP checkbox to the right of the desired IP address.

  2. For IPv4 addresses: click the “MAC Address” field in that row and type the MAC address of the client that will use this IP.  Press return or click elsewhere when you are done typing.

    Click here to expand…

  3. For IPv6 addresses: click the “DUID” field in that row and type the DHCP Unique Identifier (see also Limitations of DHCPv6 fixed address allocation) of the client that will use this IP.  Press return or click elsewhere when you are done typing.
  4. Optionally, you can also select the IP address using the checkbox to its left and then click the Edit (notepad) icon above the table to configure custom DHCP options that will apply only to this individual fixed address (but are otherwise similar to Setting DHCP Options for a Range).  Hint: don’t forget to enable Advanced Mode for the sub-dialog.
  5. Click “Save & Close”.

Please note that your network must have autoconfiguration service appropriately enabled (see Requesting DHCP for Networks) in order for enabling DHCP within a Host record to have any effect.

Displaying Host records in a Zone

When displaying Records within a Zone (see Getting Started with IPAM), we recommend that you click “Toggle flat view” so that each manifestation of a Host record is displayed in its own table row.  After you click it, the link text changes to “Toggle hierarchical view”.  It should look like this:

screenshot

If you instead choose to display Records in hierarchical view, the Host record will appear only as a single row for the primary Name, and any Host Aliases in other zones will not be visible at all when displaying the contents of those zones.  This view is not recommended, as it may cause you to overlook important data.

screenshot

DHCP Ranges (Dynamic Pools)

This page contains information about configuring DHCP Ranges (Dynamic Pools) and DHCP options.

Introduction

A DHCP Range provides a pool of IP addresses that can be assigned interchangeably to any eligible DHCP client.

To configure an individual IP address for use exclusively by a single DHCP client, see DHCP Fixed Addresses or Adding DHCP to a Host Record.

The instructions below assume that you are working in DHCP View (see Getting Started with IPAM). Some DHCP configuration tasks can also be performed from IPAM View, but the exact sequence of steps may differ.

Creating A New IPv4 DHCP Range

To create a new DHCP Range:

  1. Open the Network in which you want to add a new range (see Getting Started with IPAM).
  2. Click the dropdown arrow next to the Add (+) icon above the table in the main workspace, then choose “Range”.
  3. Click “Next” at the bottom of the dialog window.
  4. Enter the desired Start (first) and End (last) IP addresses for the range.

    Make sure the range will be large enough to comply with Range Size Guidelines.

  5. Optionally enter an internal display name and/or a comment.
  6. Click “Next”.

  7. Important: for “Served by”, choose “IPv4 DHCP Failover Association” and then click the “Select Association” button to automatically select “DHCP-A” which is the only failover association available.

    Do NOT select “Grid Member”.  Although a DHCP Range served by a single Grid Member may appear at first glance to function correctly, this configuration is unsupported because it does not properly utilize the redundancy provided by DHCP Failover.

  8. Click “Save & Close” at the bottom of the dialog window.

Editing a Range

To edit an existing Range:

  1. Navigate to the Range you want to edit (e.g. by opening its Network in DHCP View, see Getting Started with IPAM).
  2. Select the checkbox for the Range object and click the Edit (notepad) icon above the table.  This opens the Edit dialog box.
  3. Be sure to enable Advanced Mode for the dialog.
  4. Make any desired changes (see subsections below).
  5. Click “Save & Close”.

Setting DHCP Options

See DHCP Standards for the option values that will automatically apply unless you choose to override them.

To configure additional DHCP options:

  1. Choose the “IPv4 DHCP Options” subscreen in the Edit dialog.
  2. Scroll down to the “Custom DHCP Options” section at the bottom.
  3. Add your new option in the last row:
    1. First field:
      • Choose a custom vendor option space if you wish to set a vendor-specific option which will be automatically encapsulated inside option 43 (see RFC 2132 Section 8.4) when replying to clients with the appropriate vendor class identifier (option 60).
      • Otherwise, choose “DHCP” to set a standard DHCP option.
    2. Second field: choose which option to set.  Option names are not standardized and may vary by implementation, so check the numeric option code (displayed in parentheses) to be sure you have the right one.

      If you need to set a custom DHCP option or vendor-specific option that is not yet defined in Grid Manager (i.e. does not appear in the drop-down lists), please contact hostmgr@illinois.edu.
    3. Third field: type the desired value.  The format of this value depends on the type defined for the option; see DHCP Option Data Types in the vendor documentation.
  4. To add another option, click the + button.

To configure BOOTP/PXE settings:

  1. Choose the “IPv4 BOOTP/PXE” subscreen in the Edit dialog (requires Advanced Mode).
    Click the Override button next to the setting you wish to override, and enter a new value.

    Hint: most PXE clients require values for Next Server and Boot File (which respectively populate the “siaddr” and “file” protocol fields defined by RFC 2131); please note that these settings are not the same thing as options 66 and 67. Clients utilizing the Boot Server (“sname” protocol field) setting are much less common in our experience.

If you need to enter a value that contains backslash characters, they should be doubled, e.g. foo\\bar instead of foo\bar.

Exclusion Ranges

To exclude certain addresses within a DHCP Range from being dynamically assigned to clients:

  1. Choose the “Exclusion Ranges” subscreen in the Edit dialog (requires Advanced Mode).
  2. To add a new exclusion range:
    1. Click the Add (+) icon above the table to create a new row.
    2. Click the empty “Start Address” field in the new table row that appears, and type the first address to be excluded.
    3. Click the “End Address” field and type the last address in the range to be excluded. To exclude only a single IP address, enter the same value for Start Address and End Address.
  3. To remove an exclusion range:
    1. Select the checkbox to the left of the exclusion range to be deleted.
    2. Click the Delete (trash can) icon above the table.

Email Alerts

By default, the DHCP servers will automatically alert you by email whenever the current utilization of one of your DHCP Ranges exceeds 95% (and again when it drops back below 85%), with a maximum of one email alert per Range per day.  The recipient list for these emails is automatically populated (at the Network level) based on the network contacts listed in Contacts Database.

You may wish to add the following addresses to your email address book and/or safe senders list to ensure that DHCP utilization warnings are not filtered as spam:

  • no-reply@dhcp-a1.techservices.illinois.edu
  • no-reply@dhcp-a2.techservices.illinois.edu

sample message
From: <no-reply@dhcp-a1.techservices.illinois.edu>
Subject: DHCP high threshold crossed:

Message: DHCP high threshold crossed:
  Member: 192.17.2.10
  Network: 172.21.195.0/28/default
  Range: 172.21.195.7/172.21.195.14///default
  High Trigger Mark: 95%
  High Reset Mark: 85%
  Current Usage: 100%
  Active Leases: 5
  Available Leases: 0
  Total Addresses: 5

Reporting: DHCP
Node: 192.17.2.10
Time: Mon Mar  7 15:01:49 2018


Network Name: 0210-citesdhcp-net

Utilization graphs: 
https://ipam-tools.techservices.illinois.edu/dhcpmon/view.fcgi?subnet=0210-citesdhcp-net

Help: https://netwiki-dev.techservices.illinois.edu/public/home/ipamdocs/using-ipam/dhcp-ranges-dynamic-pools/#Email_Alerts

You can customize the behavior of Email Alerts for this Range by choosing the “IPv4 DHCP Thresholds” subscreen in the Edit dialog (requires Advanced Mode).

  • To adjust the threshold values (or disable notifications altogether) for this Range, click the Override button for the “DHCP Thresholds” area.

    • Be sure to check both “Enable DHCP Thresholds” and “Enable Email Warnings” if you do still want to receive notifications.  Do NOT check “Enable SNMP Warnings”.

      screenshot

    • Note that actual utilization must be strictly greater than the High Trigger Mark (or strictly less than the Low Trigger Mark) in order to trigger an alert.

      Hint: do NOT set High Trigger Mark to 100. If you only want notifications when the range is completely full, set High Trigger Mark to 99.

  • To manually specify the list of email addresses which will receive threshold alert notifications for this Range (overriding the default recipient list for the Network), click the Override button for the “Email Addresses” area and populate the table as desired.
  • To return either area to its default behavior, click the corresponding “Inherit” button.

Restricting Access to a Range

By default, IP addresses in a DHCP Range can be dynamically allocated to any client machine that is connected to the appropriate network. To restrict the use of a DHCP Range to specific clients:

  1. Create a new MAC Address Filter and populate it with the desired MAC addresses (see MAC Address Filters), OR identify a suitable existing MAC Address Filter.

    You can use the same MAC Address Filter to restrict access to multiple DHCP Ranges.
  2. Choose the “Filters” subscreen in the Edit dialog for the Range (requires Advanced Mode).
  3. Click the Add (+) icon for the Class Filter List table, and select your MAC Address Filter.
    • By default the filter will be added with Action “Grant Lease”, meaning that clients matching this MAC Address Filter will be permitted (and clients not matching any MAC Address Filter listed in the Class Filter List will be denied).
    • If instead you want to deny leases to MACs matching this filter, click on “Grant Lease” and it will become a drop-down, then choose “Deny Lease” instead.

To return to the default behavior of permitting all clients, simply remove all Filters from the Class Filter List.

Advanced note: some use cases may involve adding an IPv4 Option Filter to the Class Filter List instead.  If a Class Filter List contains more than one type of filter (e.g. one or more MAC Address Filters AND one or more IPv4 Option Filters), then clients will be checked against the criteria for each filter type separately, and must satisfy them all in order to receive a lease.

Using Multiple DHCP Ranges

Best practice: avoid using more than one DHCP Range on the same network, unless each is intended for a different (non-overlapping) set of clients.

In most cases, you will want to create only one DHCP Range per network. If your network has a discontinuous collection of IP addresses which should be assigned interchangeably, it is better to create one large DHCP Range with Exclusions then to create several small DHCP Ranges which are otherwise identical, because Email Alerts apply individually to each Range.

It may make sense to create multiple DHCP Ranges if each one is intended to be used by a different (non-overlapping) set of clients.  If this is your goal, make sure that you associate at least one Filter with each Range.

Hint: if you configure one DHCP Range with action “Grant Lease” for a particular Filter, and a second DHCP Range with action “Deny Lease” for the same Filter, then any clients matching that Filter will be placed in the first range and all other clients will be placed in the second range.

Placing Fixed Addresses inside a DHCP Range

Best practice: avoid placing Fixed Addresses (or DHCP-enabled Hosts) inside a DHCP Range.

If you configure a Fixed Address (or DHCP-enabled Host) for an IP address that resides within a DHCP Range, it will function correctly (i.e. the IP in question will not be allocated to any other client).  However, the fixed address will be counted in the utilization statistics for the DHCP Range, which can be confusing and misleading – especially in the context of Email Alerts.

The simplest way to avoid confusion is to separate the IP addresses used for dynamic vs fixed allocations so they don’t overlap, but this may not be feasible if your net is full of legacy devices that can’t be easily moved.  In that scenario, your choices include:

  • Configure Exclusion Ranges for all IPs used by fixed addresses, so that they will not be counted as part of the Range.  This works well, but increases complexity (if you ever remove the fixed address, you must also remember to remove the exclusion before the IP will become dynamically assignable again).
  • Accept that your utilization statistics will be inaccurate, and consider adjusting Email Alert thresholds for a better practical outcome (e.g. if utilization currently hovers between 95-99%, increase High Trigger Mark to 99 so that you’ll still receive a notification if it ever hits 100%).
  • Decide that email alerts on this Range aren’t worth the trouble, and disable them.  (But be careful: this means new dynamic clients will just silently fail to get a lease if none is available, and you won’t have any indication why).

Reserved Ranges

If you set “Served by” to “None (Reserved Range)” instead of “IPv4 DHCP Failover Association”, then your range will be a Reserved Range rather than a DHCP Range.

Reserved Ranges provide no DHCP functionality; they are simply a way to label a group of addresses within the IPAM system (with the additional proviso that Reserved Ranges and DHCP Ranges can never overlap). See vendor documentation for more information about Reserved Ranges.

Note that addresses within Reserved Ranges will be counted (along with DHCP Ranges) in the DHCP Utilization statistics for the entire net, which can be confusing.  Workaround: Edit the Reserved Range and check “Disable for DHCP”.

DHCP Fixed Addresses

Introduction

A DHCP Fixed Address makes a particular IP address available for use exclusively by a single designated client.  For as long as the Fixed Address is configured, the designated client will always receive this IP address when connected to the appropriate network, and this IP address will never be allocated to any other client.  For DHCPv4, the designated client is identified by MAC address; for DHCPv6, it is identified by DUID (DHCP Unique Identifier – see also Limitations of DHCPv6 fixed address allocation).

From the client’s point of view, obtaining a lease from a Fixed Address is exactly the same as obtaining a lease from a DHCP Range.

On the server side, however, there is an important difference: fixed addresses are timeless, which is to say that the server’s behavior does not take into account whether the IP address in question was previously leased (either to the same client or to a different client).  This has two practical consequences for the careful network administrator wishing to avoid an operational conflict:

  • Avoid configuring a Fixed Address for an IP which currently has an Active lease belonging to a different client (unless you are certain that the old client is no longer on the network).
  • Avoid configuring a Fixed Address for an IP which very recently had a Fixed Address belonging to a different client (unless you are certain that the old client is no longer on the network).

Stand-alone Fixed Addresses vs DHCP-enabled Host records

The stand-alone DHCP Fixed Address objects described on the remainder of this page are DHCP-only objects with no DNS component.

You may alternatively wish to consider enabling DHCP for an IP address within a Host record, which is functionally equivalent to creating a stand-alone Fixed Address but makes it easy to keep the DNS and DHCP configuration for a client in sync (in case you later decide to migrate the client to a different IP address or retire it altogether).

Best practice: in general, use DHCP-enabled Host records instead of stand-alone DHCP Fixed Addresses.

Reservations

You may notice that it’s also possible in IPAM to create a “Reservation” object.  This is not the same thing as a Fixed Address, and will not accomplish what you probably intend; a “Reservation” in IPAM is a placeholder which does not permit any DHCP client to use the IP.

Users familiar with Microsoft DHCP should note that a Microsoft DHCP “Reservation” is analogous to a Fixed Address in IPAM, not a “Reservation”.

Creating a DHCP Fixed Address

To create a new stand-alone DHCP Fixed Address:

  1. Using either DHCP View or IPAM View, Open the Network in which you want to add a fixed address (see Getting Started with IPAM).
  2. Optionally (if using IPAM View), select the checkbox next to the desired IP address.
  3. Click the dropdown arrow next to the Add (+) icon above the table in the main workspace, then choose “Fixed Address”.
  4. Click “Next” at the bottom of the dialog window.
  5. Enter the desired IP address.

    If you have opened a Network in IPAM View and selected an IP address in the main workspace, it will automatically be pre-populated for you.

  6. For IPv4 addresses: ensure that “MAC Address” is selected, and enter the MAC address of the client that will use this IP.
  7. For IPv6 addresses: enter the DUID (DHCP Unique Identifier – see also Limitations of DHCPv6 fixed address allocation) of the client that will use this IP.
  8. Optionally, you may use the Name field to specify an internal display name for this Fixed Address object.

  9. Click “Save & Close”.

Please note that your network must have autoconfiguration service appropriately enabled (see Requesting DHCP for Networks) in order for creating a DHCP Fixed Address to have any effect.

Editing a Fixed Address

To edit an existing stand-alone DHCP Fixed Address:

  1. Navigate to the Fixed Address you want to edit (e.g. by opening its Network in DHCP View, or opening the individual IP address in IPAM View to display Related Objects – see Getting Started with IPAM).
  2. Select the checkbox for the Fixed Address object, and click the Edit (notepad) icon above the table.
  3. Make sure to enable Advanced Mode for the dialog.
  4. Make any desired changes.
  5. Click “Save & Close”.

Note that you can configure custom DHCP options that will apply only to this individual fixed address (but are otherwise similar to Setting DHCP Options for a Range).

Deleting a Fixed Address

To deleted an existing stand-alone DHCP Fixed Address:

  1. Navigate to the Fixed Address you want to edit (e.g. by opening its Network in DHCP View, or opening the individual IP address in IPAM View to display Related Objects – see Getting Started with IPAM).
  2. Select the checkbox for the Fixed Address object (making sure no other checkboxes are selected), and click the Delete (trash can) icon above the table.
  3. If you’re sure, click “Yes” when the confirmation dialog appears.

Requesting DHCP for Networks

Terminology

This page uses “autoconfiguration” as a generic term (more general than DHCP) for empowering end hosts on your network to automatically configure themselves with an IP address and other network configuration parameters.

Requesting Autoconfiguration Service

To enable autoconfiguration for your existing network, email net-trouble@illinois.edu with the following information:

  • The name and IP CIDR of the network
  • Which type of autoconfiguration you would like to enable (see below for details)
  • If the network already has a DHCP server, let us know and provide details so that we can assist you in migrating your existing DHCP configuration into IPAM.
  • Optionally, any other special configuration changes you require at this time (e.g. DHCP options set at the network level)

Sample requests:

“Please enable DHCPv4 for uiuc-example-net 192.0.2.0/24”

“Please enable IPv6 Stateless autoconfiguration for uiuc-example-net 2001:db8:abcd::/64”

“Please enable IPv6 Stateful autoconfiguration for uiuc-example-net 2001:db8:abcd::/64”

“I would like to migrate uiuc-example-net 192.0.2.0/24 to campus DHCP from an existing local DHCP server.  (details)”

Please note: merely enabling DHCPv4 or IPv6 Stateful autoconfiguration is not sufficient to allow your DHCP clients to obtain leases!  You must also use IPAM to configure DHCP for your network.  Read on for more information.  (IPv6 Stateless autoconfiguration is different, and does not require you to configure anything in IPAM)

For new networks, work with your network designer to request autoconfiguration service as part of the network creation process.

Autoconfiguration Design Guide

There is no one-size-fits-all optimal approach to autoconfiguration; which type you choose, and which DHCP objects you configure in IPAM, will vary depending on how you want to use and administer your network.

The first step is to determine which of the following client behaviors you want to support:

  • dynamic address allocation: each client automatically obtains an available IP address which is arbitrary and unpredictable. It doesn’t matter which client gets which IP, or if a particular client gets a different IP next time it comes back. This behavior is the easiest to configure, and requires very little administrative maintenance once set up.
  • fixed address allocation: each client automatically obtains an IP address which has been administratively reserved for that client’s exclusive use.  This behavior requires more configuration work in IPAM (new clients must be added and old ones removed), but allows individual client IPs to be stable and predictable.
  • manual client configuration: each client device is manually configured with the necessary network parameters, and does not use autoconfiguration at all. This is usually only necessary for devices which do not support autoconfiguration.

It is possible to mix and match, using different behaviors for different clients on the same network, but care must be taken to avoid conflicts!

In particular, if your network includes any manually-configured devices, it is very important that DHCP not be configured to hand out those IP addresses to other clients!

Next, select the autoconfiguration type that best supports your desired behavior(s) – these are covered in detail in the following sections – and request that type of autoconfiguration service on your network.

Finally, if you’ve chosen DHCPv4 and/or IPv6 Stateful autoconfiguration, configure the desired DHCP objects in IPAM (see Using IPAM for detailed instructions):

  • DHCP Ranges (Dynamic Pools) for dynamic address allocation
  • DHCP-enabled Host Records and/or DHCP Fixed Addresses for fixed address allocation

    Notes for Microsoft DHCP users

    A Microsoft DHCP “Reservation” corresponds to a “Fixed Address” in IPAM. Avoid the temptation to create a “Reservation” in IPAM; that term refers to a different concept entirely and will not accomplish what you intend.

    Also, there is no need to place Fixed Addresses inside a DHCP Range (a “scope” in Microsoft terms); in fact, it’s best practice to avoid doing this. If you don’t want to use dynamic address allocation behavior on your network, you should not create a DHCP Range at all.

IPv4 Autoconfiguration Types

For IPv4, autoconfiguration is synonymous with DHCPv4, so the standard choices are simple; DHCPv4 is either enabled or disabled for any given network.

No Autoconfiguration

DHCPv4
dynamic address allocation?
fixed address allocation?
manual client configuration? ✅ note: manually configured clients may need to explicitly disable autoconfiguration.
Technical Details

Router: no ip helper

IPAM: network disabled

Router: ip helper pointing to campus DHCP servers

IPAM: network enabled, with Fixed Addresses / Hosts (for fixed allocation behavior) and/or Ranges (for dynamic allocation behavior)

Notes:

  • Several best practice recommendations are discussed in DHCP Ranges (Dynamic Pools).
  • One strategy for preserving flexibility on a mixed-behavior net is to create a DHCP Range near the end of the net (i.e. highest-numbered IPs), and allocate Fixed Addresses, DHCP-enabled Hosts, and static IPs for manual configuration (if any) starting from the beginning of the net (lowest-numbered IPs).

IPv6 Autoconfiguration Types

For IPv6, there are multiple standard implementation choices for autoconfiguration, each supporting different behavior(s):

No Autoconfiguration

Stateless Stateful
dynamic address allocation? ✅ preferred ⚠️ less efficient, redundancy is not automatic (see technical details)
fixed address allocation? ✅ yes, but see Limitations
manual client configuration? ✅ note: manually configured clients may need to explicitly disable autoconfiguration. ✅ note: manually configured clients may need to explicitly disable autoconfiguration.
Suggested Use Cases

non-routed nets carrying only link-local traffic

other special cases

typical end-user nets (dynamic)

wherever fixed address allocation behavior is required
What Happens

Client self-configures one or more arbitrary IPv6 addresses, and sends a DHCPv6 Information-Request to obtain option values (including the IPv6 DNS resolver address).

Clients lacking DHCPv6 support can still obtain an address, but will not obtain option values.

Client uses DHCPv6 to obtain both an IPv6 address and option values (including the IPv6 DNS resolver address).

Dynamic vs fixed allocation is determined by IPAM configuration.

Clients lacking DHCPv6 support must be configured manually.

Technical Details

Router: A=0, M=0, O=0, no DHCPv6 relay

IPAM: network disabled

More precisely “SLAAC + stateless DHCPv6”

Router: A=1, M=0, O=1, DHCPv6 relay pointing to campus DHCP servers

IPAM: network enabled, but no Ranges or Fixed Addresses / Hosts

Router: A=0, M=1, O=0, DHCPv6 relay pointing to campus DHCP servers

IPAM: network enabled, with Fixed Addresses / Hosts (for fixed allocation behavior) and/or Ranges (for dynamic allocation behavior)

Notes:

  • Where feasible, choose Stateless over Stateful autoconfiguration for your IPv6 networks.
    • Stateless is simpler than Stateful, and significantly easier on the DHCP servers.
    • If your network includes clients without DHCPv6 support, they will still be able to obtain an IPv6 address using Stateless autoconfiguration. Such clients will not learn the IPv6 DNS resolver address or other option values, but in many cases clients can function successfully without this information (e.g. by using IPv4 for DNS resolution, if available).
    • It is easy to migrate between Stateless and Stateful in the future if your requirements change.
  • Most modern clients do support DHCPv6, as shown in https://en.wikipedia.org/wiki/Comparison_of_IPv6_support_in_operating_systems.

Technical Details

  • A, M, and O refer to the “Autonomous address configuration”, “Managed address configuration”, and “Other configuration” flags in the Router Advertisement, defined in RFC 4861.
  • The “Stateless” option shown above is more precisely described as “SLAAC + stateless DHCPv6” (SLAAC is the common abbreviation for IPv6 Stateless Address Autoconfiguration, as defined in RFC 4862).  Other stateless options are technically possible, but are not listed in the chart because we anticipate that they would rarely offer any practical advantage.
    • In particular, RDNSS (the “Recursive DNS Server” Router Advertisement option defined in RFC 6106) offers another way to provide clients with the IPv6 DNS resolver address, but DHCPv6 provides more general functionality, and most clients which support RDNSS also support DHCPv6.
  • The DHCPv6 Failover Protocol (to automatically provide redundancy for dynamic autoconfiguration using DHCPv6) defined in RFC 8156 is not currently supported by IPAM, so the only way to achieve dynamic allocation redundancy with Stateful autoconfiguration is to manually configure two separate non-overlapping Ranges in IPAM, one served by each DHCP server.

Limitations of DHCPv6 fixed address allocation

The DHCPv4 protocol specification (RFC 2131) includes a “client hardware address” (chaddr) field which in practice contains the MAC address of the requesting client’s network interface.  This makes it easy for a DHCPv4 server to identify clients by MAC, and to assign fixed address allocations based on the client’s MAC.

The DHCPv6 protocol specification (RFC 3315) does not include a client hardware address field; instead, it defines the DHCP Unique Identifier (DUID) which is intended as an opaque, globally unique, and stable identifier for the whole client device (not just for one of its network interfaces).  Because the MAC address is not included in DHCPv6 messages, there is currently no way for a DHCPv6 server to assign fixed address allocations based on the client’s MAC address; instead, you must configure them based on the client’s DUID.

The challenge is that it can be difficult or impossible to learn the client’s DUID ahead of time.  While the MAC address is a property of the physical hardware, the DUID (for most general-purpose computers, at least) is a software property generated and stored on disk by the operating system.  Depending on your operating system, the DUID may not even exist until it is needed for the first time – and it will almost certainly change if you reinstall the operating system, dual-boot to a second operating system, etc.

Recommendations:

  • Where possible, sidestep this issue entirely by using dynamic address allocation instead of fixed.
  • If you do require fixed address allocation, make sure you understand the challenges discussed in this section and that you have a strategy for ascertaining client DUIDs.

RFC 6939 defines a Client Link-Layer Address option (inserted by the router acting as relay agent) which may someday provide an easier alternative, but as of this writing it is not supported by IPAM or by most building routers.

Other Information

DHCP Standards details important guidelines and recommendations for using the DHCP service, as well as the default configuration parameters that will automatically apply to all networks unless you choose to override them.

Email Alerts explains the automated email notifications that may be sent to network administrators by the DHCP service.

Stand-alone DNS Records

This page contains information about creating and managing stand-alone DNS records.

Introduction

We use the term “stand-alone” to refer to any standard DNS record type (A, AAAA, CNAME, MX, SRV, TXT, etc) which does not have special proprietary behavior in Grid Manager.  There are many different types of stand-alone records, but the steps for managing them are very similar; we will discuss a few of the most common ones.

This page does not contain many screenshots, but some of the screenshots from the Host Records page may also be helpful here.

Stand-alone A Records

An address (A) record maps a fully-qualified domain name to a single IPv4 address:

www.example.com. IN A 198.51.100.17

Publishing multiple A records for the same name is legal and results in “round-robin DNS” behavior.

Best practice: use stand-alone A records only when you need an A record with no matching PTR (see below for further discussion). If you want a matching pair of A and PTR records, create a Host Record instead.

To create a stand-alone A record (with no matching PTR):

  1. Open the DNS Zone in which you want to create the new record (see Getting Started with IPAM).
  2. Click the dropdown arrow next to the Add (+) icon above the table in the main workspace, then choose “Record” and finally “A Record”.

  3. If necessary, click the “Select Zone” button and choose the zone which will contain the desired fully-qualified domain name (e.g. to create “myrecord.sandbox.illinois.edu”, you would select the zone “sandbox.illinois.edu”).

  4. Type the leading portion of the Name (e.g. “myrecord“) into the text box to the left of the selected zone name, so that both pieces together form the desired fully-qualified domain name.
    • You may leave this text box empty to create a record with the same name as the zone itself (e.g. “sandbox.illinois.edu”).
    • You may type e.g. “foo.bar” in the text box to create a record named “foo.bar.sandbox.illinois.edu” even if there is no zone “bar.sandbox.illinois.edu”.
    • You may type “*” or e.g. “*.bar” in the text box to create a record with a wildcard domain name (see RFC 4592).
  5. Enter the target IP Address to which your A record should resolve.
  6. Important: UNCHECK “Create associated PTR record”

    If you do want a matching PTR, you should Cancel this operation and create a Host Record instead.  Leaving this box checked creates a stand-alone A record and a separate stand-alone PTR record, which is undesirable because they can easily get out of sync in the future.
  7. Click “Save & Close”.

AAAA records are exactly like A records, but they target IPv6 addresses instead of IPv4 addresses.

www.example.com. IN AAAA 2001:db8::17

When should I use stand-alone A records?

Use stand-alone A (and AAAA) records when you do not want a matching PTR record.

Common reasons for this include:

  • the IP address already has a PTR record pointing to a different fully-qualified domain name

  • the IP address belongs to a network whose reverse-mapping DNS is not managed in IPAM

Otherwise, it is preferable to use Host Records (which automatically manifest as matching pairs of A/AAAA and PTR records).

Note that it is best practice to avoid creating multiple PTR records for the same IP address.  While not technically an error, this may cause problems for software which expects reverse lookups to return a single name (an expectation subtly encouraged by language such as “primary” and “the host name” in https://tools.ietf.org/html/rfc1035#section-3.5).

When you want several fully-qualified domain names (FQDNs) to resolve to the same IP address, the recommended best practice is:

  1. Create a Host Record for the FQDN that you consider to be primary.
  2. Where possible, implement each additional FQDN as a Host Alias or stand-alone CNAME record pointing to the primary FQDN.
  3. Create a stand-alone A record with no PTR for each additional FQDN which cannot be implemented as a CNAME record.

Example: Host Record for server17.mysubdomain.illinois.edu, stand-alone CNAME records (pointing to server17.mysubdomain.illinois.edu) for www.mysubdomain.illinois.edu and www.example.com, and stand-alone A records (pointing to the same IP as the Host Record) for mysubdomain.illinois.edu and example.com (which cannot be implemented as CNAME records since each resides at the apex of a zone).

MX Records

A mail exchanger (MX) record indicates the fully-qualified domain name of a mail server which can accept incoming email messages for a domain:

illinois.edu. IN MX 10 incoming-relays.illinois.edu.

Note that successful use of this record also entails resolving A (and/or AAAA) records for the mail server name.

To create an MX record:

  1. Open the DNS Zone in which you want to create the new record (see Getting Started with IPAM).
  2. Click the dropdown arrow next to the Add (+) icon above the table in the main workspace, then choose “Record” and finally “MX Record”.

  3. If necessary, click the “Select Zone” button and choose the zone which will contain the desired fully-qualified domain name (e.g. to create “myrecord.sandbox.illinois.edu”, you would select the zone “sandbox.illinois.edu”).

  4. Type the leading portion of the Mail Destination (e.g. “myrecord“) into the text box to the left of the selected zone name, so that both pieces together form the desired fully-qualified domain name.
    • You may leave this text box empty to create a record with the same name as the zone itself (e.g. “sandbox.illinois.edu”).
    • You may type e.g. “foo.bar” in the text box to create a record named “foo.bar.sandbox.illinois.edu” even if there is no zone “bar.sandbox.illinois.edu”.
  5. In the “Mail Exchanger” field, enter the target fully-qualified domain name of the mail server to which the MX record should point.

    Per RFC 2181, the target of an MX record MUST NOT be an (explicit) alias (i.e. a Host Alias or CNAME record).  You are responsible for following this rule; it is not enforced automatically.
  6. In the Preference field, enter a priority value for this record. (10 is selected by default)

  7. Click “Save & Close”.

Stand-alone CNAME Records

A CNAME record defines a static, explicit alias in the DNS which affects query behavior for all record types:

www.illinois.edu. IN CNAME illinois.edu.
  • Query: www.illinois.edu. IN A?
    Answer:

    www.illinois.edu. IN CNAME illinois.edu.
    illinois.edu.     IN A     192.17.172.3
  • Query: www.illinois.edu. IN MX?
    Answer:

    www.illinois.edu. IN CNAME illinois.edu.
    illinois.edu.     IN MX    10 incoming-relays.illinois.edu.

Common points of confusion:

  • This CNAME record helps your browser find the IP address of a web server for www.illinois.edu.  It does not tell your browser to redirect HTTP requests for http://www.illinois.edu/ to a different URL (only the web server itself can do that).
  • A CNAME record cannot coexist with other records (e.g. no other records are permitted at www.illinois.edu)

    RFC 1034: “If a CNAME RR is present at a node, no other data should be present; this ensures that the data for a canonical name and its aliases cannot be different.”

    A few special record types for DNSSEC are exempted by later RFCs.

  • A CNAME record cannot be placed at the apex of a zone (e.g. illinois.edu).

    This follows from the previous point, because the apex of a zone is required to have NS and SOA records.

  • CNAME stands for “canonical name”, but that term (correctly applied) refers to the target name, not the alias name.  Best practice: use the terms “alias” and “target” to avoid confusion.

To create a stand-alone CNAME record:

  1. Open the DNS Zone in which you want to create the new record (see Getting Started with IPAM).
  2. Click the dropdown arrow next to the Add (+) icon above the table in the main workspace, then choose “Record” and finally “CNAME Record”.

  3. If necessary, click the “Select Zone” button and choose the zone which will contain the desired fully-qualified domain name of the alias (e.g. to create “myalias.sandbox.illinois.edu”, you would select the zone “sandbox.illinois.edu”).

  4. Type the leading portion of the Alias name (e.g. “myalias“) into the text box to the left of the selected zone name, so that both pieces together form the desired fully-qualified domain name.
    • You may type e.g. “foo.bar” in the text box to create a record named “foo.bar.sandbox.illinois.edu” even if there is no zone “bar.sandbox.illinois.edu”.
    • You may type “*” or e.g. “*.bar” in the text box to create a record with a wildcard domain name (see RFC 4592).
  5. In the “Canonical Name” field, enter the target fully-qualified domain name to which the alias should point. 

    The target of a CNAME record should not be another (explicit) alias.  So-called “CNAME chains” are not technically an error, but create inefficient behavior and are discouraged as a bad practice (see RFC 1034 sections 3.6.2 and 5.2.2).

  6. Click “Save & Close”.

When should I use stand-alone CNAME records?

A Host Alias is functionally equivalent to a stand-alone CNAME record pointing to the Host’s primary FQDN, but carries trade-offs with respect to ease of future maintenance.  Which option is preferable depends on the situation.

Advantages of using a Host Alias:

  • A Host Alias will automatically be kept up to date if you change the Host’s primary Name, whereas a stand-alone CNAME record will be left “dangling” if the target Host record is renamed or deleted.

Advantages of using a stand-alone CNAME record:

  • Modifying an existing stand-alone CNAME record to point to a different target is a simple one-step operation.  The corresponding process for a Host Alias requires editing the old Host (to remove the Host Alias) and then editing the new Host (to add the Host Alias).
  • If a Host Alias resides in a different zone (from the primary Name of the Host) which is not managed by the same set of people, the disparity in permissions may impede self-service changes to the record (possibly requiring an escalation to hostmgr).  A stand-alone CNAME record presents no such problem; it is governed by the permissions on the zone containing the alias name, while any target record(s) are governed by the permissions of the zone containing the target fully-qualified domain name.

    Best practice: always use a stand-alone CNAME record in the case where the desired alias name and the canonical (target) name reside in different zones which may not be managed by the same set of people.

Stand-alone PTR Records

A PTR record is a pointer to another fully-qualified domain name.  PTR records (unlike CNAME records) are simple data; they do not alter DNS behavior, may coexist with other records, and have no inherent special meaning.  Their significance is understood by convention from where they are placed in the namespace (e.g. “17.100.51.198.in-addr.arpa” is understood to represent the IPv4 address 198.51.100.17).

PTR records are most commonly used for reverse-mapping DNS (i.e. mapping from an IP address to a fully-qualified domain name).  In general, you should never create a stand-alone PTR record in IPAM for this purpose; instead, create a Host Record which will automatically manifest as matching pairs of A (or AAAA) and PTR records.

The rare exception to this rule occurs when you specifically need a PTR record for reverse-mapping DNS to point to a fully-qualified domain name whose forward-mapping zone is not managed in IPAM.

If you do need to manage stand-alone PTR records for reverse-mapping DNS, just Open the Network in IPAM View (see Getting Started with IPAM); it is not necessary to navigate the arpa zones.

Stand-alone PTR records in forward-mapping DNS zones (used infrequently for other purposes such as DNS-SD) are not a special case, and can be managed just like the other types of stand-alone records described on this page.

Editing Stand-alone DNS Records

  1. Navigate to the record you want to edit (see Getting Started with IPAM).
  2. Select the checkbox for the record and click the Edit (notepad) icon above the table. This opens the Edit dialog box.
  3. Make any desired changes.
  4. Click “Save & Close”.

Deleting Stand-alone DNS Records

  1. Navigate to the record you want to delete (see Getting Started with IPAM).
  2. Select the checkbox for the record (making sure no other checkboxes are selected), and click the Delete (trash can) icon above the table.
  3. If you’re sure, click “Yes” when the confirmation dialog appears.

Using the IPAM API

This page contains information about configuring and using the Grid Manager API (application programming interface).

Introduction

IPAM Grid Manager includes a RESTful Web API (WAPI).  The purpose of this page is to help you get started using WAPI, and to make you aware of some important considerations that are specific to the University of Illinois IPAM service.  Please refer to the vendor documentation for a comprehensive API reference.

WAPI vendor documentation is available from https://ipam.illinois.edu/wapidoc/ or published in PDF format.

The current WAPI version is 2.12.3. New client programs should be written to use this version.

Previous WAPI versions still supported include: 1.4.2, 2.2.2, 2.7.3, 2.11.1

API Credentials

All IPAM users (see How do I gain access to IPAM?) also have access to the API.  You must authenticate using your full Active Directory userPrincipalName (typically yournetid@illinois.edu or serviceuser@ad.uillinois.edu, but other variations are also possible).

Using your own credentials is appropriate for direct, interactive use of the API (e.g. command-line utilities) where you can supply your Active Directory password and Multi-Factor Authentication (MFA) at run time.  IPAM is not able to prompt you interactively for a second authentication factor, but you can append a passcode or factor name to your password as documented in https://guide.duo.com/append-mode.

If you don’t append anything to your password, you should automatically receive a push notification (if you have a smartphone registered for Duo).

If you have more than one smartphone registered for Duo, you might need to append e.g. “,push2” to use your second device.

If your actual password happens to contain any commas (the delimiter character for append mode), we suggest always appending something (e.g. “,push”) so that your authentication can succeed on the first try without requiring an extra round-trip to AD on the back end.

If your application requires unattended access to the IPAM API, you will need to create and authorize a non-person service user:

  1. Create an Active Directory user object under your own organizational unit (OU) with a strong, randomly generated password.  We suggest choosing a name longer than 8 characters that begins with your unit or group followed by a dash (e.g. “techsvc-foo”) for easy identification and to avoid conflicting with potential NetIDs; see also Active Directory Naming Conventions.
  2. Use Contacts Database to grant the desired permissions to your service user (either directly or via an AD group).

    Note that Contacts Database identifies users by their Active Directory sAMAccountName, a.k.a. “User logon name (Pre-Windows 2000)”, which is different from the userPrincipalName you will use to authenticate to the IPAM API.
  3. Non-person service users must be individually exempted from MFA for IPAM by the IPAM service managers.  Contact hostmgr with the Active Directory userPrincipalName of your service user to request this.
  4. Verify that you can successfully authenticate to the IPAM API with the Active Directory userPrincipalName of your service user.  If the actual password happens to contain any commas, we suggest appending “,push” as a placeholder so that authentication can succeed on the first try.

Rules of Use

  1. Contrary to some of the vendor-provided examples,
    • Always use a hostname (i.e. “ipam.illinois.edu” for production) in the WAPI request URL. Do not use an IP address.

      It is possible that the IP address of the grid master may change from time to time, but the hostname ipam.illinois.edu will always resolve to the current grid master’s IP.

    • DO NOT disable SSL/TLS validation e.g. by passing the “-k” option to curl.
  2. Use the “ibapauth” cookie (see Transport and Authentication) when making multiple API requests in the same program invocation, so that IPAM will not have to recheck your credentials (and MFA) for every single request.
  3. Keep in mind that the grid master has finite computational resources, and be responsible and considerate in your usage. Do not (for example) write a script that performs lots of intensive API operations and schedule it to run automatically every few minutes.

    If you need to write a recurring API job that could significantly impact the grid master, please talk to us first. We don’t want to have to revoke access to the API.

  4. Read and understand Backward Compatibility, and plan your deployments accordingly.

    Best practice: obtain the full WAPI base URL including version (e.g. https://ipam.illinois.edu/wapi/v2.12.3) from one or more configuration parameters rather than hardcoding it directly into your program.

Quick Start

Try a few simple GET requests from the command line using curl:

  • Retrieve the singleton Grid object (a simple test to make sure your credentials work):

    curl --user yournetid@illinois.edu -X GET 'https://ipam.illinois.edu/wapi/v2.12.3/grid'
  • Again, but also save the returned “ibapauth” cookie to a temporary cookie jar file, and use it to make a subsequent request without having to supply credentials:

    COOKIE_JAR=$(mktemp)
    
    curl --user yournetid@illinois.edu -c ${COOKIE_JAR:?} -X GET 'https://ipam.illinois.edu/wapi/v2.12.3/grid'
    
    curl -b ${COOKIE_JAR:?} -X GET 'https://ipam.illinois.edu/wapi/v2.12.3/grid'
    
    rm ${COOKIE_JAR:?}

    Be sure to consider the security implications of storing the cookie in a file!  Real applications should store it in memory instead (where it cannot be read by other processes).

  • List all IPv4 Networks you have permission to see:

    curl --user yournetid@illinois.edu -X GET 'https://ipam.illinois.edu/wapi/v2.12.3/network'
  • Again, but include Extensible Attributes (such as Network Name) in the returned data, and limit the result set to 2 objects:

    curl --user yournetid@illinois.edu -X GET \
    'https://ipam.illinois.edu/wapi/v2.12.3/network?_return_fields=network,extattrs&_max_results=2'
  • Again, but use paging to iterate through the entire result set, retrieving 2 objects at a time.

    This is a simple example for demonstration purposes.  In practice, results paging is only necessary when your search might return too many objects to retrieve all at once (e.g. > 1000), and you should use a page size on the order of 500 or 1000.

    Initial request:

    curl --user yournetid@illinois.edu -X GET \
    'https://ipam.illinois.edu/wapi/v2.12.3/network?_return_fields=network,extattrs&_max_results=2&_paging=1&_return_as_object=1'

    Subsequent requests:

    curl --user yournetid@illinois.edu -X GET \
    'https://ipam.illinois.edu/wapi/v2.12.3/network?_page_id=789c5590...9c96b659'

    where each new request’s `_page_id` is the value of `next_page_id` returned by the previous request.

The documentation includes sample curl requests for PUT, POST, and DELETE (Examples accessing WAPI using Curl), but many of these examples require permissions that are not given to non-superusers in our environment (e.g. creating Networks).  Try adapting them to other object types, such as a stand-alone A record:

Note: URLs in the following examples are written to use the development IPAM system, a good idea when experimenting with new features you haven’t used before.

  • Use POST to create a new stand-alone A record:

    curl --user yournetid@illinois.edu -X POST 'https://dev.ipam.illinois.edu/wapi/v2.12.3/record:a' \
    -H "Content-Type: application/json" \
    --data '{ "name": "mytestrecord.sandbox.illinois.edu", "ipv4addr": "192.168.0.5", "comment": "WAPI is fun" }'
  • Search for the record we just created, and note its object reference (“_ref“) in the output:

    curl --user yournetid@illinois.edu -X GET 'https://dev.ipam.illinois.edu/wapi/v2.12.3/record:a?name=mytestrecord.sandbox.illinois.edu'
  • Use PUT to modify the ipv4addr field of the existing record (using the object reference obtained above):

    curl --user yournetid@illinois.edu -X PUT 'https://dev.ipam.illinois.edu/wapi/v2.12.3/record:a/ZG5zLmJp...LjAuMC41' \
    -H "Content-Type: application/json" \
    --data '{ "ipv4addr": "192.168.0.6" }'

Resources

The Infoblox Community site has an article on Getting Started with the Infoblox Web API (WAPI) which you may find helpful, as well as a long list of REST examples (user-contributed) and other searchable content.

Perl

Here are a helper module and a working example script that you can use as a basis for your own programs.  Set environment variable IPAM_WAPI to the desired WAPI base URL (including version) before running the script.

  • IPAMUserAgent.pm

    Helper module for IPAM WAPI scripts written in Perl.
    Requires LWP::UserAgent, optionally uses Config::Simple

  • add_host_ip.pl

    Uses GET, POST, and PUT requests to either create a new Host record or add an IP to an existing Host record.
    Requires IPAMUserAgent.pm (above), JSON, and NetAddr::IP.

Python

Here are a helper module and a working example script that you can use as a basis for your own programs.  Set environment variable IPAM_WAPI to the desired WAPI base URL (including version) before running the script.

  • ipam.py

    Helper module for IPAM WAPI scripts written in Python 3.
    Requires requests (http://docs.python-requests.org)

  • add_host_ip.py

    Uses GET, POST, and PUT requests to either create a new Host record or add an IP to an existing Host record.
    Requires ipam.py (above)

Ansible

Ansible provides official Infoblox NIOS modules for many common use cases; see also Ansible’s Infoblox Guide.  Here are a helper playbook and some working example playbooks to get you started; note that these playbooks take extra care to avoid unexpectedly overwriting or deleting an existing record.

Requires infoblox-client (https://infoblox-client.readthedocs.org/)

Deprecated Perl-only API (PAPI)

You may encounter occasional references to a legacy Perl-only API (PAPI) which predated the modern RESTful Web API (WAPI), worked only with Perl, and required specific Infoblox perl modules to be installed on every client system and upgraded in lockstep with the appliance grid.  Use of PAPI at the University of Illinois has been strongly discouraged for many years, and it is now officially deprecated by the vendor as well.  Our only reason for mentioning it here is to forestall confusion in case you encounter the term and wonder what it means.

Managing DHCP Leases

This page contains instructions for viewing and clearing DHCP Leases.

Introduction

A DHCP Lease represents a DHCP server’s knowledge that a particular IP address has been allocated to a particular client for a specified period of time.

Note: because of the way DHCP Failover works, each dynamically allocated IP address actually has two corresponding Lease objects in Grid Manager – one for each DHCP server in the failover pair.

Grid Manager may also display “Static” Lease objects for IP addresses that have been assigned to a client via DHCP Fixed Address (or DHCP-enabled Host); note that these behave differently from regular Leases because fixed addresses are timeless.

Displaying Leases

There are three different ways to display Leases in Grid Manager. In all cases, the Lease objects on the servers are updated in real time; use the Refresh icon at the bottom of the window to see the latest data.

Viewing Leases in a single DHCP Range

You can view all free and assigned Leases in a particular DHCP Range by opening the Range object:

  1. In DHCP View, Open the DHCP Network to which the DHCP Range belongs (see Getting Started with IPAM).
  2. Open the Range by clicking on its address range displayed in the IP Address column.

    You can add the MAC Address column to this table.

Any “Static” Leases for IP addresses within the DHCP Range will also be included.

To see the details of an assigned Lease, select it and choose “Lease Details” from the toolbar panel on the right.

Viewing Leases in a Network

You can see the status of each IP address on a Network, including whether it is currently assigned as a Lease, by opening the Network in IPAM View (see Getting Started with IPAM).

Known Issue: in IPAM view, “Static” Leases are only displayed if the IP in question happens to fall within a DHCP Range.

The Lease State and MAC Address are visible in columns of the table (if you have selected List display).

To see the full details of an assigned Lease:

  1. Open the IP address (in List display), or select it on the graphical map (in IP Map display).
  2. Select the Lease from the Related Objects table.
  3. Choose “Lease Details” from the toolbar panel on the right.

Viewing all Leases in all of your Networks

You can view all Lease objects on all of your Networks at once (including “Static” Leases) by navigating to Data Management > DHCP > Leases > Current Leases using the rows of tabs at the top of the screen.

screenshot

This is by far the slowest method of examining Leases, because Grid Manager has to check every Lease object in its database against your individual user permissions in order to determine which ones should be displayed.  Performance can be improved by using a Filter to narrow the scope of your interest; for example,

  • IP Address belongs to “192.168.0.0/26” (pictured in screenshot above) for a CIDR match, or
  • IP Address begins with “192.168.0.” for a plain string match.

Known Issue: when you first click on the Current Leases tab, you may need to wait up to 2 minutes for the unrestricted search to time out before you can successfully apply a Filter.

Note that free addresses which do not have Lease objects yet (because they have never been assigned to a client) will not be displayed in this view.

To see the details of an assigned Lease, select it and click the Lease Details (paper) icon above the table.

Clearing Leases

The DHCP protocol specification does not empower the server to revoke a client’s lease once it has been issued.

However, you can force the DHCP servers to forget that a lease has been assigned (thereby making it available for assignment to other clients) by selecting it and clicking “Clear Lease” from the toolbar (in IPAM view, click the drop-down arrow next to “Clear” and then choose “Clear Lease”).

Use extreme caution when clearing leases, as it may cause IP address conflicts on your network!

Even after a lease has been cleared in Grid Manager, the client is within its rights to continue using the allocated IP address until the original expiration time.

In general, you should clear a lease only if you are absolutely certain that the client has been removed from the network.

Note that “Static” Leases cannot be cleared this way, but will be automatically removed by Grid Manager if you modify your DHCP configuration in a way that would permit the IP in question to be allocated to a different client.

Abandoned Leases

An Abandoned lease marks an IP address which is configured for DHCP dynamic allocation but has been abandoned by the DHCP server as unfit for use, due to one of the following occurrences:

  • After receiving a DHCPDISCOVER, the server selected this IP address to be offered, but received a response to its ping check.
  • After sending a DHCPACK for this IP, the server received a DHCPDECLINE message from the client indicating that the IP address is already in use (typically because the client issued an ARP request for the IP address and received a response, as described in RFC 2131 section 4.4.1).

Abandoned leases do not expire but remain Abandoned indefinitely, at least until the supply of Free/Backup leases becomes exhausted.  When a DHCPDISCOVER is received and there is no Free/Backup lease available to fulfill it, DHCP will automatically attempt to reclaim one Abandoned address and offer it to the new client (after performing the usual ping check).  However, if the reclaimed address is still in use, it will be marked Abandoned again and no DHCPOFFER will be sent, meaning the client will fail to obtain a lease (even though there might be other Abandoned addresses which aren’t actually still in use – in that case, future DHCPDISCOVER attempts by the same or other clients will eventually fare better).

What to do about Abandoned leases:

  • Try to avoid them in the first place by making sure that clients on your network are correctly configured to use DHCP and, if your network includes any manually-configured devices, making sure that DHCP is not configured to hand out those IP addresses.
  • If you do accumulate a significant number of Abandoned leases, identify any addresses which are not actually still in use on the network, and manually Clear them from Grid Manager.

    Hint: to see only the Abandoned addresses within a particular network, open the Network in IPAM view (as in Viewing Leases in a Network above), and apply Filter: Lease State equals Abandoned

CSV Imports and Exports

Introduction

The CSV Import feature of Grid Manager provides one way to perform “bulk” updates which create, modify, or delete many DNS and/or DHCP objects at once. Not every imaginable use case is supported, but most common tasks are fairly straightforward.

Caution: it is not possible to “undo” or roll back a CSV import after it is executed!

When in doubt, we highly recommend using development IPAM for proof-of-concept testing.

Note that you can also perform “bulk” updates programmatically using the IPAM API; the advantages and disadvantages of each approach vary depending on the nature of the task at hand.

Creating CSV Data Files for Import

For your convenience, Technology Services has created ready-made template data files for a number of common tasks, which can be used for their intended purpose just by reading and following the instructions on this page.

If you wish to adapt any of the templates for other purposes, or to create your own data files from scratch, please refer to CSV Import Reference in the vendor documentation.

Performing a CSV Import

Once you have created a CSV data file, use the following steps to import your data file into Grid Manager:

  1. Click “CSV Import” on the Toolbar panel to bring up the CSV Import Wizard.
  2. Choose the desired import type:
    • Add
      Adds a new Grid Manager object based on the data in each row (will fail if an object with the same required field values already exists).

    • Override
      Uses the required field values in each row to select an existing Grid Manager object (will fail if no suitable object exists), then overwrites any other attributes of that object specified in the remaining columns.
    • Merge
      Uses the required field values in each row to select an existing Grid Manager object (will fail if no suitable object exists), then fills in any attributes specified in the remaining columns for which the object does not already have a value.
    • Delete
      Uses the required field values in each row to identify and delete an existing Grid Manager object.
    • Custom
      See vendor documentation.
    • Replace
      See vendor documentation; use with caution.
  3. Click “Next”.
  4. Click the “Choose…” button and choose a CSV file to upload.  The file name should appear in the text box.
  5. Optionally select how Grid Manager should behave “On error”.

    Note: no matter which behavior you select, any rows before the first error row will always take effect.
  6. Click “Next”.
  7. The first few rows of your data file should appear in the preview area (separated into columns); make sure it looks reasonable.
  8. Click “Import” to begin the operation.

    Note: if you click “Save & Close” at any point prior to clicking “Import” in this step, your job will be saved but not executed.  See Managing Existing CSV Jobs (below) to find it again.

  9. The “CSV Import Progress” window will appear, showing the current status of your job (probably “Import pending”).
  10. You may wait here for your job to complete; when it does (typically within about 30 seconds), the current status will change to “Import successful” or “Import unsuccessful”.
    Alternatively, you may click “Close & Run in Background” to dismiss the dialog box and work on something else while you wait; see Managing Existing CSV Jobs (below) to find it again.
  11. Once the job has completed, check the “Rows with errors” counter to see if any errors were generated.
    • If so, click the “Download Errors” button to retrieve another CSV file containing the error rows (prepended with their corresponding error messages).
    • Remember: any rows from your original CSV file that did not produce errors will still have been imported!
  12. Click “Close” to dismiss the dialog.

Managing Existing CSV Jobs

Click “CSV Job Manager” on the Toolbar panel to display a table containing your CSV jobs submitted within the last 30 days.

Use the hamburger menu icon in each table row and click “Edit” to open the Edit CSV Import Job dialog box, which includes an “Import” button to execute the job.

Grid Manager allows you to Edit a job which has already been executed and click Import to execute that same job again without re-uploading the file, but if you do so, the information about the previous run (timestamps, error file, etc) will no longer be available in CSV Job Manager.  It is usually preferable to start a new import job instead.

You can also use the hamburger menu to Delete a job which has not yet been executed, or Download the Error File from a job which terminated unsuccessfully.

Templates

The following templates are available to help you perform common tasks via CSV Import.

Each template contains at least one header row which can be used exactly as provided, followed by one or more sample object rows which should be modified (and more rows added if necessary) to reflect the actual data you wish to import. The header row beginning with e.g. “HEADER-Foobar” tells Grid Manager how to interpret the columns of the corresponding object rows beginning with e.g. “Foobar” (which must be a valid object type).

Some templates include columns whose values are described as optional; you may safely choose to leave these columns blank when filling in your object rows.

  • Create new DNS-only Host Records
    Type: Add
    Importing this spreadsheet will create a new Host Record for the FQDN in each row, with the specified IPv4 and/or IPv6 address(es) and Host Aliases. You must specify at least one address. The “aliases”, “EA-Property Tag” (Property Tag extensible attribute) and “comment” values are optional. Host records created using this template will not be enabled for DHCP.
  • Create new DHCP-enabled Host Records
    Type: Add
    This template expands on the previous one to create new Host Records whose IP addresses are also enabled for DHCP. Each new Host record to be created needs multiple CSV rows:
    • one “HostRecord” row specifying the FQDN and all of its associated IPv4 and/or IPv6 addresses (as well as optional “aliases”, “EA-Property Tag”, and “comment” values)
    • zero or more “HostAddress” rows to enable the DHCP checkbox and specify the associated MAC address for each individual IPv4 address within the Host
    • zero or more “IPv6HostAddress” rows to enable the DHCP checkbox and specify the associated DUID for each individual IPv6 address within the Host
  • Enable DHCP for Existing Host Addresses
    Type: Override
    For each row, “parent” and “address” must match the FQDN and an IPv4 or IPv6 address of an existing Host record in IPAM. Importing this spreadsheet will enable the DHCP checkbox for that IP address and overwrite its associated MAC address or DUID (as described in Adding DHCP to a Host record).
    Hint: you can obtain names and IP addresses of existing Host records on a network (to use as a starting point) by opening the Network in IPAM view and exporting visible data.
  • Add IP Addresses to Existing Host Records
    Type: Add
    For each row, “parent” must match the FQDN of an existing Host record in IPAM. Importing this spreadsheet will assign an additional IP address to that Host record. Optionally, you may choose to enable DHCP for newly added IP addresses.
  • Create Stand-alone DNS Records
    Type: Add
    Use this template to create new Stand-alone DNS Records of various types. Each type has its own header row; please omit any unused header rows from your data file. All “comment” values are optional.

    Keep in mind that Host Records are often (but not always) preferable to stand-alone A and AAAA records.

  • Importing this spreadsheet will create a new DHCP Fixed Address with the IP address and MAC address or DUID specified in each row. The “EA-Property Tag” (Property Tag extensible attribute) and “comment” values are optional.

  • Add MAC Addresses to a MAC Address Filter
    Type: Add
    Importing this spreadsheet will add the MAC address in each row to the MAC Address Filter whose name appears in “parent”. The “registered_user”, “EA-Property Tag” (Property Tag extensible attribute), and “comment” values are optional.
  • Modify Existing Stand-alone DNS Records
    Type: Override
    For each row, the required fields (indicated with asterisks) must match an existing Stand-alone DNS Record in IPAM.  Importing this spreadsheet will modify that record according to the values specified in the remaining columns.  To modify a required field such as the address of an A record, specify the old value in “address” and the new value in “_new_address” (leave “_new_address” blank if you don’t want to change the address). Each type has its own header row; please omit any unused header rows from your data file.

Exporting data from Grid Manager

Many tables in Grid Manager can be exported as a downloadable CSV in two different ways, using the drop-down menu for the Export (up arrow) button:

screenshot

  • Choose “Export visible data” to download a CSV containing precisely the columns and values that are actually visible within the current table (i.e. as shown on the screen, except that all pages of the table are included).
  • Choose “Export data in Infoblox CSV Import Format” to download a full CSV representation of the Grid Manager objects that appear in the current table, including all of their configuration attributes.

Other tables in Grid Manager provide only a single Export button with no drop-down menu; this is equivalent to “Export visible data” as described above.

You can restrict which rows (objects) are included in the CSV by applying a Filter to the table beforehand.

MAC Address Filters

This page contains instructions for creating and managing MAC address filters for DHCP.

Introduction

A MAC Address Filter is a Grid Manager object which keeps track of a set of MAC addresses.

MAC Address Filters are typically used to restrict access to IPv4 DHCP Ranges. Once you have configured your MAC Address Filter the way you want it using the instructions below, see Restricting Access to a Range to apply it to a DHCP Range.

Creating a new MAC Address Filter

If you need a new MAC Address Filter, please email hostmgr to request one. Provide the following details:

  • a desired name for the new MAC Address Filter object.

    There is a single global namespace for all Filters, so try to choose something reasonable that incorporates the department or group for which this filter is relevant. If in doubt, explain what you plan to use it for, and we will help you choose a suitable name.
  • the name(s) of one or more network models (from Contacts Database) that should confer “ownership” rights to this MAC Address Filter. Any user with permissions on any of the named network models will automatically be given permission to manage this MAC Address Filter as well (updated nightly).

    These network model names will be stored in Grid Manager as values of an Extensible Attribute called “Owned By Network”. Modifying or removing this attribute may result in loss of permissions on the MAC Address Filter.

Managing MAC addresses in a MAC Address Filter

To open a MAC Address Filter:

  1. Navigate to Data Management > DHCP > Filters using the rows of tabs at the top of the screen.
  2. Open the desired MAC Address Filter by clicking on its name in the table.

This will display a table containing all MAC addresses currently present in the MAC Address Filter.

If your table contains many rows, see Using the Table Controls in Getting Started with IPAM.

Adding a MAC address

After opening a MAC Address Filter as described above,

  1. Click the Add (+) icon above the table.
  2. Enter the desired MAC address.
  3. Optionally, you may set an expiration time at which this MAC address will be automatically removed from the MAC Address Filter.
  4. Click “Next” at the bottom of the dialog window.
  5. Optionally, you may enter a username in the “Register as User” field to associate with this MAC address (for your own tracking purposes).  If you don’t want to do this, just leave it blank.

  6. Click “Save & Close”.

Removing a MAC address

After opening a MAC Address Filter as described above,

  1. Select the checkbox for the MAC address you wish to remove (making sure no other checkboxes are selected).
  2. Click the Delete (trash can) icon above the table.
  3. If you’re sure, click “Yes” when the confirmation dialog appears.

IPAM Training Quick Reference

go.illinois.edu/ipamtraining (this page)

  1. Open https://dev.ipam.illinois.edu
  2. Double-check that the login screen says “DEVELOPMENT GRID”!
  3. Click “SSO Login” or see go.illinois.edu/ipamlogin for detailed login instructions
    (If you don’t have any Contacts Database permissions, contact hostmgr to request demo access to dev.ipam)
  4. Follow along with the live training instructions or the self-guided tutorial in Getting Started with IPAM

Dummy Objects

Dummy objects (in development grid only) that everybody has permissions on, for training purposes:

  • sandbox.illinois.edu
  • 192.168.0.0/26 (sandbox-net)
  • 2001:db8::/64 (sandbox-net)
  • sandbox-macfilter

Sample dig commands

  • dig @dev.ipam.illinois.edu hostname.sandbox.illinois.edu IN A
    (variations: “IN AAAA”, “IN CNAME”, “IN any”, etc)
  • dig @dev.ipam.illinois.edu -x 192.168.0.5

IPAM Service Documentation

The service documentation at go.illinois.edu/ipam contains step by step instructions for common tasks.