User Guide for Cisco Network Registrar 7.2

Configuring Policies and Options

This chapter describes how to set up DHCP policies and options. Before clients can use DHCP for address assignment, you must add at least one DHCPv4 scope (dynamic address pool) or DHCPv6 prefix to the server. The policy attributes and options are assigned to the scope or prefix.

See Also

Configuring DHCP Policies
Creating DHCP Option Definition Sets and Option Definitions

Configuring DHCP Policies

Every DHCPv4 scope or DHCPv6 prefix must have one or more policies defined for it. Policies define lease duration, gateway routers, and other configuration parameters, in what are called DHCP options. Policies are especially useful if you have multiple scopes or prefixes, because you need only define a policy once.

This section describes how you can define named policies with specific attributes and option definitions, or use system default or embedded policies.

See Also

Types of Policies
Policy Hierarchy
Creating and Applying DHCP Policies
Cloning a Policy
Setting DHCP Options and Attributes for Policies
Creating and Editing Embedded Policies

Types of Policies

There are three types of policies—system default, named, and embedded:

•System default (system_default_policy)—Provides a single location for setting default values on certain options for all scopes or prefixes. Use the system default policy to define attributes and standard DHCP options that have common values for all clients on all the networks that the DHCP server supports. You can modify the system default options and their values. If you delete a system default policy, it reappears using its original list of DHCP options and their system-defined values (see Table 21-1).

•Named—Policies you explicitly define by name. Named policies are usually named after their associated scope, prefix, or client grouping. For example, the policy might be assigned attributes and options that are unique to a subnet, such as for its routers, and then be assigned to the appropriate scope or prefix.

Cisco Network Registrar includes a policy named default when you install the DHCP server. The server assigns this policy to newly created scopes and prefixes. You cannot delete this default policy.

•Embedded—A policy embedded in (and limited to) a named scope, scope template, prefix, prefix template, client, or client-class. An embedded policy is implicitly created (or removed) when you add (or remove) the corresponding object. Embedded policy options have no default values and are initially undefined.

Tip Be sure to save the object (scope, prefix, client, or client-class) for which you are creating or modifying an embedded policy. Not doing so is a common error when using the web UI. Click Modify for both the embedded policy and the parent object.

Policy Hierarchy

To eliminate any conflicting attribute and option values that are set at various levels, the Cisco Network Registrar DHCP server uses a local priority method. It adopts the more locally defined attribute and option values first while ignoring the ones defined on a more global level, and includes any default ones not otherwise defined. When the DHCP server makes processing decisions for a DHCPv4 client, it prioritizes the attributes and options in this order:

1. Client embedded policy.

2. Client named policy.

3. Client-class embedded policy.

4. Client-class named policy.

5. Scope embedded policy for clients, or address block embedded policy for subnets.

6. Scope named policy for clients (or default policy if a named policy is not applied to the scope), or address block named policy for subnets.

7. Any remaining unfulfilled attributes and options in the system_default_policy. For attributes, the default value for the most local policy applies.

Note For DHCPv6 policy prioritization, see the "DHCPv6 Policy Hierarchy" section on page 26-9.

Creating and Applying DHCP Policies

This section describes how to create a policy at the DHCP server level and then allow specific scopes or prefixes to reference it. A policy can consist of a:

•Name—Not case sensitive and must be unique.

•permanent-leases attribute—A permanent lease never expires.

•Lease time—How long a client can use an assigned lease before having to renew the lease with the DHCP server (the lease time attributes are not available for an embedded policy, only the option). The default lease time for both system default and default policies is seven days (604800 seconds). A policy contains two lease times—the client lease time and the server lease time:

–Client lease time—Determines how long the client believes its lease is valid. (Set the client lease time using a DHCP option, not a policy attribute.)

–Server lease time—Determines how long the server considers the lease valid. Note that the server lease time is independent of the lease grace period. The server does not allocate the lease to another client until after the lease time and grace period expire.

---

Caution Although Cisco Network Registrar supports the use of two lease times for special situations, Cisco Systems generally recommends that you not use the server-lease-time attribute.

---

You can establish these two different lease times if you want to retain information about client DNS names and yet have them renew their leases frequently. When you use a single lease time and it expires, the server no longer keeps that client DNS name. However, if you use a short client lease time and a longer server lease time, the server retains the client information even after the client lease expires. (For details on leases, see Chapter 22, "Managing Leases.")

•Lease grace period—Time period after the lease expires that it is unavailable for reassignment (not available for an embedded policy).

