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.13.7. 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, 2.12.3, 2.13.6

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 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.13.6) 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.13.6/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.13.6/grid'
  
  curl -b ${COOKIE_JAR:?} -X GET 'https://ipam.illinois.edu/wapi/v2.13.6/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.13.6/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.13.6/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.13.6/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.13.6/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:

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

  curl --user yournetid@illinois.edu -X POST 'https://dev.ipam.illinois.edu/wapi/v2.13.6/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.13.6/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.13.6/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 (https://requests.readthedocs.io/en/latest/)
• 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.  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.io/)

• ipam-provider.yml
  Helper playbook for IPAM automation using Ansible 2.8+
• add-ipam-host.yml
• delete-ipam-host.yml
• add-ipam-a.yml
• delete-ipam-a.yml
• add-ipam-aaaa.yml
• delete-ipam-aaaa.yml
• add-ipam-cname.yml
• delete-ipam-cname.yml

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.

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.

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

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

Introduction

IPAM, which stands for “IP Address Management”, is the integrated platform used by IT professionals to manage DNS and DHCP configuration for their networks and authoritative zones served by campus DNS and DHCP.

The user interface for IPAM is called Grid Manager.

How do I gain access to IPAM?

IT Professionals listed in Contacts Database with the “DNS Requests” permission for one or more network(s) and/or domain(s) may log in to IPAM Grid Manager and make changes to objects and records within those network(s) and domain(s).

The preferred way to obtain Contacts Database permissions for an existing network or domain is to contact the person responsible for that network or domain and ask them to grant you permissions.  If you cannot identify this person, feel free to contact hostmgr@illinois.edu for help.  Please note, however, that bulk permission change requests should be submitted to the Contacts Database team via consult@illinois.edu.

Updated permissions in Contacts Database are automatically read and imported into IPAM nightly.

Employees with a home campus other than Urbana must have an account in the Urbana UofI Active Directory in order to access IPAM.

About Contacts Database

Contacts are the people (or distribution lists) who should be informed when problems or questions arise regarding this network or domain:

• The Primary contact is the technical person who has operational (day-to-day) responsibility for the item and will be contacted first regarding any questions or problems.
• The Backup contact will be contacted if the Primary contact is unavailable or does not respond.
• The Administrative contact is managerial rather than technical (typically a department head or business manager), representing the unit that owns the item and pays for it (where applicable).  They will be contacted for help re-establishing Primary and Backup contacts if the ones listed are out of date or not responding.
• You may list more than one Primary, Backup, or Administrative Contact.
• Please list at least two Primary/Backup contacts (i.e. two Primary or one of each) and at least one Administrative contact.
• Please do NOT list the same person in multiple contact roles.
• You may also list contacts of type “Other” who are allowed to view the item in Contacts Database but who will generally not be contacted with questions about it.
• To avoid confusion, don’t use the Service-specific contact types “Service Owner” and “Service Liaison” for Networks and Domains.  (If these are present, we will treat them as type “Other”.)

Permissions identify the Active Directory users (or groups) who are allowed to manage this network or domain:

• Change Contacts permission-holders can update the information in Contacts Database (which includes granting and revoking permissions), and are expected to keep this information up to date as people leave the University, change jobs, etc.
• DNS Requests permission-holders can perform self-service tasks in IPAM Grid Manager and request non-self-service changes from hostmgr@illinois.edu.  Note that requests for certain major irrevocable changes such as deactivating a domain or transferring it to another owner will be reconfirmed with a Primary contact (unless originated by a Primary contact).
• Networks in CDB may also have other types of permission which are used to manage access to other services.

Note that Contacts and Permissions are entirely separate concepts; it is common to grant Permissions to the same people who are Contacts, but not required.

See Contact Types in Contacts Database (CDB) for more information.

How do I log in?

Visit https://ipam.illinois.edu and click the “SSO Login” button (without entering anything in the text boxes) to authenticate using Shibboleth single sign-on.

• Multi-Factor Authentication (MFA) is required.
• See Linking a Secondary Account for Multi-Factor Authentication (MFA) if you perform IPAM tasks using a “secondary” AD account.
  • After configuring the alias in the NetID center, please additionally email TechServices-IAMU@illinois.edu to request that your secondary account be enabled for MFA in Azure.
