- Overview of Cisco IoT Field Network Director
- Installing Cisco IoT FND
- Generating and Installing Certificates
- Managing User Access
- Managing System Settings
- Managing Devices
- Managing Firmware Upgrades
- Managing Tunnel Provisioning
- Monitoring System Activity
- Managing High Availability Installations
- Troubleshooting IoT FND
Managing Tunnel Provisioning
This section describes how to configure IoT FND for tunnel provisioning, and how to manage and monitor tunnels connecting FARs (CGRs and C800s) and HERs, and includes the following topics.
■Configuring Tunnel Provisioning
Overview
IoT FND sends the commands generated from processing the tunnel provisioning templates to FARs and HERs to provision secure tunnels between them. The default IoT FND templates contain CLI commands to set up and configure GRE and IPsec tunnels.
Figure 1 Tunnels Connect FARs and their Corresponding HERs
To provision tunnels between HERs and FARs, IoT FND executes CLI tunnel configuration commands on these devices. By default, IoT FND provides basic tunnel configuration templates containing the CLI tunnel configuration commands. You can also use your own templates. Although the tunnel provisioning process is automatic, you must first complete the configuration steps outlined in Tunnel Provisioning Configuration Process. After that, whenever a FAR comes online, IoT FND automatically provisions it with a tunnel. Before you configure IoT FND for tunnel provisioning, ensure that the IoT FND TPS Proxy is installed and running.
Tunnel Provisioning Configuration Process
You must generate the keystore files on the IoT FND and TPS Proxy before configuring tunnel provisioning. Then, you configure IoT FND and the TPS Proxy to talk to one another (Setting Up the TPS Proxy and Configuring IoT FND to Use the TPS Proxy).
To configure IoT FND for tunnel provisioning:
After completing the previous steps, deploy the FARs and power them on. Tunnel provisioning happens automatically.
This is the sequence of events after a FAR is turned on:
1. Upon joining the uplink network after being turned on, the FAR sends a request for certificate enrollment.
2. The FAR then requests tunnel provisioning to IoT FND through the IoT FND TPS Proxy.
3. IoT FND looks up the FAR record in the IoT FND database and determines which tunnel provisioning templates to use. IoT FND also looks up which HERs to which to establish a tunnel.
4. For Cisco IOS CGRs, the default templates configure the CGR to use FlexVPN. The FlexVPN client is configured on the CGR that will contact the HER and ask for a FlexVPN tunnel to be dynamically constructed. This is how the HER dynamically adds a new tunnel endpoint interface for the CGR.
5. Before processing FAR templates, IoT FND processes the HER Tunnel Deletion template and sends the resulting commands to the HERs. This is done for each HER to remove existing tunnel configuration that may be associated with the FAR.
6. IoT FND uses the FreeMarker template engine to process the FAR Tunnel Addition template. The engine converts the templates to text, which IoT FND assumes to be CLI configuration commands (CG-OS or Cisco IOS, per the CGR). IoT FND uses these commands to configure and bring up one end of the tunnel on the FAR.
7. IoT FND uses the FreeMarker template engine to process the HER Tunnel Addition template. The engine converts the templates to text, which IoT FND assumes to be commands for configuring the tunnel on the HERs.
The specified URL uses the IoT FND registration port (default 9121) instead of the tunnel provisioning port. The Fully Qualified Domain Name (FQDN) in that URL is different and resolves to an IP address that is only reachable through the tunnels.
Configuring Tunnel Provisioning
This section describes how to configure IoT FND for tunnel provisioning.
■Configuring the DHCP Server for Tunnel Provisioning
■Configuring DHCP for Tunnel Provisioning Using CNR
Configuring the DHCP Server for Tunnel Provisioning
For tunnel provisioning to succeed, configure the DHCP server used by IoT FND to supply addresses to create tunnels between the FARs and HERs. For example, configure the DHCP server to provide IP addresses for tunnel provisioning on a permanent-lease basis.
IoT FND makes the DHCP requests based on the settings defined in the tunnel provisioning templates. During tunnel provisioning, the IoT FND templates can make two kinds of DHCP requests:
■Request an IP address, and then make it available to the template.
■Request a subnet with two IP addresses, and then make both addresses available to the template.
IoT FND can make these requests for IPv4 addresses and IPv6 addresses.
The ability to request DHCP addresses from the template gives you maximum flexibility when defining tunnel configurations because you allocate the exact address needed for each FAR and corresponding interface on the HER. The default tunnel provisioning templates provided address the most common use case: one IPsec tunnel between the FAR and its corresponding HER. Each end of this IPsec tunnel gets a dynamically allocated IPv4 address:
■If your DHCP server supports subnet allocation, use it to obtain two addresses that belong to the same subnet.
■If your DHCP server only supports address allocation, configure it so that the two DHCP address requests return addresses that can be used as ends of an IPsec tunnel.
■If your routing plan calls for allocating unique IPv4 addresses for each FAR and assigning it to a loopback interface above the IPsec tunnel, allocate this address using the IoT FND template.
If you choose to build IPv6 GRE tunnels, allocate the IPv6 addresses for each end of the tunnel using DHCP prefix delegation or individual address requests.
This section describes example DHCP settings for tunnel provisioning. How you configure these settings depends on your installation. This section provides general guidelines for configuring the DHCP server for tunnel provisioning using the Cisco Network Registrar (CNR).
Configuring the DHCP Client Listen Address for Red Hat Linux 7.x Installations
In Red Hat Linux 7.x installations, you must configure specific IPv4 and IPv6 addresses on the IoT FND Linux host server for binding DHCP IPv4 and IPv6 clients by setting the following fields on the Admin > Provisioning Settings page (Provisioning Settings Page Client Listening Fields):
■ DHCPv6 Proxy Client > Client Listen Address: Set the value to the IPv6 address of the interface to use to obtain IPv6 DHCP leases from the DHCP server. The default value is “::”. Change the default setting to an actual IPv6 address on the Linux host machine.
■ DHCPv4 Proxy Client > Client Listen Address: Set the value to the IPv4 address of the interface to use to obtain IPv4 DHCP leases from the DHCP server. The default value is “0.0.0.0”. Change the default setting to an actual IPv4 address on the Linux host machine.
Figure 2 Provisioning Settings Page Client Listening Fields
Configuring DHCP for Tunnel Provisioning Using CNR
The CNR CLI script in the following example configures the CNR DHCP server to service requests made by the default tunnel provisioning templates in IoT FND. When using this script, ensure that the subnets are appropriate for your DHCP server environment.
Example CNR DHCP Server Tunnel Provisioning Script
Configuring Tunnel Group Settings
You use groups in IoT FND to bulk configure tunnel provisioning for FARs. By default, all FARs added to IoT FND (see Adding Devices in Bulk) the appropriate default group: default-cgr1000 or default-c800. Default groups contain the three templates IoT FND uses for tunnel provisioning.
Creating Tunnel Groups
If you plan to use one set of templates for all FARs, whether using the default templates, modified default templates or custom templates, do not create additional groups. To define multiple sets of templates, create groups and customize the templates for these groups.
Note: CGRs and C800s can be in the same tunnel provisioning group if your custom templates are applicable to both router types.
1. Choose Config > Tunnel Provisioning.
3. Enter a name of the new group, and then click OK.
The group appears in the TUNNEL GROUPS pane.
After creating a tunnel group, the next step is to move FARs from other groups to it, as described in Moving FARs to Another Group.
Deleting Tunnel Groups
Only empty groups can be deleted. Before you can delete a tunnel group, you must move the devices it contains to another group.
To delete an empty tunnel group:
1. Choose Config > Tunnel Provisioning.
2. In the TUNNEL GROUPS pane, select the tunnel group to delete.
Viewing Tunnel Groups
The Tunnel Provisioning page lists information about existing tunnel groups.
Follow these steps to view the tunnel groups defined in IoT FND:
1. Choose Config > Tunnel Provisioning.
3. In the TUNNEL GROUPS pane, select a group.
IoT FND displays a list of all FARs in the group. Use the list navigation buttons to scroll through the list. Tunnel Group Fields describes the list fields.
Renaming a Tunnel Group
You can rename a tunnel group at any time. Cisco recommends using short, meaningful names. Names cannot be more than 250 characters long.
1. Choose Config > Tunnel Provisioning.
2. In the TUNNEL GROUPS pane, roll over the tunnel group to rename and click the Edit pencil icon ().
3. Enter the new name, and then click OK.
Note: As shown above, when you enter an invalid character entry (such as, @, #, !, or +) within a field, highlights the field in red, and disables the OK button.
Moving FARs to Another Group
You can move FARs to another group in two ways:
Moving FARs to Another Group Manually
To move FARs to another group manually:
1. Choose Config > Tunnel Provisioning.
2. Click the Group Members tab.
3. In the TUNNEL GROUPS pane, select the tunnel group with the routers to move.
4. Choose the device type from the Select a device type drop-down menu.
5. Check the check boxes of the FARs to move.
To select all FARs in a group, click the check box at the top of the column. When you select devices, a yellow bar displays that maintains a count of selected devices and has the Clear Selection and Select All commands. The maximum number of devices you can select is 1000.
6. Click the Change Tunnel Group button.
7. From the drop-down menu, choose the tunnel group to which you want to move the FARs.
Moving FARs to Another Group in Bulk
You can move FARs in bulk to another group by importing a CSV or XML file containing the names of the FARs to move. Ensure that the file contains entries in the format shown the following example:
The first line is the header, which tells IoT FND to expect FAR EIDs in the remaining lines (one FAR EID per line).
To move FARs to another group in bulk:
1. Create a CSV or XML file with the EIDs of the devices to move to a different group.
2. Choose Config > Tunnel Provisioning.
3. Click Assign Devices to Group.
4. Click Browse and locate the file that contains the FARs that you want to move.
5. From the Group drop-down menu, choose the destination tunnel group.
Configuring Tunnel Provisioning Templates
IoT FND has three default tunnel provisioning templates:
■Field Area Router Tunnel Addition—IoT FND uses this template to generate the CLI configuration commands for creating one end of an IPsec tunnel on the FAR.
■Head-End Router Tunnel Addition—IoT FND uses this template to generate the CLI configuration commands for creating the other end of the IPsec tunnel on the HER.
■Head-End Router Tunnel Deletion—IoT FND uses this template to generate the CLI configuration commands for deleting any existing tunnel to the FAR at the other end of the tunnel.
Tunnel Provisioning Template Syntax
The IoT FND tunnel provisioning templates are expressed with the FreeMarker syntax. FreeMarker is an open-source Java-based engine for processing templates and is built into IoT FND. As shown in CLI Command Generation from Templates in IoT FND, FreeMarker takes as input the tunnel provisioning template and data supplied by IoT FND, and generates CLI commands that IoT FND runs on the FARs and HERs in the “configure terminal” context.
Figure 3 CLI Command Generation from Templates in IoT FND
In IoT FND, the tunnel provisioning templates consist of router CLI commands and FreeMarker variables and directives. The use of FreeMarker syntax allows IoT FND to define one template to provision multiple routers.
This section describes the basic FreeMarker syntax in the tunnel provisioning templates. For information about FreeMarker visit http://freemarker.sourceforge.net/.
Template Syntax
Tunnel Provisioning Template Syntax describes the syntax in the default tunnel provisioning templates.
Data Model
This section describes the data model in the tunnel provisioning templates. The far and her prefixes provide access to the properties of the FARs and HERs, respectively. These properties are stored in the IoT FND database. Data Model describes referencing the information provided by the data model in tunnel provisioning templates.
Address References describes referencing addresses in the tunnel provisioning templates.
|
|
---|---|
Configuring the Field Area Router Tunnel Addition Template
To edit the FAR Tunnel Addition template to provide one end of an IPsec tunnel on FARs in the group:
1. Choose Config > Tunnel Provisioning.
2. In the TUNNEL GROUPS pane, select the tunnel group with the template to edit.
3. Click the Field Area Router Tunnel Addition tab.
4. Modify the default template.
Tip: Use a text editor to modify templates and copy the text into the template field in IoT FND.
6. Click OK to confirm the changes.
See also, Tunnel Provisioning Template Syntax.
Configuring the Head-End Router Tunnel Addition Template
Note: To ensure that both endpoints are in a matching subnet, this template must use the same IAID as the FAR template.
To edit the HER Tunnel Addition template to create the other end of the IPsec tunnel on HERs in the group:
1. Choose Config > Tunnel Provisioning.
2. In the TUNNEL GROUPS pane, select a tunnel group.
3. Click the Head-End Router Tunnel Addition tab.
Configuring the HER Tunnel Deletion Template
To edit the HER tunnel deletion template to delete existing tunnels to FARs at the other end of the tunnel:
1. Choose Config > Tunnel Provisioning.
2. In the TUNNEL GROUPS pane, select the tunnel group whose template to edit.
3. Click the Head-End Router Tunnel Deletion tab.
Monitoring Tunnel Status
To view tunnel status, choose Operations > Tunnel Status. The Tunnel Status page lists devices and their provisioned tunnels and displays relevant information about tunnels and their status.
Tunnel Status Fields describes the tunnel status fields. To change the sort order of tunnels in the list by name, click the HER Name column heading. A small arrow next to the heading indicates the sort order.
Note: It takes time for the status of the newly created tunnel to be reflected in IoT FND.
Reprovisioning CGRs
In IoT FND, CGR reprovisioning is a process for modifying the configuration files on CGRs.
Note: C800s do not support reprovisioning.
CGR Reprovisioning Basics
CGR Reprovisioning Actions
In IoT FND, you can perform the following two CGR reprovisioning actions in the Reprovisioning Actions pane of the Tunnel Provisioning page (Config > Tunnel Provisioning).
You can also activate the mesh firmware on this page.
Reprovisioning Actions Pane Fields describes the fields on the Reprovisioning Actions pane.
CGR Reprovisioning Sequence
When you start tunnel or factory reprovisioning on a tunnel provisioning group, the reprovisioning algorithm sequentially goes through 12 CGRs at a time and reprovisions them.
After IoT FND reprovisions a router successfully or if an error is reported, IoT FND starts the reprovisioning process for the next router in the group. IoT FND repeats the process until all CGRs are reprovisioned.
There is a timeout of 4 hours when reprovisioning each CGR in the group. If the CGR does not report successful reprovisioning or an error within the timeout period, then IoT FND changes the Reprovisioning Status of the CGR to Error and displays a timeout error and any further information displays in the Error Details field.
Tunnel Reprovisioning
If you make changes to the Field Area Router Tunnel Addition template and want all CGRs already connected to IoT FND reprovisioned with new tunnels based on the modified template, use the tunnel reprovisioning feature of IoT FND.
Tunnel reprovisioning places the CGR in a state where no tunnels are configured, and then initiates a new tunnel provisioning request. To reprovision tunnels, IoT FND sequentially goes through the FARs (12 at a time) in a tunnel provisioning group. For every CGR, IoT FND rolls back the configuration of the CGR to that defined in the ps-start-config template file.
After a rollback to ps-start-config, the CGR contacts IoT FND to request tunnel provisioning. IoT FND processes the Field Area Router Tunnel Addition template and sends the resultant configuration commands for creating new tunnels to the CGR. As shown in Tunnel Reprovisioning Process, the tunnel provisioning process includes updating the golden-config file to include the new configuration information.
Figure 4 Tunnel Reprovisioning Process
Note: For CG-OS CGRs, a rollback results in a reload of the CGR. Also, when IoT FND rolls back a CGR, IoT FND removes the corresponding tunnel information from the HERs to which the CGR was connected.
You perform a configuration replace for Cisco IOS based CGRs.
Note: The Field Area Router Factory Reprovision template is not used when performing tunnel reprovisioning.
To configure and trigger tunnel reprovisioning:
1. Choose Config > Tunnel Provisioning.
2. In the TUNNEL GROUPS pane, select the tunnel group whose template to provision.
3. Click the Reprovisioning Actions tab.
4. From the Action drop-down menu, choose Tunnel Reprovisioning.
IoT FND changes the Reprovisioning Status field to Initialized, and then to Running.
Note: If you click Stop while tunnel reprovisioning is running, IoT FND stops the reprovisioning process only for the FARs in the queue that were not selected. However, for those CGRs in the queue that were selected for reprovisioning, the process completes (success or error) and cannot be stopped.
The reprovisioning process completes after IoT FND finishes attempting to reprovision each CGR in the tunnel provisioning group. If a CGR cannot be reprovisioned, IoT FND displays the error message reported by the CGR.
Factory Reprovisioning
Use the Factory Reprovisioning feature in IoT FND to change the factory configuration of CGRs (express-setup-config).
Factory Reprovisioning involves these steps:
1. Sending the roll back command to the CGR.
3. Processing the Field Area Router Factory Reprovision template, and pushing the resultant commands to the CGR.
4. Saving the configuration in the express-setup-config file.
After these steps complete successfully, IoT FND processes the Field Area Router Tunnel Addition, Head-End Router Tunnel Addition, and Head-End Router Tunnel Deletion templates and pushes the resultant commands to the CGR (see Tunnel Provisioning Configuration Process).
To configure and trigger factory reprovisioning:
1. Choose Config > Tunnel Provisioning.
2. In the TUNNEL GROUPS pane, select the tunnel group whose template you want to edit.
3. Click the Field Area Router Factory Reprovision tab and enter the template that contains the configuration commands to apply.
Note: The Field Area Router Factory Reprovision template is processed twice during factory reprovisioning; once when pushing the configuration and again before saving the configuration in express-setup-config. Because of this, when making your own template, use the specific if/else condition model defined in the default template.
5. If needed, make the necessary modifications to the Field Area Router Tunnel Addition, Head-End Router Tunnel Addition, and Head-End Router Tunnel Deletion templates.
6. Click the Reprovisioning Actions tab.
7. From the Action drop-down menu, choose Factory Reprovisioning.
8. From the Interface drop-down menu, choose the CGR interface for IoT FND to use to contact the FARs for reprovisioning.
9. From the Interface Type drop-down menu, choose IPv4 or IPv6.
IoT FND changes the Reprovisioning Status field to Initialized, and then to Running.
Note: If you click Stop while factory reprovisioning is running, IoT FND stops the reprovisioning process only for the FARs in the queue that were not selected. However, for those CGRs in the queue that were selected for reprovisioning, the process completes and cannot be stopped.
The reprovisioning process completes after IoT FND has finished attempting to reprovision each CGR in the tunnel provisioning group. If a CGR cannot be reprovisioned, IoT FND displays the error message reported by the CGR.
Sample Field Area Router Factory Reprovision Template
This sample template changes the WiFi SSID and passphrase in the factory configuration.