•DNS update configuration—A DNS update configuration specifies the type of DNS updates to perform, the zones involved, the DNS server to be updated, and the related security. The policy determines the forward and reverse DNS update configuration objects, and can also specify the forward zone to use if a DNS server hosts multiple zones. (For details on DNS update configurations, see the "Creating DNS Update Configurations" section on page 28-5.)

•DHCP options—To add option values, see the "Setting DHCP Options and Attributes for Policies" section.

Local Basic or Advanced and Regional Web UI

Step 1 From the DHCP menu, choose Policies to open the List/Add DHCP Policies page.

Step 2 The default policy and system_default_policy are already provided for you. To add a named policy, click Add Policy to open the Add DHCP Policy page.

Step 3 Give the policy a unique name (required).

Step 4 Set the offer timeout and grace period values or leave them blank.

Step 5 Add the necessary DHCP options (see the "Setting DHCP Options and Attributes for Policies" section):

•Lease time—Set the dhcp-lease-time (51) option.

•Subnet mask—Set the subnet-mask (1) option, but also enable the get-subnet-mask-from-policy attribute for the DHCP server. To remove the subnet mask from the policy, either unset the attribute or disable it.

To set vendor-specific options, see the "Using Standard Option Definition Sets" section.

Step 6 Set the policy attributes, which include:

•Unavailable timeout—See the "Setting Timeouts for Unavailable Leases" section on page 22-22.

•Inhibit all renews—See the "Inhibiting Lease Renewals" section on page 22-20.

•Limitation count—See the "Using Expressions" section on page 25-2.

•Use client IDs for reservations—See the "Overriding Client IDs" section on page 22-18.

•Permanent leases (not recommended).

•DNS update settings—To set the DNS update configuration that determines which forward or reverse zones you want to include in a DNS update, set the following attributes:

–forward-dnsupdate—Name of the update configuration for the forward zone. Note that you can thereby set different update configurations for forward and reverse zones.

–forward-zone-name—If necessary, overrides the forward zone in the update configuration. Use this in case a DNS server is hosting multiple zones.

–reverse-dnsupdate—Name of the update configuration for the reverse zone. If not set on any policy in the policy hierarchy applicable to the client request (see the "Policy Hierarchy" section), the DHCP server uses the forward-dnsupdate configuration.

Step 7 Click Add Policy.

Step 8 Reload the DHCP server.

In the regional web UI, you can also pull replica policies and push policies to local clusters. (See the "Managing DHCP Policies" section on page 6-16 for regional policy management.)

CLI Commands

Use policy name create to create the policy. Then use policy name set offer-timeout=value and policy name set grace-period=value to set these two values.

To set policy options, use policy name setOption:

•Lease time—Use policy name setLeaseTime.

•Subnet mask—Use a combination of policy name setOption subnet-mask value and dhcp enable get-subnet-mask-from-policy.

To confirm the option settings, use policy name listOptions or policy name getOption.

To enable permanent leases (not recommended), use policy name enable permanent-leases. Note that enabling permanent leases forces the dhcp-lease-time option (51) to be set to infinite.

See Also

Types of Policies
Policy Hierarchy
Cloning a Policy
Setting DHCP Options and Attributes for Policies
Creating and Editing Embedded Policies
Creating DHCP Option Definition Sets and Option Definitions

Cloning a Policy

In the CLI, you can clone a policy from an existing one by using policy clone-name create clone=policy, and then make adjustments to the clone. For example:

nrcmd> policy cloned-policy create clone=example-policy-1 offer-timeout=4m 

Setting DHCP Options and Attributes for Policies

DHCP options automatically supply DHCP clients with configuration parameters, such as domain, nameserver, and subnet router addresses (see the "Creating DHCP Option Definition Sets and Option Definitions" section). Note that the Cisco Network Registrar user interfaces allow you to set some option values on a policy that actually have no effect on the packet returned to the client (such as hostname and dhcp-server-identifier).

The server searches the policies, in order, for these BOOTP and DHCP attribute values and returns the first occurrence of these values in its reply packet:

•packet-siaddr returned in the siaddr packet field

•packet-file-name returned in the file field

•packet-server-name returned in the sname field

See Also

Adding Option Values
Adding Complex Values for Suboptions

Adding Option Values

You can view, set, unset, and edit DHCP option values. When you set an option value, the DHCP server replaces any existing value or creates a new one, as needed for the given option name. Cisco Network Registrar DHCP options are grouped into categories to aid you in identifying options that you must set in various usage contexts. You can create custom option definitions to simplify entering custom option values (see the "Creating Custom Option Definitions" section).