• See also Identity Management, Troubleshooting and Solutions for using Urbana Single Sign-On Pages.

When the Shibboleth identity provider redirects you back to IPAM, you will be automatically logged in and should see a (fairly sparse) dashboard page.  If you instead end up back at the IPAM login screen, or if you see “Error: ‘Auto Create User’ option disabled, login denied”, this probably means you don’t currently have permissions to access IPAM (see How do I gain access to IPAM? above).

Technical notes:

• The “SSO Login” button requires your browser to briefly connect to an additional non-standard HTTPS port (8765/tcp) on the Grid Manager server, which may not work if you are behind a firewall that restricts outbound connectivity.

Alternative Login Method

If you experience difficulties using SSO Login, you can also authenticate to the web GUI using your full Active Directory userPrincipalName (typically yournetid@illinois.edu) and the regular “Login” button.

• Multi-Factor Authentication (MFA) is still required.  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.

• For UIC and UIS employees, be sure to enter the userPrincipalName of your Urbana UofI Active Directory account (typically yournetid@illinois.edu), not yournetid@uic.edu or yournetid@uis.edu

Your user profile for the Alternative Login Method will not reflect any customizations you have previously made while using SSO Login, nor vice versa.  See this known issue for details.

How do I log out?

Your Grid Manager session will automatically log out if it is idle for over 4 hours.  To log out manually, click the drop-down control labeled with your username in the upper right-hand corner of the interface, and select “Sign Out”.

In either case, logging out from IPAM does not end your Shibboleth identity provider session, which means you may still be able to click “SSO Login” and get right back in again.  You can prevent this by additionally visiting https://shibboleth.illinois.edu/idp/profile/Logout or by completely closing your web browser (see also Logging out of individual web applications with Shibboleth).

How soon will my changes take effect?

Many changes made in Grid Manager take effect instantly. Other changes (e.g. creating a DHCP Range) take effect only after a behind-the-scenes service restart, which will automatically occur within 5 minutes of making such a change.

Keep in mind that DNS records are routinely cached in accordance with their TTL (time-to-live) values.  Even though authoritative DNS record changes take effect instantly in IPAM, some clients may continue to see the old record data until it has expired from all caches.

If you don’t want your changes to take effect immediately, see the section on Scheduled Tasks in Advanced Tips and Tricks.

Getting started and navigating the interface

New users should start at Getting Started with IPAM. This page contains basic information about navigating the Grid Manager web interface once you have logged in.

DNS Configuration Tasks

Host Records explains how to create, edit, and delete Host records.

Stand-alone DNS Records explains how to create, edit, and delete all other types of DNS records.

DNS Traffic Control explains how to dynamically adjust DNS query responses based on server health checks.

DHCP Configuration Tasks

DHCP Ranges (Dynamic Pools) explains how to configure a pool of IP addresses that can be assigned interchangeably to any eligible DHCP client.

DHCP Fixed Addresses explains how to configure an individual IP address for use exclusively by a single DHCP client.

Managing DHCP Leases contains information about working with leases, which represent the allocation of a particular IP address to a particular client for a specified period of time.

Advanced Features

Advanced Tips and Tricks contains some additional tips to help you use Grid Manager more efficiently. These tips will be most helpful to users who have already logged in once or twice and have familiarized themselves with the basics. If you’re just getting started with Grid Manager, we recommend you skip this section for now and come back to it later on.

CSV Imports and Exports gives instructions on how to to perform “bulk” updates which create or modify many DNS and/or DHCP objects at once.

Using the IPAM API contains information about using Grid Manager’s application programming interfaces.

Customized Training

If you’d like free, customized training for your particular unit or department about how to manage DNS and DHCP using Grid Manager, contact hostmgr@illinois.edu.

Known Issues

Known Issues contains information about known issues with Grid Manager that may be relevant to campus network administrators.

Production IPAM

Production IPAM Grid Manager is located at https://ipam.illinois.edu/

See Using IPAM for instructions.

Development IPAM

The development IPAM system located at https://dev.ipam.illinois.edu/ is a good place to safely experiment with new CSV imports, API scripts, or interface features you haven’t used before. Please note that we enable IT Pros to use dev.ipam on an “as is” basis, with the important caveats that it is not always available, often contains data that is inaccurate or extremely out of date, and may be completely overwritten at any time without warning.

