DEVELOPMENT SERVER: content may be inaccurate

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.

Known Issues

This page summarizes known issues with IPAM Grid Manager that may be relevant to campus network administrators.

Authentication

Discovered Data

  • Please avoid using the “Ping” (and “Multi-Ping”) toolbar buttons within IPAM.  Successful pings have the side effect of storing “Discovered Data” for the IP which unfortunately cannot be cleared using normal permissions; it must be cleared by hostmgr (or a nightly automated script) on your behalf.  This Discovered Data can inconvenience you in several ways, including manifesting visually in IPAM as a purported “conflict” or “unmanaged” address, and/or preventing you from creating a Range.

Leases

  • In IPAM view (Viewing Leases in a Network), “Static” Leases from Fixed Addresses or DHCP-enabled Hosts are only displayed if the IP in question happens to fall within a DHCP Range.
  • Depending on your individual network permissions, some users may experience a significant delay and eventual timeout when clicking on the Current Leases tab.  The text of the error message is:
    “The system is taking longer than expected to complete your request. The system will continue to process any changes you made in the background. Please wait, then check whether your changes were applied. If you did a search, please refine your query and retry your request.”
    Workarounds:
    • wait for it to time out, then apply a Filter (e.g. “IP Address” “begins with” …) to limit the scope of the query
    • use one of the other two methods described in Managing DHCP Leases instead
  • Grid Manager does not appropriately account for Abandoned Leases when calculating the DHCP utilization statistics (per Range and per Network) which are shown in Grid Manager, returned by the API, tracked by dhcpmon, and used to trigger DHCP Threshold Email Alerts.  For example, a Range which contains 90% Active Leases and 10% Abandoned Leases will not generate an alert because Grid Manager considers it to be only 90% utilized, even though live clients may be unable to obtain a lease (depending on how many of the Abandoned Leases are actually still in use on the network).
    Workarounds:
    • dhcpmon has been enhanced to display the most recent Abandoned lease count per network (data updated once per day)
    • hostmgr now receives automated notifications regarding networks which are over 95% full including Abandoned leases, so we can manually reach out to CDB network contacts to let them know when this problem has become serious
  • Addresses within Reserved Ranges are counted (along with DHCP Ranges) in the per-Network DHCP Utilization statistics shown in Grid Manager, returned by the API, and tracked by dhcpmon.  Consequently, the presence of Reserved Ranges may cause a network to appear less full than it actually is.  This does not affect Email Alerts (which apply individually to each Range).
    • Workaround: Edit the Reserved Range and check “Disable for DHCP”.

Search

  • Basic Search for DNS Name does not currently find Host Aliases.
  • Advanced Search for an IPv6 address will only succeed if you enter the exact string representation of the address that Grid Manager uses internally.  For example, you will not find “2620:0:e00:b::53” by searching for “2620:0000:0e00:000b::53” (extra leading zeros) or “2620:0:e00:b:0:0:0:53” (no double colon abbreviation), even though these are all valid representations of the same IPv6 address.
    • Workaround: use Basic Search by IP Address instead.

DNS Traffic Control

  • DNS Traffic Control may return your fallback records (instead of synthesized responses) for about 1 second after a restart of services in which other DTC configuration changes are being applied, even if those changes have nothing to do with your LBDN.  Mitigation: choose good fallback records.
  • Grid Manager currently displays fallback records in normal font instead of strikethrough font

Misc

Requesting DNS Domains

Requesting New DNS Domains

Your group or organization is not limited to the domains that the University already has defined. We are able to host additional domains that fit the University mission, subject to the rules and requirements described in DNS Standards.

Use the Domain Request Form to request either an .edu subdomain (sample.illinois.edu or sample.uillinois.edu) or a new non-.edu domain (.org, .com, etc) for which you have a University-related need.

Naming Guidelines

Consult the Acceptable Name Guidelines to assist you in picking out names that conform to University policy.

To see if a non-.edu domain you want is available (prior to submitting your request), you can go to the Network Solutions home page and search for it.

Please do not attempt to actually purchase the domain from Network Solutions or any other domain granting institution. The University host manager must be involved in the requesting of the domain in order for our DNS servers to provide the service.

Transferring an Existing Domain