Local Basic or Advanced and Regional Web UI

Step 1 Create a policy, as described in the "Creating and Applying DHCP Policies" section.

Step 2 On the Add DHCP Policy or Edit DHCP Policy page, add each DHCP option to the policy by clicking its number and name in the drop-down list. The choices indicate the data type of the option value (see the "Option Definition Data Types and Repeat Counts" section).

Tip You can sort the options by Name, Number, or (in the case of DHCPv4) Legacy (grouping).

Step 3 Add the appropriate option value in the Value field. The web UI does error checking based on the value entered. For example, to add the lease time for the policy, click the [51] dhcp-lease-time (unsigned time) option in the Number drop-down list, then add a lease time value in the Value field. (Options do not have preset values.)

Tip If you are configuring an option on a policy while another user is editing the option definition, log out of the session and log back in to get the new option definition.

Step 4 Click Add Option for each option. You must supply a value or you cannot add the option.

Step 5 Click Add Policy.

Tip If you add new option values or edit existing ones, be sure to save the policy object by clicking Modify Policy.

CLI Commands

To view option values, use policy name getOption and policy name listOptions. To set option values, use policy name setOption option. When you set an option value, the DHCP server replaces any existing value or creates a new one, as needed, for the given option name. To unset option values, use policy name unsetOption.

Adding Complex Values for Suboptions

If you are adding more complex option values such as for suboptions, use a parenthesized string format. The format requires that you:

•Enclose each option level (option, suboption, subsuboption) in parentheses.

•Separate multiple values with commas.

•Separate data fields for packed data (missing the suboption code or length) with semicolons.

For example, the cablelabs-client-configuration option (122) normally has 10 suboptions as well as some subsuboptions. This example shows the syntax to set the suboption 1, 2, 3, and 4 data values, and includes the two subsuboptions for suboption 3 and the three subsuboptions for suboption 4 (which are packed data and have no code numbers):

(primary-dhcp-server 1 10.1.1.10) 

(secondary-dhcp-server 2 10.2.2.10) 

(provisioning-server 3 (flag 0; provisioning-server server.example.com.)) 

(as-backoff-retry 4 (as-backoff-retry-initial-time-ms 10; 

as-backoff-retry-max-time 10s; as-backoff-retry-count 100)) 

The suboption name (such as primary-dhcp-server) is optional. Hence, it is often safer to use just the code number and data value (or just the data value for packed data) to minimize typographical errors and parsing failures. The compacted (and preferred) version of the previous example that strips out the suboption names is:

(1 10.1.1.10) (2 10.2.2.10) (3 (0;server.example.com.)) (4 (10;10s;100)) 

Even if you use numerical code values, Cisco Network Registrar always includes the equivalent names when it displays the suboptions (see the "Creating DHCP Option Definition Sets and Option Definitions" section).

To include suboptions that include enterprise IDs (such as for option 125), use the following format, for example, when entering in the policy option value:

(enterprise-id 1((1 10.1.1.1) (2 10.2.2.2) (3 www.cisco.com))) 

The parentheses surround the enterprise ID itself, the suboptions as a group, and each suboption.

Creating and Editing Embedded Policies

An embedded policy is embedded for a DHCPv4 scope or scope template, DHCPv6 prefix or prefix template, client, or client-class (see Chapter 26, "Managing DHCPv6 Addresses," for embedded policies in DHCPv6). You can create or edit an embedded policy.

Local Advanced Web and Regional UI

Step 1 From the DHCP menu, choose one of the following that appear for DHCPv4 or DHCPv6 in the local web UI: Scopes, Scope Templates, Clients, Client-Classes, Prefixes, or Links. (The regional web UI can have the selections Scope Templates, Client-Classes, Prefixes, and Links.)

Step 2 Click the name of the object to open its Edit page.

Step 3 Click Create Embedded Policy or Edit Existing Embedded Policy under the Embedded Policy section of the page. This opens the Edit DHCP Embedded Policy page for the object.

Step 4 Make changes to the values as needed, then click Modify Embedded Policy.

Step 5 On the Edit page for the object, be sure to save the changes by clicking Modify.

CLI Commands

Use the embedded commands, such as client-class-policy client-class-name set attribute=value, where the command starts with the object name followed by -policy.

Creating DHCP Option Definition Sets and Option Definitions