dev.ipam is not reachable from off-campus, so you may need to use the VPN.

The following dummy objects exist only in dev.ipam, with permissions granted to all users for training purposes:

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

Test authoritative DNS queries sent to dns-dev1.techservices.illinois.edu (from on campus) will be answered using the data configured in dev.ipam:

dig +norecurse @dns-dev1.techservices.illinois.edu foo.sandbox.illinois.edu a

dhcpmon

dhcpmon provides graphs for each subnet showing the utilization of dynamically-allocated DHCP addresses over the past day, week, month, and year.

Please note the following limitations:

• actual usage data may be up to 15 minutes older than the graph timestamp
• abandoned lease counts are updated only once per day
• addresses from multiple Ranges are aggregated together
• unused addresses within Reserved Ranges are misleadingly counted as available even though in fact they can never be assigned to a DHCP client (see also Known Issues)

In general, dhcpmon works well for the common case of nets containing a single DHCP Range (with optional Exclusion Ranges).  If your net contains multiple DHCP Ranges and/or any Reserved Ranges, be very careful when drawing conclusions from dhcpmon data.

Domain Request Form

The Domain Request Form is located at go.illinois.edu/domainrequest

See Requesting DNS Domains for more information.

Contacts Database

Network administrators can now keep their identities up to date using Contacts Database.

dig

dig is the preferred client tool for troubleshooting DNS issues because of its flexibility and detailed output. This section is intended as a quick-start guide to help you get it running on your workstation.

See also https://help.dyn.com/how-to-use-binds-dig-tool/

Mac OS X:

• Modern versions of OS X come with dig pre-installed. Just open a Terminal window and run dig.

Linux:

• dig is readily available as a package for most linux distributions. Look for a package called “bind-utils”, “dnsutils”, or “dnstools”.

Windows:

• If you’re comfortable using Windows Subsystem for Linux (WSL), you can install the linux version of dig under WSL.
• The latest versions of BIND unfortunately do not support Windows, but you can still install an older version natively:
  1. Browse to https://downloads.isc.org/isc/bind9/9.16.50/ and download the last stable release of BIND 9 as a Windows zip file (e.g. BIND9.16.50.x64.zip).
  2. Extract the zipfile’s contents to a temporary directory on your workstation.
  3. Run BINDInstall.exe and choose the “Tools only” option (since you don’t want to install the BIND server on your workstation).
  4. Open a Command Prompt and run dig from the directory where you installed it, e.g.

     cd "C:\Program Files\ISC BIND 9\bin"
     dig

     Note that previous versions installed dig under C:\WINDOWS\system32\dns\bin or C:\WINDOWS\SysWOW64\dns\bin

  5. Optionally, you may add the above bin directory to your PATH for convenience (the details of this step are outside the scope of this document, but try searching the web for “set windows path”).

To test that your installation of dig is working, run a simple query:

dig @8.8.8.8 www.illinois.edu a

This should return the IP address of our web server (in the ANSWER section).

Plenty of other documentation has already been written about the details of working with dig; just search the web for “dig tutorial”.
See also the dig manual page.

Host Manager

If you have questions about campus DNS services, email hostmgr@illinois.edu.

Introduction

This document describes the standard as set forth by Technology Services pertaining to the governance and rules of the Domain Name System (DNS) Service at the University of Illinois, Urbana-Champaign campus.

EDUCAUSE and the American Registry for Internet Numbers (ARIN) have delegated second level domains and IP address blocks (respectively) to Technology Services, acting on the authority of the University of Illinois at Urbana-Champaign, with the agreement that DNS service will be properly maintained and configured.

Technology Services provides DNS service to the Urbana-Champaign campus and controls allocation, management and delegation of these zones.

Terminology

