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

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.

   The Name field does not create a DNS hostname! If you want to manage DNS and DHCP for this client together, consider adding DHCP to a Host record instead of creating a stand-alone Fixed Address.

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.

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.

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.

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.

• Create DHCP Fixed Addresses
  Type: Add

  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:

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

Introduction

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

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

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

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

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

This page contains information about navigating the Grid Manager web interface once you have logged in.

Logging In

See How do I log in?

Getting Help

If you have a question not covered by this service documentation, you can try one of the following resources or contact hostmgr for assistance.

Help Panel

All screens and dialog windows in Grid Manager contain context-sensitive help, which appears in the Help panel on the far right-hand side of the window.

1. If the Help panel is not visible, click the grey “?” icon on the far right to expand it.
   
2. Some Help panels contain vertically expanding subpanels.  Expand the subpanel labeled “Help” to see context-sensitive help for the screen you are on.
3. When you don’t need the Help panel, you can collapse it again to save space.

Vendor Documentation

Extensive vendor documentation for Grid Manager is published in HTML and PDF formats.

Please note that not all functionality described in the vendor documentation is available to you in the University of Illinois IPAM service.

Browser Information

The vendor documentation includes requirements for your workstation (including minimum display resolution) and known limitations for certain browsers.

A few general tips:

• Please be patient with the web interface; occasionally it will take a few seconds to finish refreshing after you have clicked on something. Clicking repeatedly will not help, and in fact will probably make you wait longer for the interface to catch up.
• Don’t use your browser’s Back button within Grid Manager.
• Don’t use Grid Manager in multiple tabs or windows of the same browser, as they may interfere with each other.
  (However, we have had success using Grid Manager concurrently in two separate browsers, e.g. in one instance of Chrome and one instance of Firefox.)

The list of OS and browser versions tested and validated by the vendor is now maintained in the release notes (which are not publicly viewable), but generally includes recent releases of Firefox, Chrome, Safari, and Edge.  Let us know if you consistently experience problems with the latest version of any of these browsers, and also whether the problem is solved by using a different browser.  Note that Mozilla offers a Firefox Extended Support Release (ESR) which may be helpful in some circumstances.

Basic Navigation: a Guided Tour

Upon first login, Grid Manager will display the (fairly sparse) Tasks Dashboard, which doesn’t do much but serves as a landing page.

To illustrate some basic principles of Grid Manager navigation, we’ll begin by browsing Networks in DHCP View.  This is not what you’ll usually do in practice, but it’s the simplest place to start.

Browsing Networks in DHCP View

To display Networks in DHCP View:

1. Choose “Data Management” from the top row of tabs.
2. Choose “DHCP” from the second row.
3. Choose “Networks” from the third row.
4. Choose “Networks” from the fourth row.

This will display a table containing all Networks that you have permissions on.

Using the Table Controls

Just above the table in the main workspace is a row of icon buttons.  Mouse over each icon in turn to see their names:
Open, Add, Edit, Delete, Export, and Print.

• To Edit a Network from the table, select the checkbox to its left, and then click the Edit (notepad) icon above the table.

  screenshot

  

  This opens the Edit Network dialog box. You don’t have permissions to change anything in the Edit Network dialog box, but you can use it to examine the DHCP configuration properties of your Network.  To close the dialog box and return to the table, click Cancel (in the lower left).

• To Open a Network from the table, just click directly on its address/CIDR (e.g. “192.168.0.0/26”) in the Network column.  Alternatively, you could select its checkbox and then click the Open (right arrow) icon above the table.  Opening a Network takes you to a new screen which we will discuss in the next section.

The hamburger menu icon in each table row displays a shortcut menu which provides yet another way to Open or Edit the Network in that row.

If your table contains too many rows to display all at once, you can

• use the page navigation buttons (below the table, on the left) to page through them.
  

• start typing the first several characters of a network address e.g. “192” into the “Go to” box (above the table, on the right) to quickly select a matching row. 

  “Go to” only matches one field (whichever one Grid Manager considers to be the primary identifier), so you can’t use it to find e.g. Network Name even if you have added a Network Name column to the table.

• click “Show Filter” and Apply desired filter criteria to display fewer results.  (Note that you can Filter based on Network Name.)

  screenshot

  

Opening a Network (DHCP View)

When you Open a Network as described above, the main workspace displays a new table containing all DHCP-related objects (Fixed Addresses, Ranges, and DHCP-enabled Hosts) that have been configured within that Network.

From here you could go on to perform a variety of DHCP configuration tasks.

For now, just familiarize yourself with the following new interface elements near the top of the main workspace:

• The breadcrumb link “Networks Home” (just below the four rows of navigation tabs) may be used to return to the list of all Networks.
• Next, Grid Manager displays the currently opened object (“192.168.0.0/26”) and its type (“IPv4 Network”).

• Click the nearby blue pencil Edit icon to Edit the currently opened object.

  Note the difference between this blue pencil Edit icon which edits the currently opened object, and the notepad Edit icon further down which edits the object whose checkbox is selected from the table.
• Click the Bookmark (red swallowtail flag) icon to bookmark the currently opened object so you can quickly navigate back to it later (see Advanced Tips and Tricks).
• Click “Go to IPAM View” to Open the current Network in IPAM View (discussed further down) instead of DHCP View.  This is a convenient way to quickly switch between these two views of the same Network.

Opening a Zone

When you open a DNS Zone object as described above, the main workspace displays a table containing either the Records or the Subzones within that Zone (depending on which tab you select from the fourth row underneath the Zone name).

Note the following controls near the top of the main workspace:

• Multiple breadcrumb links allow quick navigation to any ancestor of the current zone, including the DNS View (“default”).  “DNS Home” may be used to return to the list of Views.

• Click “Toggle flat view” on the Records tab to change the way Host records are displayed in this table.  After you click it, the link text changes to “Toggle hierarchical view”.

  We recommend using Flat view for the Records tab, to ensure that you will always see all manifestations of Host records.

• Optionally (and independently), click “Toggle flat view” on the Subzones tab to display all descendants of the current zone instead of only its immediate children (note that this may cause the interface to respond more slowly).  Navigate back up to “edu” for a clear illustration of the difference.

Browsing Networks in IPAM View

IPAM View is another way of looking at Networks.  Whereas DHCP View is narrowly focused on DHCP functionality, IPAM View combines configuration data from both DNS and DHCP into a holistic picture of how every IP address in a network is being used (or not – it also displays unused IPv4 addresses).  IPAM View also shows Network Containers which organize Networks into a hierarchical tree structure.

To browse Networks and Network Containers in IPAM View (again, this is intentionally not the quickest method):

1. Choose “Data Management” from the top row of tabs.

2. Choose “IPAM” from the second row.

3. The main workspace will display any top-level Network Containers (shown with a folder icon) which contain at least one Network that you have permissions on.  Note that you don’t have permissions on the Network Container itself, so you can’t see any other details about it.

   screenshot

   

   This is a separate table from the one we saw earlier in DHCP View, so you’ll want to add the Network Name column again here.

4. Open a Network Container by clicking its address/CIDR.  At this point a third row of tabs appears with “Net Map” selected by default, and the workspace displays a graphical visualization of the contents of this Network Container (which may include other Network Containers and/or leaf Networks), subject to your permissions.

5. Choose “List” from the third row of tabs to display the contents of this Network Container in a table instead.

   screenshot

   

   Note that Network Containers have a folder icon, while leaf Networks have an icon with no folder.  There is also a “Toggle flat view” link which behaves similarly to the one described above for DNS Subzones.

6. Open a leaf Network by clicking its address/CIDR.

Opening a Network (IPAM View)

When you open a leaf Network in IPAM View, you can choose “IP Map” from the third row of tabs to display a graphical representation of how each address in the network is used, or choose “List” to display the addresses in a table (generally more useful).

From here,

• Click “Go to DHCP View” to open the current Network in DHCP View (instead of IPAM View).  This is a convenient way to quickly switch between these two views of the same Network.

  In general IPAM View is more powerful, but some DHCP configuration tasks can only be performed (and others are easier) in DHCP View.

• If you select an IP address which is used by only one object, you can click the Edit (notepad) icon above the table to Edit that object.

• Open an IP address (by clicking on it in the table) to display all of its Related Objects in a new table where you can Edit or Delete them individually.  Use the breadcrumb links to return.

  screenshot

  

• Be very careful with the Reclaim button (see Reclaiming Objects Associated with IPv4 and IPv6 Addresses in the vendor documentation).  When in doubt, it’s safer to examine the Related Objects individually and make a decision about whether to edit or delete each one.
• Please do not use the Ping button (see known issues involving Discovered Data).

Global Search

The step-by-step browsing methods above are very helpful for learning how Grid Manager works, but they aren’t usually the quickest way to reach your goal.  Grid Manager provides several practical navigation shortcuts, the most important of which is Global Search.  (Some others will be discussed later in Advanced Tips and Tricks.)

Click the Search (magnifying glass) button in the upper right-hand corner of the interface window to open the Search dialog box.

Use Basic Search to quickly locate objects matching a specific IP address, MAC address, or DNS Name:

1. Select the “Basic” tab.

2. Click the left-most drop-down (“Choose Filter”) and select DNS Name, IP Address, or MAC Address.
3. Optionally select a different operator from the middle drop-down.

4. Type the desired search value in the text box on the right.
   Please note:

   • MAC Address values should be punctuated with colons, e.g. “aa:aa:aa:00:00:10“

   • When searching by DNS Name, try to use at least a partially-qualified name.  For example, searching for “www.techservices” is much more efficient than searching for “www“.

5. Click “Search”.
   (see screenshot under examples below)
   

or use Advanced Search for other types of searches:

1. Select the “Advanced” tab.

2. In the first filter criterion (Type equals All), click the right-most drop-down (All) to select what type of objects you want the search to return, such as “All Networks” or “All Zones”.

   If you do not filter by Type, then by default Grid Manager will search ALL objects in its database. While you might need to do this on rare occasions (if you aren’t able to find what you want using a more specific search), it takes a lot longer, and is also more likely to return a large number of uninteresting results.

3. Type your desired search value into the main (unlabeled) text box above the filter criteria.  You can enter a regular expression in this field; see Supported Expressions for Search Parameters in the vendor documentation for details.

4. Check “Include Extensible Attributes Values” in case the value you are searching for appears in an extensible attribute (such as Network Name).  If you leave this unchecked, only built-in object fields will be searched.

5. Optionally click “+” to add more filter criteria.
6. Click “Search”.
   (see screenshot under examples below)

Once your search results are displayed, you may:

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

• 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/)

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

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.

The primary purpose of Lease objects is to track the state of IP addresses which are dynamically allocated from a DHCP Range. “Active” indicates a dynamically assigned lease which is still valid (i.e. has not yet expired), while “Free” or “Backup” indicates an address which is currently available for allocation.  “Abandoned” indicates an address which cannot be leased by DHCP because it is (or was) already in use on the network; see Abandoned Leases for more detail.

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

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.

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.

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

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

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.