In Cisco Network Registrar, you configure option values on policies for such things as lease times and router addresses. Numerous RFCs describe the formatting of DHCP option values, beginning with RFC 2132. Option definitions are used in the web UI and CLI to control formatting of option values in policies. You can define option definitions separately for the DHCPv4 and DHCPv6 address spaces, as:

•Standard (built-in) options—Defined by the RFCs. In the web UI, these are in the dhcp-config and dhcp6-config definition sets. The CLI includes additional dhcp-default and dhcp6-default definition sets that are hidden, but accessible if you call for them specifically. (See the "Using Standard Option Definition Sets" section.)

•Custom options—New or modified definitions in the supplied dhcp-config or dhcp6-config definition sets. Once you add or modify definitions in the web UI, they are added to the dhcp-custom or dhcp6-custom definition sets in the CLI. (See the "Creating Custom Option Definitions" section.)

•Vendor-specific options—Defined in their own definition sets. The CableLabs definition sets (dhcp-cablelabs-config and dhcp6-cablelabs-config) are preconfigured in Cisco Network Registrar. The CLI also includes dhcp-cablelabs-default, dhcp6-cablelabs-default, dhcp-cablelabs-custom, and dhcp6-cablelabs-custom definition sets. (See the "Using Standard Option Definition Sets" section.)

See Also

Using Standard Option Definition Sets
Creating Custom Option Definitions
Creating Vendor-Specific Option Definitions
Option Definition Data Types and Repeat Counts
Adding Suboption Definitions
Importing and Exporting Option Definition Sets
Pushing Option Definition Sets to Local Clusters
Pulling Option Definition Sets from Replica Data
Setting Option Values for Policies

Using Standard Option Definition Sets

Cisco Network Registrar provides two standard, built-in option definition sets, dhcp-config and dhcp6-config, for DHCPv4 and DHCPv6 option definitions, respectively. You can create new options definitions in these sets or you can overwrite existing ones. New option definitions or ones that were overwritten are identified by an asterisk (*). You can delete these definitions and there is no deletion confirmation given. However, saving the set after deleting an overwritten definition causes the original definition to reappear in the set.

Caution Arbitrarily modifying the standard definitions (or adding suboption definitions) can adversely affect configurations.

Local Advanced and Regional Web UI

Step 1 From the DHCP menu, choose Options to open the List/Add DHCP Option Definition Sets page. (DHCP option definition is not available in Basic mode.)

Step 2 Click the dhcp-config or dhcp6-config link to open the Edit DHCP Option Definition Set page, then click Add/Edit Option Definitions. View the predefined definitions on the List DHCP Option Definitions page. These are the definitions that control the formatting of the option values you add to policies. If there are suboption definitions, you can expand to show them.

Step 3 To add a definition, click Add Option Definition. On the Add DHCP Option Definition page, give the option an ID, name, description, type, and repeat count (whether more than one instance of the option is allowed or required). (For details on the data types and repeat count values, see the "Option Definition Data Types and Repeat Counts" section.)

Note You cannot add an option definition for an option number or name that already exists. However, you can modify any option definition that appears as a hyperlink on the page.

Step 4 Click Add Option Definition. Then, on the List DHCP Option Definitions page, click Modify Option Definition Set.

Step 5 If you modify a standard definition in a set, a Revert icon () appears next to it on the List DHCP Option Definitions page. Click this icon if you want to revert to the original definitions in that standard set.

Step 6 In the regional web UI, you can also pull replica definition sets and push definition sets to local clusters. (See the "Pulling Option Definition Sets from Replica Data" section and the "Pushing Option Definition Sets to Local Clusters" section.)

CLI Commands

To view the entire list of standard DHCP option definitions, use option-set dhcp-config [show] or option-set dhcp6-config [show], or option {id | name} option-set show to view a specific definition. For example:

nrcmd> option-set dhcp-config 

nrcmd> option subnet-mask dhcp-config show 

To add a definition to a set, use option id option-set create name type. You cannot add a definition for an option ID (number) or name that already exists. For example, to add option number 222 with the name example-option in the dhcp-config option set, with a string type, use:

nrcmd> option 222 dhcp-config create example-option AT_STRING 

To get a particular option attribute value, use option (id | name} optionset get attribute. To modify an option attribute, use option (id | name} optionset set. You can also unset an option attribute.

Creating Custom Option Definitions

You can create custom option definitions in the standard sets. Click the dhcp-config or dhcp6-config set on the List/Add DHCP Option Definition Sets page. Then proceed with Step 3 in the "Using Standard Option Definition Sets" section.