American Registry for Internet Numbers (ARIN): An organization that allocates IP address space to the University of Illinois at Urbana-Champaign.
Delegation: handing over authority for a portion of the DNS namespace (thereby establishing a new zone)
Domain: a logical subtree of the hierarchical DNS namespace, headed by a domain name such as illinois.edu or example.com
Domain Name: a string of labels separated by dots which identifies an entity on the Internet. Examples: illinois.edu, example.com, www.techservices.illinois.edu.
Domain Name System (DNS): A method of translating a readable name to an Internet Protocol (IP) address.
EDUCAUSE: Grants .edu domains and offers resources for the advancement of higher education to the education community.
FQDN (Fully Qualified Domain Name): The full entry in DNS for a machine, e.g. host.unit.illinois.edu.
Hostmgr (pronounced “host manager”): role within Technology Services who handles campus DNS change requests
Hostname: A domain name given to a network-attached device.
IP Address: A number to identify a device on a network.
IP Address space/block: A group of IP Addresses.
Subdomain: a logical subset (subtree) of another domain, named by prepending one or more additional labels. Examples: unit.illinois.edu and foo.unit.illinois.edu are both subdomains of illinois.edu.  Note that a subdomain does not necessarily require a separate zone.
Subnet: A subset of an IP address space.
Time to live (TTL): The amount of time the authoritative nameserver caches a record when queried by a caching server.
Third-level name: a domain name consisting of three labels.  Example: unit.illinois.edu.
Zone: a portion of DNS namespace delegated to and configured in a particular set of authoritative name servers.  All subdomains of the apex name are part of the zone unless delegated again to form a new zone.

Roles, obligations, and resources

Units DNS requests and maintenance are processed via the unit’s IT professional for network support (aka network admin).
The IT professional for network support is designated by the unit head in agreement with Technology Services.

To identify your network admin, please contact the Technology Services Help Desk.

The primary contact for DNS for Technology Services is hostmgr at illinois.edu.

General usage of DNS

The use of any domain name or IP address space that is managed by or associated with the University of Illinois at Urbana-Champaign must conform to the policy on Appropriate Use of Computers and Network Systems, which includes a prohibition on use of network resources for commercial or profit-making purposes or other purposes that interfere with the mission of the University.

Inter-unit DNS entries

Units wishing to create pointers from a domain they control to another unit (for example, cs.illinois.edu hostnames pointing into Beckman Institute subnets) should do so in cooperation with Technology Services. Technology Services will set up a discussion so that both groups are aware of the request and can coordinate the use of the new DNS entries.

External domain entries

Units should create and maintain their entries in cooperation with hostmanager, either via delegation or using the self-service management interface. Please see the section on non-.edu domains.

Reverse DNS (in-addr.arpa)

All hosts must have PTR records. This rule is enforced to help the campus be in compliance with industry best practice. As numerous services use PTR records, it can cause considerable problems to users if an IP does not have a matching PTR record.

Time-To-Live (TTL) recommendations

The Time-To-Live (TTL) DNS parameter is used to control how long DNS resolvers cache a DNS record. Setting a TTL value too low reduces the efficiency of caching and increases DNS server traffic/load. Setting a TTL too high means that DNS changes may not be recognized in a timely manner.

The campus standard for TTL records is 1 hour (3600 seconds). Contact hostmgr for changes to a domain’s TTL. TTL changes to individual records can be done by IT Professionals with appropriate access to the record in the IPAM appliance web interface.

Assignment of domains and subdomains

Acceptable Name Guidelines

Units requesting a new third-level name (e.g. xyz.illinois.edu) must meet the following guidelines from the Office of Strategic Communications and Marketing for acceptable domain names. (Pre-existing domains are ‘grandfathered’ under prior guidelines.)

• The domain name can only contain the characters (a-z), -, and (0-9), which complies with the preferred name syntax guidelines in RFC 1035 (Section 2.3.1)
• In general, avoid acronyms and initialisms unless they are universally recognized. For example, creativeservices.illinois.edu not cs.illinois.edu (which could be confused with Computer Science.)
• Supportive of brand – the domain name should not be contrary to the Illinois brand. The UIUC initialism should not be used in newly created domain names.
• Appropriateness – Language which could be considered derogatory, offensive, or misleading should be avoided.
• Respectful of scope and role – Third-level campus domain names should reflect high-level organizations in the university (colleges, departments, inter-departmental organizations,) or campus-wide services (www, campusrec, careercenter). Since third-level names apply at the campus level, the requesting unit must have the authority to represent the organization or service indicated or implied by the name. For example, research.illinois.edu could only be requested by a unit on campus that speaks for all research at the campus level.