To transfer an existing non-.edu domain to University ownership from another registrar:

  1. Contact the domain owner, and ask them to unlock the domain for transfer and provide you with the transfer authorization code.
  2. Once you have the code, complete the Domain Request Form.  Note that you will need to provide:
    • the transfer authorization code
    • is the domain currently in active use, or is a lengthy disruption in service acceptable?

      If the domain is in active use, we will work with you to perform a seamless migration which ensures that live DNS queries for the domain continue to resolve without interruption, and with consistent answers, at all times during the transfer process.

      If you indicate that a lengthy disruption in service is acceptable because nothing actively depends on this domain right now, we can follow a simpler process which involves less work for both you and us.

  3. For seamless migrations, Technology Services will work with you to import the domain’s current zone data into our nameservers, and then ask you to update the NS records with the current registrar.

    It is important to migrate all of your domain’s DNS records (not just the address record for your website) unless you are certain that you don’t need them anymore.

    Once you have provided the current zone data, do not make any further changes to your DNS records until we confirm that it is safe to do so.

  4. To process your order, an authorization email will then be sent to the the current Administrative Contact of Record (as identified by WHOIS). The Administrative Contact must authorize the transfer within 14 days of receipt of the email. Once our registrar receives this authorization, your request will be submitted to the registry to finalize the transfer.
  5. If for some reason your transfer fails, we will notify you and work with you to retry the transfer. Common reasons why registrars will reject a transfer include:
  • Domain name is within 60 days of initial registration
  • Domain name is within 60 days of a previous transfer
  • No response/negative response to transfer authorization request to current Administrative Contact of RecordIf the transfer still does not succeed after all reasonable efforts have been made, Technology Services will provide at least 7 days notice before removing the zone from our nameservers, to allow you time to update your NS records again.

Please note: the transfer process can take up to two weeks from the time we initiate the transfer.

For other questions about transfers, please email hostmgr.

Automatic Renewals

Non-.edu DNS domains registered through Technology Services are automatically renewed by the registrar 60-90 days before they are scheduled to expire.

The Primary and Administrative contacts listed for the domain in Contacts Database will receive a notification email prior to each auto-renewal, but will NOT need to respond affirmatively in order for the auto-renewal to proceed (this eliminates unnecessary workflow steps for you and for us, and reduces the risk that a domain registration will unintentionally be allowed to lapse).

If you no longer wish to renew a non-.edu domain, please inform hostmgr at least 91 DAYS PRIOR TO ITS EXPIRATION DATE (or sooner if that deadline would fall on a non-business day) to ensure that the change can be processed before the next auto-renewal occurs.  Choose one of the following options:

  • Disable renewal but keep the domain in service until it expires.
  • Deactivate the domain immediately.

Note that removal requests should come from a Primary contact if possible (otherwise we will attempt to reconfirm with a Primary contact).

By choosing to disable renewal but keep the domain in service, you accept full responsibility for any disruption that may occur when the domain expires.  You will NOT receive any further notification from Technology Services when this is about to happen.  As a best practice, we recommend leaving automatic renewal enabled until you are actually finished using the domain.

Q: For how many years at a time will a non-.edu domain be renewed?
A: Each domain will automatically renew for the same duration as its current term, i.e. a domain most recently purchased or renewed for 3 years will auto-renew for 3 years.  If you wish to adjust this cadence, you can contact hostmgr to request a one-time manual renewal for a new term of 1, 2, 3, or 5 years (which will immediately extend the current expiration date by that amount).

Q: Which CFOP will be billed for the renewal fee?
A: Each non-.edu domain has a CFOP on file which is billed $10 per year plus renewal fees equal to the amount that Technology Services pays the registrar (as specified in DNS Standards).  Contact hostmgr if you wish to change the CFOP to which your domain is billed.

Managing DNS for your Domains

Once your domain has been created, you can use IPAM to create and modify most types of DNS records; see Using IPAM for detailed instructions.

Other Information

DNS Basics (KB#47914) is written for a general audience, and briefly explains what a DNS server is used for and which IP addresses are used for the campus DNS servers.  Note that most users will not ever need to change their computers’ DNS settings.

DNS Standards contains information about implementation details related to the campus domain registration policy.