Creating Vendor-Specific Option Definitions

You can send vendor-specific option data to DHCP clients that request them.

Note There are several option codes set aside for vendor-specific options, so that you must explicitly specify the option code number for which you are creating a vendor-specific option definition.

In Cisco Network Registrar, you can create vendor-specific option definitions in the web UI, or in the CLI by using option id option-set-name create. (For details on the option data types, see the "Option Definition Data Types and Repeat Counts" section.)

Vendor-specific options are sent in the following DHCP options:

•vendor-encapsulated-options (43)—Set this to a binary data type, then add the vendor-specific suboption definitions. (The data type of the parent option definition is a placeholder only. The suboption definitions define the valid option value formatting.)

•v-i-vendor-info (125) or vendor-options (17) for DHCPv6—Set this to a vendor-opts data type, then add the vendor-specific suboption definitions.

You can create vendor-specific option definitions for DHCPv4 options 43 and 125, and DHCPv6 option 17. You add the vendor-specific option definitions into a vendor option definition set that you create.

Caution Changing option definition properties, or deleting the option definition altogether, can have unexpected side effects on policies. If you delete a custom option definition, also check for the policies that include an option value. Changing an option definition changes the way that they are displayed, not what is stored, so that you do not need to modify the policy value unless you want the policy to return a differently formatted option value. Some option types are very similar, and changing between them can have side effects. For example, strings and DNS names are both entered as string values in the user interfaces, but the formatted option values are quite different.

Note Cisco Network Registrar 7.0 preconfigures separate CableLabs (enterprise ID 4491) option definitions in the dhcp-cablelabs-config and dhcp6-cablelabs-config vendor-specific option definition sets.

Local Advanced and Regional Web UI

Step 1 From the DHCP menu, choose Options to open the List/Add DHCP Option Definition Sets page. View the existing DHCPv4 or DHCPv6 options.

Step 2 Click Add Option Definition Set to open the Add DHCP Option Definition Set page.

Step 3 Enter a name for the option definition set, then choose DHCPv4 or DHCPv6 from the DHCP Type drop-down list.

If you are creating vendor-specific option definitions using:

•Option 43, enter a value in the Vendor Option String field. (See the subsequent section for a sample procedure on creating a vendor option set and vendor option values for option 43.)

•Option 125 for DHCPv4 or option 17 for DHCPv6, enter a valid Enterprise Option Enterprise ID value.

Step 4 Click Add Option Definition Set.

Step 5 Click the option definition set name.

Step 6 On the Edit DHCP Option Definition Set page, click Add/Edit Option Definitions. This opens the List DHCP Option Definitions page. Any existing option definitions will appear on this page (new or modified standard definitions are marked with an asterisk).

Step 7 Click Add Option Definition. This opens the Add DHCP Option Definition page.

Step 8 Enter the ID number of the option definition, along with its name and a description. The ID must be 43, 125, or 17 (for DHCPv6) for the client to recognize a vendor-specific option definition. The option name does not need to match the one specified in the RFC and can be of your own creation.

Step 9 Choose or enter the data type and repeat count (or enter an absolute repeat count in the next field). The data type must be:

•Binary (AT_BLOB) for option 43.

•Vendor-opts (AT_VENDOR_OPTS) for option 125 (for DHCPv4) and option 17 (for DHCPv6).

(For details on the data type and repeat count values, see the "Option Definition Data Types and Repeat Counts" section.)

Step 10 Click Add Option Definition. Then, on the List DHCP Option Definitions page, click Modify Option Definition Set.

Using the Local Advanced web UI to create vendor option set and vendor option values for option 43:

Step 1 From the DHCP menu, choose Options to open the List/Add DHCP Option Definition Sets page.

Step 2 Click Add Option Definition Set.

The Add DHCP Option Definition page appears,

Step 3 Enter values for the following attributes:

Step 4 Click Add Option Definition Set.

The List/Add DHCP Option Definition Sets page appears.

Step 5 Click AP1130, the name of the option definition set that appears.

The Edit DHCP Option Definition Set AP1130 page appears.

Step 6 Click Add/Edit Option Definitions, then Add Option Definition.

Step 7 In the Add DHCP Option Definition page, enter values for the following attributes:

Step 8 Click Add Option Definition.

Note that clicking this button does not save the changes that you make to the option definition set. It only lists the option definition set on the List DHCP Option Definitions page.