Name requests which violate these guidelines must be justified and go through an approval process.

Non-.edu domains

Domains outside the .edu namespace (.org, .net, etc) both incur cost and require the approval of the Office of Strategic Communications and Marketing. The following requirements apply in addition to the normal considerations for domain creations:

• Must be registered through Technology Services.
• Department/Unit pays registration, renewal, and/or transfer fees equal to the amount that Technology Services pays the registrar, plus $10 per year to Technology Services.
• Changes to the domain must be kept to a minimum. There may be an additional fee for excessive changes to the domain. Typical traffic would be an initial set up and a few changes per year.

Approval / escalation process

Technology Services works with the Office of Strategic Communications and Marketing to obtain approval for new domain requests.

Third-level subdomains of illinois.edu

Every third-level subdomain of illinois.edu MUST have a corresponding Domain model in Contacts Database, which must be kept up to date by the responsible department/unit.

Third-level subdomains can be implemented in one of two ways.

Separate zone

A third-level subdomain may be created as a separate DNS zone, which will be made available for self-service management via the IPAM web interface (and may contain an arbitrary number of fourth-level records).

This option has one significant drawback (resulting from an inherent technical limitation of DNS): if mysubdomain.illinois.edu is a separate DNS zone, then there cannot be a CNAME record at mysubdomain.illinois.edu.  In practice, this typically rules out web hosting solutions that do not offer static IP addresses.

Records in the illinois.edu zone

Alternatively, a third-level subdomain of illinois.edu may be registered as a CNAME record in the second-level illinois.edu zone, and accompanied by a small number of fourth-level subdomains (each of which may be either an additional CNAME record or a separate zone).  For example:

• mysubdomain.illinois.edu  (CNAME record in the illinois.edu zone)
• www.mysubdomain.illinois.edu  (CNAME record in the illinois.edu zone)
• etc.mysubdomain.illinois.edu  (separate zone with self-service management)
• name3.mysubdomain.illinois.edu  (either CNAME record or separate zone)
• name4.mysubdomain.illinois.edu  (either CNAME record or separate zone)

Changes to CNAME records in the illinois.edu zone must be made by request to Hostmgr, but fourth-level zones will be made available for self-service management via the IPAM web interface (and may contain an arbitrary number of fifth-level records).

Consider placing records that don’t have specific name requirements (including e.g. dev/test records) underneath a single fourth-level zone.

This option provides somewhat more flexibility for web hosting solutions (since the target of the CNAME record is another domain name, which does not need to resolve to a static IP address).  It is also more lightweight, and therefore generally preferable for new subdomains which do not require a large number of fourth-level records.

Requirements for Third Level Domain Requests

The domain name must follow the Acceptable Name Guidelines and all policies outlined in this standard. The person or group making the request must have a university affiliation (registered organization, staff, faculty, student) and the request should be routed through the unit’s Network Admin.

Requested third-level domains must not already exist and must not be reserved for future use. Contact Hostmanager to check domain availability.

There is no charge for approved third-level subdomains of illinois.edu.

The domain request must include:

• the desired domain name
• a description of the name and purpose
• contact information (considerations for hosted vs. delegated)
• organization codes

See Requesting DNS Domains to start the domain registration request.

After approval, Technology Services will process the request and setup access to the domain through the IPAM web interface, or delegate it to the unit’s servers if requested (see below.) Domain requests will be acknowledged within one business day and processed within 5 business days.

Hosts and domains beyond the third level

Domain names beyond the third level are administered by the unit responsible for the third-level subdomain, subject to the following criteria:

• The names follow the acceptable name guidelines
• The length of any fully qualified domain name does not exceed 255 characters.

Note that separate DNS zones beyond the third level are usually not necessary unless the third level is registered as a CNAME or the fourth level requires delegation.  For example, you can use IPAM to create records named foo.bar.mysubdomain.illinois.edu inside a third-level zone mysubdomain.illinois.edu even though there is no fourth-level zone bar.mysubdomain.illinois.edu.  From the perspective of a DNS client, the end result is the same; the only practical difference is how things look when you log in to manage them in IPAM (i.e. whether you navigate into a separate Zone to look at all the “bar” records, or whether they are displayed in the third-level zone alongside everything else).

Implementation of changes / requests