Step 9 In the List DHCP Option Definitions page, click the name of the new option definition (ap1130-option-43), then Add Sub-Option Definition.

Step 10 In the Add DHCP Option Definition page, enter values for the following attributes:

Step 11 Click Add Option Definition, then Modify Option Definition Set.

Step 12 Click DHCP, then Policies to open the List/Add DHCP Policies page.

Step 13 Choose the policy for which to set this option; or, add a new policy in the Advanced mode.

Depending on your selection, the Edit DHCP Policy policy_name or the Add DHCP Policy page appears.

Step 14 From the DHCPv4 Vendor Options drop-down list, choose the name of the option definition set (AP1130), and click Select.

Step 15 Choose the option definition from the Name drop-down list ("ap1130-option-43") and, in the Value field, enter, for example:

(241 3.3.3.3,4.4.4.4)

Step 16 Click Add Option, then, click Modify Policy or Add Policy.

Step 17 Reload the DHCP server.

Examples

You can create a vendor option set and vendor option values from the CLI for Cisco Access Point (AP) devices, SunRay devices, and Cisco 79xx IPPhones using the sample procedures described in this section.

Example 21-1 Creating Vendor Option Set for Cisco AP Devices

Using option 43 for Lightweight Access Point Protocol (LWAPP) APs requires vendor option 43 if you are using Cisco Network Registrar as the DHCP server. This example is specific to the Cisco Aironet 1130 series. You can modify the example to configure option 43 for other vendor options, such as Cisco Aironet 1200 series and Cisco Aironet 1240 series.

Step 1 Create a .txt file with the following content:

#

# Version: 1

#  6.2+ Option-set example for Option 43 with suboptions for Cisco APs 

#

#  NOTE: Need to edit vendor option string to Exact match AP Model string in Option-60.

#

#        For compatibility with pre-6.2 vendor options ensure that

#        name=vendor-option-string. (Not True in this test example.)

#  ======================================================================

{

  ( id-range = 1 )

  ( vendor-option-string = Cisco AP c1130 )

  ( name = APtest )

  ( children = [

    {

      ( id = 43 )

      ( name = pxe-sample )

      ( desc =  )

      ( base-type = AT_BLOB )

      ( children = [

        {

          ( id = 241 )

          ( name = controller )

          ( desc = ap controller )

          ( base-type = AT_IPADDR )

          ( repeat = ONE_OR_MORE )

        } ]

      )

    } ]

  ) 

}

Step 2 Save the file as OptionSetCiscoAP.txt at the following location:

•Windows—\Program Files\Network Registrar\Local\bin

•Solaris and Linux—/opt/nwreg2/local/usrbin

Step 3 Import the OptionSetCiscoAP.txt file from the CLI using the import option-set file command. For example:

nrcmd> import option-set OptionSetCiscoAP.txt

(For information on importing option definition sets, see the "Importing and Exporting Option Definition Sets" section.)

Step 4 Set the vendor-specific option data on a policy using the policy name setVendorOption opt-name-or-id opt-set-name value command.

For example, to set vendor option 43 data for the optionset APtest with values (241 3.3.3.3,4.4.4.4), on an existing policy with the name test, use:

nrcmd> policy test setVendorOption 43 APtest "(241 3.3.3.3,4.4.4.4)"

nrcmd> save

Step 5 Reload the DHCP server.

nrcmd> dhcp reload

Example 21-2 Creating Vendor Option Set for SunRay Devices

Use this sample procedure to create vendor option set with multiple suboptions for SunRay Devices:

Step 1 Create a .txt file with the following content:

#

# Option Definition Set Export/Import Utility

# Version: 1

#  6.2 Option-set example for Option 43 with suboptions for Sun SunRay. 

#  NOTE: Need to edit vendor option string to match Option-60

#        For compatibility with pre-6.2 vendor options ensure that

#        name=vendor-option-string.

#  ======================================================================

{

  ( id-range = 1 )

  ( vendor-option-string = sunray )

  ( name = sunray )

  ( children = [

    {

      ( id = 43 )

      ( name = option43 )

      ( desc =  )

      ( base-type = AT_BLOB )

      ( children = [

        {

          ( id = 21 )

          ( name = AuthSrvr )

          ( desc = AuthSrvr )

          ( base-type = AT_IPADDR )

          ( repeat = ONE_OR_MORE )

        } 

        {

          ( id = 35 )

          ( name = AltAuth )

          ( desc = AltAuth )

          ( base-type = AT_IPADDR )

          ( repeat = ONE_OR_MORE )

        } 

        {

          ( id = 36 )

          ( name = BarrierLevel )

          ( desc = BarrierLevel )

          ( base-type = AT_SHORT )

        } 

       ]

      )

    } ]

  ) 

}

Step 2 Save the file as OptionSetSunRay.txt at the following location:

•Windows—\Program Files\Network Registrar\Local\bin

•Solaris and Linux—/opt/nwreg2/local/usrbin

Step 3 Import the OptionSetSunRay.txt file from the CLI using the import option-set file command. For example:

nrcmd> import option-set OptionSetSunRay.txt

(For information on importing option definition sets, see the "Importing and Exporting Option Definition Sets" section.)

Step 4 Set the vendor-specific option data on a policy using the policy name setVendorOption opt-name-or-id opt-set-name value command.

For example, to set vendor option 43 data for the optionset APtest with multiple suboption values (21 3.3.3.3,4.4.4.4) (35 1.1.1.1) (36 0), on an existing policy with the name test, use:

nrcmd> policy test setVendorOption 43 APtest "(21 3.3.3.3,4.4.4.4) (35 1.1.1.1) (36 0)"

nrcmd> save

Step 5 Reload the DHCP server.

nrcmd> dhcp reload

Example 21-3 Creating Option Set for Cisco 79xx IPPhones

Use this sample procedure to create option set for Cisco 79xx IPPhones:

Step 1 Define the option.

nrcmd> option 150 dhcp-custom create voip-tftp-server AT_IPADDR desc="VOIP Option-150 
Server" repeat=ONE_OR_MORE

Step 2 Display the configured option.

nrcmd> option dhcp-config list 

Step 3 Set policy, by using policy default setoption voip-tftp-server ip-address. For example:

nrcmd> policy default setoption voip-tftp-server 192.168.1.254 

Step 4 Confirm the policy setting.

nrcmd> policy default getoption voip-tftp-server 

Step 5 Reload the DHCP server.

nrcmd> dhcp reload

Option Definition Data Types and Repeat Counts

The data type values that you can use appear in Table 21-2.

You can view these types in the CLI by using option listtypes.

To set the repeat count, set the repeat-count attribute to one of the following, or enter an absolute number:

•ZERO_OR_MORE—0+ in the web UI

•ONE_OR_MORE—1+ in the web UI

•EVEN_NUMBER—2n in the web UI

In the CLI, for example, use:

nrcmd> option 200 ex-opt-def-set set repeat-count=ZERO_OR_MORE 

nrcmd> save 

Adding Suboption Definitions

You can set a suboption definition for the option definition by clicking Add Suboption Definition on the Edit DHCP Option Definition page. This opens the Add DHCP Option Definition page, where you can add the same values as for an option definition. The suboption definition you create is associated with its parent option (or parent suboption) definition. You can define up to six option and suboption levels.

Note You can add suboption definitions by using the web UI only. You currently cannot do so by using the CLI.

Suboption definition formats can be packed or type/length/value (TLV):

•Packed—A suboption with a zero ID value and an implicit data type. The option value is the only data in the packet. DHCPv6 options are virtually all defined with packed data. There are no markers for type or length and the layout of the data is inherent in the option definition. You cannot have further suboption definitions for packed suboptions.

•TLV—A suboption with a value of 1 through 255 (or 65535) that includes a type, length, and value. The data in the packet has the type and length preceding the value.

In most cases, you will not be mixing packed with TLV suboptions for the same option.

In addition to adding the AT_NOLEN datatype, you can enter PAD (0) and END (255) options anywhere in a list of suboptions for vendor option definitions (it is not necessary for the vendor option definition itself). For example:

(0 )(0 )(suboption-1 1 64)(255 ) 

To enter suboption values when editing policies, see the "Adding Complex Values for Suboptions" section.

Importing and Exporting Option Definition Sets

Importing and exporting option definition sets is a way to copy them between servers. In the CLI, you can import and export option sets by using import option-set file and export option-set name file.

For example, to import an option set for Preboot Execution Environment (PXE) clients, modify and import a sample file located in the /examples/dhcp directory:

nrcmd> import option-set /examples/dhcp/OptionSetPXE.txt 

Caution Do not export the built-in option definition sets (such as dhcp-config and dhcp-cablelabs-config) and then reimport them. Reimporting an edited option definition set without TAC assistance can cause the server to fail.

Some of the guidelines for the file format include:

•The version string in the file must match the version for the import utility.