• Changes submitted via the IPAM appliance web interface will take effect immediately.

• Requests emailed directly to Hostmanager will be hand processed as time allows. Upon completion, Hostmanager will send a completion email to the requestor. We ask that you give your request a full 24 hours for processing and activation.

• Requests that have a sensitive time-line, either during regular business hours or outside of them, should be emailed to host manager and clearly communicated in the body of the email the desired time of activation. We ask that you coordinate all time sensitive requests a full 24 hours in advance.

• Requests to modify TTLs
  The campus standard TTL is set at the domain level and inherited by all records of that domain. The campus standard is 1 hour. This duration can be lowered to help propagate changes to high profile machines (i.e Mail servers, Web servers, etc..) to external nameservers. TTL changes to individual records can be done by IT Professionals with appropriate access to the record in the IPAM appliance web interface; if a TTL change is needed for a record you do not have access to, please contact hostmgr.

Delegation of domains to unit-managed DNS servers

Units may request Technology Services to delegate management of the domain to unit-managed DNS servers. Delegated domains must follow other standards and practices in this document, but are served from unit-managed servers.

Definition of delegation

“Administrative responsibility over any zone may be divided, thereby creating additional zones. Authority is said to be delegated for a portion of the old space, usually in form of sub-domains, to another nameserver and administrative entity.” — Wikipedia entry for DNS

Delegation is appropriate when the unit:

• wishes to use its own tools and servers for managing its DNS records,
• has business requirements that are not met by Technology Services DNS tools,
• has technical integration requirements (such as Active Directory dynamic DNS)

What can be delegated?

• unit third-level domains (e.g. unit.illinois.edu)
• non-university domains (e.g. .org domains registered to the unit)
• reverse IP lookup zones (PTR zones, e.g. 100.168.192.IN-ADDR.ARPA).
  • The DNS architecture requires having 256 address blocks for reverse lookup delegation. Units with less than a 256 address subnet cannot have reverse DNS delegated.

Delegation considerations

In a delegated DNS environment, the unit’s DNS servers are the primary responders to queries to delegated domains.

Because your DNS servers are the authoritative “holders” of your domain information, they should be well-managed and highly available.

Technology Services must have contact information on file for the DNS server administrators.

DNS outages often appear as full network outages, which harm the functionality and image of the university and your unit. The Internet takes DNS seriously and so do we.

DNS servers need to be in the Fully Open firewall group to provide DNS responses to off-campus requests.

Technology Services needs to know if you are using a Windows Active Directory domain controller as the DNS server.

Recommended values for DNS delegations

Technology Services recommends that nameservers for delegated zones be configured with the following values. Note that Technology Services does not prohibit DNS administrators from making other choices, so long as the configuration still complies with the official requirements of delegation (as set forth in the delegation agreement).

Recommended values

SOA values

• Refresh: 1 hour. Exception: If departmental name servers cannot send NOTIFYs to Technology Services name servers, please contact hostmgr to determine an appropriate value.
• Retry: 15 mins
• Expiry: 2 to 4 weeks
• Minimum: 15 mins

TIP: Don’t forget that when modifying a high-profile record (e.g. for a public-facing webserver) it is a good idea to reduce the individual record TTL in advance of making the change (e.g. to a value of 1-5 minutes), and to restore it afterward to the default setting.

Firewall groups for true Delegations

Departmental name servers for true delegations MUST be placed in the Fully Open firewall group to allow udp/53 and tcp/53 from any host (including off campus).

Firewall groups for primary/secondary pseudo-delegations

Any departmental name servers which advertise themselves in an NS RRset SHOULD allow udp/53 and tcp/53 from any host (including off campus).

“Hidden primary” departmental name servers which only participate in primary/secondary pseudo-delegations and are not listed in any NS records MAY allow udp/53 and tcp/53 traffic from off campus but are not required to do so.

Recursion

All departmental name servers must either disable recursion and use the campus resolver (IPv4:130.126.2.131) or restrict recursion to only known hosts.

Delegation request process

Send an email to hostmgr with the required information.

• domains and zones to be delegated
• DNS server names and IP addresses
• Contact information for the zones
• Reason for delegation

Domain lifecycle

Changes to domains