•The utility imports just the first option definition set found in the file.

•Delimit objects using curly brackets ({ }), attributes using parentheses (( )), and lists of objects in attributes using square brackets ([ ]). Delimit string value attributes using quotes (" ").

Using some care, you can also edit the text file to make minor modifications to an option definition set. Cisco Network Registrar provides two sample option definition set text files in the examples/dhcp directory, OptionSetJumpStart.txt and OptionSetPXE.txt:

•OptionSetJumpStart.txt—Edit the vendor-option-string to match the dhcp-class-identifier (option 60) that your JumpStart clients are sending.

•OptionSetPXE.txt—Edit the vendor-option-string to match the dhcp-class-identifier (option 60) that your Pre-boot Execution Environment (PXE) clients are sending.

Pushing Option Definition Sets to Local Clusters

You can push option definition sets you create from the regional cluster to any of the local clusters. If you want to push a specific option definition set to a cluster, click Push Option Definition sets on the List/Add DHCP Option Definition Sets page, which opens the Push DHCP Option Definition Set to Local Clusters page.

This page identifies the data to push, how to synchronize it with the local cluster, and the cluster or clusters to which to push it. The data synchronization modes are:

•Ensure (preset value)—Ensures that the local cluster has new data without affecting any existing data.

•Replace—Replaces data without affecting other objects unique to the local cluster.

•Exact—Available for "push all" operations only. Use this with caution, because it overwrites the data and deletes any other objects unique to the local cluster.

Choose the destination cluster or clusters in the Available field and move it or them to the Selected field.

Tip The synchronization mode and cluster choice settings are persistent for the duration of the current login session, so that they are in effect each time you access this page, unless you change them.

After making these choices, click Push Data to Clusters. This opens the View Push DHCP Option Definition Set Data Report page.

Pulling Option Definition Sets from Replica Data

You may choose to pull option definition sets from the replica data of the local clusters instead of explicitly creating them. (You may first want to update the option definition set replica data by clicking the Replicate icon [] next to the cluster name.) To pull the option definition sets in the web UI, click Pull Replica Option Definition Sets to open the Select Replica DHCP Option Definition Set Data to Pull page.

This page shows a tree view of the regional server replica data for the local clusters' option definition sets. The tree has two levels, one for the local clusters and one for the scope templates in each cluster. You can pull individual option definition sets from the clusters, or you can pull all of their option definition sets. To pull individual ones, expand the tree for the cluster, then click Pull Option Definition Set next to its name. To pull all the ones from a cluster, click Pull All Option Definition Sets from Cluster. To pull the option definition sets, you must also choose a synchronization mode:

•Ensure—Ensures that the regional cluster has new data without affecting any existing data.

•Replace (preset value)—Replaces data without affecting other objects unique to the regional cluster.

•Exact—Available for "pull all" operations only. Use this with caution, because it overwrites the data and deletes any other objects unique to the regional cluster.

Setting Option Values for Policies

You enter option values on a policy. The option definitions in your server configuration control the format and values that you enter.

Local Advanced and Regional Web UI

On the List/Add DHCP Policies page, click a policy to edit it. (Note that you cannot set options for policies in Basic mode.) On the Edit DHCP Policy page:

•To enter a standard DHCPv4 or DHCPv6 option value for a policy, choose it from the DHCPv4 Options or DHCPv6 Options drop-down list, then set a value for the option. Click Add Option.

•To enter a vendor-specific DHCPv4 or DHCPv6 option value for a policy, choose an option definition set in the DHCPv4 Vendor Options or DHCPv6 Vendor Options drop-down list, then click Select. The page changes to show the drop-down list that includes the option; choose it, then click Add Option.

Note that you can also edit policy attributes on this page. Be sure to click Modify Policy.

To edit a configured policy option, click the name of the configured option on the Edit DHCP Policy page to open the Edit DHCP Policy Option page. Enter a new value, then click Modify Option.

CLI Commands

Use one of these commands:

nrcmd> policy name setOption {name | id} value 

nrcmd> policy name setV6Option {name | id} value 

nrcmd> policy name setVendorOption {name | id} option-set-name value 

nrcmd> policy name setV6VendorOption {name | id} option-set-name value 

To list the options in the policy, use one of these commands:

nrcmd> policy name listOptions 

nrcmd> policy name listV6Options 

nrcmd> policy name listVendorOptions 

nrcmd> policy name listV6VendorOptions 

To add suboption values, see the "Adding Complex Values for Suboptions" section.