• Domain removal
  If you no longer are in need of a domain associated to you, email Hostmanager. Once the requested date of removal is met, the domain will no longer resolve and (for non-.edu domains) billing will cease.

• Transfers within the University
  If you no longer are in need of a domain and another department or unit would like to be associated with that domain, please contact Hostmanager. Hostmanager will coordinate between both departments to reach an agreement.

DNS technical considerations

Campus resolver IP address

The DNS resolver address for campus is 130.126.2.131.

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.

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.

When creating an MX record:

• 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.
• In the Preference field, enter a priority value for this record. (10 is selected by default)

TXT Records

A text (TXT) record provides the ability to associate arbitrary text with a domain name.  Each TXT record may contain one or more strings (each limited to 255 characters).  Interpretation of the record data is context dependent.

When creating a TXT record:

• In the Text field, enter all desired strings with enclosing double quotes, e.g.

  "one two" " three"

  for a value of two strings, each containing one embedded space character.

• If you enter one two three without double quotes, Grid Manager will treat it as "one" "two" "three" (i.e. three strings with no embedded space characters).

TXT records can be used for many purposes, including but not limited to SPF email authentication.

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.

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.

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 Porkbun home page and search for it.

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.
   • If the domain is close to expiration, also consider renewing it with the current registrar now to ensure it will not expire before the transfer completes.
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 45-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 do 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).

Q: For how many years at a time will a non-.edu domain be renewed?
A: As of May 2026, Technology Services is gradually transitioning non-.edu domains to a new registrar in order to streamline our process and reduce your cost.  Domains held under the new registrar will automatically renew for one year at a time, regardless of the initial registration length, unless otherwise stipulated by top-level domain rules (for example, as of this writing .AI domains require a minimum term of 2 years for registration and renewals).  Any domain still under the old registrar (with a current expiration date during or before Sep 2026) 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.

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.

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

Authentication

Even though they both ultimately derive from the same Active Directory user object, Grid Manager regards `yournetid` (the SAML identity that you use for SSO Login) and `yournetid@illinois.edu` (the userPrincipalName identity that you use for API access and the optional Alternative Login Method) as two separate users who happen to have the same permissions.
This has the following practical consequences:
Each user profile has its own independent set of GUI personalizations, so e.g. Smart Folders or table customizations you create for your SSO Login identity will not be visible when you log in with your userPrincipalName identity (nor vice versa).  This can be a confusing user experience, especially if you frequently switch back and forth, so our general recommendation for most people is to always access the GUI using “SSO Login”.
User profile settings, Smart Folders, Scheduled Tasks, etc that belong to your SSO Login identity cannot be managed using the API.
Here is a partial (not exhaustive) list of user profile customizations you may wish to consider manually recreating when you switch login methods:
(your username in upper-right corner) > Profile: Table Size
Finder > Smart Folders
Finder > Bookmarks
column customizations for various tables (e.g. adding “Network Name” to both Data Management > IPAM and Data Management > DHCP > Networks > Networks)
saved Quick Filters for various tables
“Toggle Advanced Mode” in various dialog boxes
“Toggle flat view” in Data Management > DNS > Zones > Records
“Include Extensible Attributes Values” in Search > Advanced

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.
Workaround: use Advanced Search with Type equals All
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.

Misc

Due to shared implementation logic under the hood, if you try to create a Fixed Address with MAC address 00:00:00:00:00:00, IPAM will silently create a “Reservation” object instead.  This is especially confusing because there is no way to convert a “Reservation” back into a Fixed Address later on; it must be deleted.
Workaround: if you need a dummy placeholder MAC address, consider using one that begins with “02:” (a valid prefix for locally administered addresses).

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

Note that publishing multiple A records for the same name (by adding more than one IPv4 address to a Host) or multiple AAAA records for the same name (by adding more than one IPv6 address to a Host) is legal and results in “round-robin DNS” behavior.

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!

myprefix-192-168-1-10.sandbox.illinois.edu. IN A 192.168.1.10
myprefix-192-168-1-11.sandbox.illinois.edu. IN A 192.168.1.11
...
10.1.168.192.in-addr.arpa. IN PTR myprefix-192-168-1-10.sandbox.illinois.edu.
11.1.168.192.in-addr.arpa. IN PTR myprefix-192-168-1-11.sandbox.illinois.edu.
...