DHCP Option Manager

Note: To display only the features present on a particular device, select one or more filters from the SmartDocs bar below.

StageNow - 3.3

Overview

The DHCP Option Manager (DhcpOptionMgr) allows an app to configure options for Dynamic Host Configuration Protocol (DHCP) on the device. This can simplify device administration by allowing network settings such as the device's IP address and default gateway to be configured automatically using DHCP protocols.

When using DHCP on a device, the DHCP Client sends a DHCP Request to a DHCP Server and receives back a DHCP Acknowledgment. A request can contain information about the device or the client, as well as requests for additional information from the server. The acknowledgment contains the IP address assigned to the device by the server along with any additional information requested by the device.

DHCP Options are variable-length strings identified by DHCP Option Numbers that can be included in the request or acknowledgment to convey information between a client and server. From the point of view of the device where the DHCP Client is running, a DHCP Option can support a mode of Write (if the DHCP Client sends the option to the DHCP Server in the DHCP Request) or Read (if the DHCP Client receives information from the DHCP Server in the DHCP Acknowledgment). DHCP can support a wide variety of DHCP Options, including custom options that can be defined by equipment vendors or end customers.

Main Functionality

  • Enable/Disable and set values of configurable DHCP options listed below:
DHCP Option Number DHCP Option Name Default State Configurable Supported Mode
1 Subnet Mask On No Read
3 Routers On No Read
6 Domain Name Servers On No Read
12 Host Name On Yes Write
15 Domain Name On No Read
28 Broadcast Address Off Yes Read
42 NTP Server Off Yes Read
43 Vendor Encapsulated Off Yes Read
51 Lease Time On No Read
60 Vendor Class ID Off Yes Write
61 Client Identifier Off Yes Write
66 TFTP Server Name Off Yes Read
67 Boot File Name Off Yes Read
77 User Class On Yes Write
81 FQDN Off Yes Write
119 Domain Search List Off Yes Read
150 TFTP Server Address Off Yes Read
186 Vendor Specific1 Off Yes Read
188 Vendor Specific2 Off Yes Read
230 Vendor Specific3 Off Yes Read

Note: DHCP Options that are shown in the table above as "not configurable" are supported on Zebra Android devices but are always enabled and their operation cannot be altered using DhcpOptionMgr.

Host Name (12)

Controls whether a Host Name will be sent by the DHCP Client to the DHCP Server via the Host Name DHCP Option. The Host Name is generally used by a DHCP Server to identify a device on the network and/or to track the devices to which IP Addresses have been assigned.

Parm Name: HostNameState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 4.4+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the specified Host Name Option to be sent by the DHCP Client to the DHCP Server in the DHCP Request.

MX: 4.4+

2 Disable This value will cause this DHCP Option to be turned off and hence will prevent a Host Name from being to be sent by the DHCP Client to the DHCP Server.

MX: 4.4+

Host Name Option Value

Used to enter the Host Name that will be sent by the DHCP Client to the DHCP Server in the DHCP Request.

Parm value input rules:

  • String from 1–91 characters containg a host name

Shown if: Host Name is "Enable"

Parm Name: HostNameValue

Requires:

  • MX: 4.4+

Broadcast Address (28)

Controls whether a request for the Broadcast Address is sent by the DHCP Client to the DHCP Server in the DHCP Request. When requested, the DHCP Server returns the Broadcast Address for the network to the device in the DHCP Acknowledgment. The Broadcast Address for a network is the IP Address for which all devices on that network are enabled to receive messages. A message sent to the Broadcast Address for a network can therefore be received by all devices on that network, rather than by a specific device.

Parm Name: BroadcastAddrState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) causes no change to DHCP Option settings; any previously selected setting is retained.

MX: 4.4+

1 Enable Turns on the DHCP Option, causing the Broadcast Address to be requested by the DHCP Client in the DHCP Request.

MX: 4.4+

2 Disable Turns off the DHCP Option, preventing the Broadcast Address from being requested by the DHCP Client in the DHCP Request.

MX: 4.4+

NTP Server (42)

Control whether a request for a NTP Server Address will be sent by the DHCP Client to the DHCP Server in the DHCP Request. When requested, the DHCP Server will return the NTP Server Address to the device in the DHCP Acknowledgment.

An NTP (Network Time Protocol) Server is a Server that is capable of providing the current Date and Time to a device. A device must generally know the name or address of an NTP Server in order to query that server to acquire the Date and Time.

Note: The DHCP Client does not automatically use the value returned by this DHCP Option to configure the device to acquire the Date and Time from the returned NTP Server. To configure a device to acquire the Date and Time from the NTP Server, the value of the returned NTP Server Address would need to be obtained using the DhcpOptionMgr and then used to configure AutoTime via the Clock.

Parm Name: NTPServerState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 4.4+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the NTP Server Address to be requested by the DHCP Client in the DHCP Request.

MX: 4.4+

2 Disable This value will cause this DHCP Option to be turned off and hence will prevent the NTP Server Address from being requested by the DHCP Client in the DHCP Request.

MX: 4.4+

Vendor Encapsulated (43)

Vendor Encapsulated, also referred to as Vendor Specific, is a DHCP option that can be requested by the DHCP Client. The value of this option is determined by the specific vendor of the DHCP server. In complex network environments where they may be multiple vendors, this option is often used with option 60 so that the correct DHCP server is used for the given device.

Parm Name: VendorEncapsulatedState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 5.0+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the Vendor Specific option 43 to be requested by the DHCP Client in the DHCP Request.

MX: 5.0+

2 Disable This value will cause this DHCP Option to be turned off and hence will not cause the Vendor Specific option 43 to be requested by the DHCP Client in the DHCP Request.

MX: 5.0+

Vendor Class Identifier (60)

Controls whether a Vendor Class will be sent by the DHCP Client to the DHCP Server via the Vendor Class DHCP Option. This support allows DHCP relay to compare option 60 strings in received DHCP client packets against strings configured on the router by the app or an admin. The DHCP relay option 60 feature can be used when providing converged services in a network environment—option 60 support enables DHCP relay to direct client traffic to the specific DHCP server (the vendor-option server) that provides the service that the client requires.

Another option permits option 60 strings to be configured to direct traffic to the DHCP local server in the current virtual router. For example, imagine an environment in which some DHCP clients require only Internet access, while other clients require IPTV service. The clients that need Internet access get their addresses assigned by the local DHCP server on the E Series router (in equal-access mode). Clients requiring IPTV must be relayed to a specific DHCP server that provides the service. To support both types of clients, configure two option-60 strings on the DHCP relay. When DHCP client packets are received with option 60 strings configured, the strings are matched against all strings configured on the DHCP relay. If the client string matches the first configured string, that client is directed to the DHCP local server and gains Internet access. Client traffic with an option 60 string that matches the second string is relayed to the DHCP server that provides the IPTV service. In addition, a default action can be configured to be performed by a DHCP relay when a client option 60 string does not match either of the pre-configured strings. For example, it might be desireable for any client with a non-matching string to be dropped.

Parm Name: VendorClassIdState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 5.0+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the specified Vendor Class to be sent by the DHCP Client to the DHCP Server in the DHCP Request.

MX: 5.0+

2 Disable This value will cause this DHCP Option to be turned off and hence will prevent a Vendor Class from being to be sent by the DHCP Client to the DHCP Server.

MX: 5.0+

Vendor Class Value

Used to enter the Vendor Class value that will be sent by the DHCP Client to the DHCP Server in the DHCP Request.

Parm value input rules:

  • String from 1–91 characters containing a vendor class value

Shown if: Vendor Class is "Enable"

Parm Name: VendorClassIdValue

Requires:

  • MX: 5.0+

Client Identifier Enable/Disable (61)

Controls whether a custom client identifier value can be specified for identifying a device on the network in place of its MAC address. When Enabled, permits the identifier to be specified using the ClientIdentifierValue parameter. When Disabled, the device will be identified by its MAC address.

Parm Name: ClientIdentifier

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 6.3+

1 Enable Enables a client identifier to be specified.

MX: 6.3+

2 Disable Prevents a client identifier from being specified.

MX: 6.3+

Client Identifier Value

Used to enter the client identifier, an optional parameter that can be used to identify a device on the network in place of its MAC address.

Parm value input rules:

  • String from 1–91 characters containing a class identifier value

Shown if: Client Identifier is set to "Enable"

Parm Name: ClientIdentifierValue

Requires:

  • MX: 6.3+

TFTP Server Name Enable/Disable (66)

Controls whether a request for a TFTP Server Name will be sent by the DHCP Client to the DHCP Server in the DHCP Request. When requested, the DHCP Server will return the TFTP Server Name to the device in the DHCP Acknowledgment.

A TFTP (Trivial File Transport Protocol) Server provides simple means for a remote client to get or put a file. A primary use of TFTP is configuring a device when it first joins a network. TFTP is used because it is very simple to implement but must be used with caution because it lacks security and other more advanced file transfer features.

Important: The DHCP Client does not automatically use an acquired TFTP Server Name to perform file transfers or configuration. To configure a device using TFTP, use DhcpOptionMgr to acquire the TFTP Server Name and provide it to the TFTP Client that will perform the file transfer. The transferred files can then be used to perform the desired configuration.

Parm Name: TFTPServerNameState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 4.4+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the TFTP Server Name to be requested by the DHCP Client in the DHCP Request.

MX: 4.4+

2 Disable This value will cause this DHCP Option to be turned off and hence will prevent the TFTP Server Name from being requested by the DHCP Client in the DHCP Request.

MX: 4.4+

TFTP Ser. Name (66)

NOTE: This parameter is deprecated. Use TFTPServerNameState instead.

Parm Name: TFTPSerNameState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 4.4+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the TFTP Server Name to be requested by the DHCP Client in the DHCP Request.

MX: 4.4+

2 Disable This value will cause this DHCP Option to be turned off and hence will prevent the TFTP Server Name from being requested by the DHCP Client in the DHCP Request.

MX: 4.4+

Boot File Name Enable/Disable (67)

Controls whether a request for a Boot File name will be sent by the DHCP Client to the DHCP Server in the DHCP Request. When requested, the DHCP Server will return the Boot File name to the device in the DHCP Acknowledgment.

A Boot File is a file that is typically used to configure a device when it first joins a network. A common usage scenario is to pull a Boot File of a given name from a TFTP Server and then use that Boot File to configure the device.

Note: The DHCP Client does not automatically use the Boot File name to configure the device or perform file transfers. To configure a device, a Boot File name and a TFTP Server Name must both be acquired using the DhcpOptionMgr and provided to a TFTP Client that could perform the boot-file transfer. Once transferred, the file can then be consumed to perform any desired configuration.

Parm Name: BootFileState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 4.4+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the Boot File name to be requested by the DHCP Client in the DHCP Request.

MX: 4.4+

2 Disable This value will cause this DHCP Option to be turned off and hence will prevent the Boot File name from being requested by the DHCP Client in the DHCP Request.

MX: 4.4+

User Class Enable/Disable (77)

Control whether a User Class will be sent by the DHCP Client to the DHCP Server via the User Class DHCP Option. The User Class is generally used by a DHCP Server to select the proper pool of IP Addresses from which to acquire the IP Address to assign to the device. It may also be used by the DHCP Server to determine which additional information should be returned to the device in the DHCP Acknowledgment.

Parm Name: UserClassState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 4.4+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the specified User Class to be sent by the DHCP Client to the DHCP Server in the DHCP Request.

MX: 4.4+

2 Disable This value will cause this DHCP Option to be turned off and hence will prevent a User Class from being to be sent by the DHCP Client to the DHCP Server.

MX: 4.4+

User Class Value

Used to enter the User Class value that will be sent by the DHCP Client to the DHCP Server in the DHCP Request.

Parm value input rules:

  • String from 1–91 characters containing a user class value

Shown if: User Class is "Enable"

Parm Name: UserClassValue

Requires:

  • MX: 4.4+

FQDN Enable/Disable (81)

Controls whether the DHCP client can send a fully qualified domain name (FQDN) value and optional flag to the DHCP server as a means of updating IP-address-to-FQDN mapping.

An FQDN is the complete domain name for a specific internet host computer, including its hostname and domain name. For example, the FQDN of Google's Gmail server "mail.google.com" includes the hostname "mail" and the domain name "google.com." The server's hostname distinguishes it from other servers in the Google.com domain, and its domain name sets Google's mail server apart from other public mail servers.

For complete information about FQDN options, please refer to Section 2 of IETF's FQDN Option page.

Parm Name: FqdnState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 6.3+

1 Enable Enables the DHCP client to send an FQDN value and optional flag-field value.

MX: 6.3+

2 Disable Prevents the DHCP client from sending FQDN information.

MX: 6.3+

FQDN Value

Used to enter a fully qualified domain name (FQDN) for the DHCP client to communicate to the DHCP server.

Parm value input rules:

  • String from 1–91 characters containing an FQDN value

Shown if: FQDN is set to "Enable"

Parm Name: FqdnValue

Requires:

  • MX: 6.3+

FQDN Flag Value

Used to enter a value for the optional FQDN flag, which DHCP clients can use to convey information about DNS updates. The FQDN Flag value is used to overcome issues related to a hostname prefixed with a special character.

  • 0001 = "S" - Indicates whether the server should perform FQDN-to-address DNS updates. A "0" value indicates that the server SHOULD NOT perform updates (recommended).
  • 0010 = "O" – Indicates whether the server has overridden the value stored in the "S" bit. NOTE: Client must always set a "0" value here.
  • 0100 = "E" – Indicates the encoding used on the Domain Name field. When this bit contains a "1" value, FQDN is binary-encoded (recommended). All DNS servers should have the capability to handle this encoding.
  • 1000 = "N" – Indicates whether the SHOULD (value = 1) or SHOULD NOT (value = 0) perform any DNS updates. The S bit must contain a "0" value if the N bit contains a "1" value.

Parm value input rules:

  • String of exactly 7 characters containing an FQDN flag value in the format "x,x,x,x"
  • For example, the string "0,1,0,0" sends the Zebra-recommended values for this parameter

See the FQDN Flags Field on IETF.org for more information.

Shown if: FQDN is set to "Enable"

Parm Name: FqdnFlagValue

Requires:

  • MX: 6.3+

Domain Search Enable/Disable (119)

Control whether a request for the Domain Search list will be sent by the DHCP Client to the DHCP Server in the DHCP Request. When requested, the DHCP Server will return the Domain Search list for the network to the device in the DHCP Acknowledgment.

The Domain Name System (DNS) is a hierarchical distributed naming system that associates domain names to the IP Addresses. When seeking to resolve a name, one or more Domain Name Servers may need to be contacted, in a prioritized order until the name can be successfully resolved. The Domain Search list for a network is an ordered list of DNS server addresses that should be used to resolve names on that network.

Note: The DHCP Client does not automatically use the Domain Search List to configure the DNS Client to resolve names based on the list. This may be a future enhancement, when the DNS Client provides a way to configure it to use such a list. In the meantime, if name resolution needs to be performed based on this list, it would have to be implemented at an application level. An application would need to acquire the Domain Search List using the DhcpOptionMgr and then utilize the information provided in that list to drive an explicit process of requesting name resolution from the DNS Servers for the listed domains

Parm Name: DomainSearchState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 4.4+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the Domain Search list to be requested by the DHCP Client in the DHCP Request.

MX: 4.4+

2 Disable This value will cause this DHCP Option to be turned off and hence will prevent the Domain Search list from being requested by the DHCP Client in the DHCP Request.

MX: 4.4+

TFTP Server Address Enable/Disable (150)

Control whether a request for a TFTP Server Address will be sent by the DHCP Client to the DHCP Server in the DHCP Request. When requested, the DHCP Server will return the TFTP Server Address to the device in the DHCP Acknowledgment.

The TFTP Server Address DHCP Option (Option 150) is basically a Cisco-proprietary version of the standard TFTP Server Name DHCP Option (Option Number 150).

Note: The DHCP Client does not automatically use the TFTP Server Address to perform any file transfers or configuration. To configure a device using TFTP, the TFTP Server Address would need to be acquired using the DhcpOptionMgr and then provided to a TFTP Client that could perform the transfer of one or more files and then perform any desired configuration using those files.

Parm Name: TFTPServerAddrState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured.

MX: 4.4+

1 Enable This value will cause this DHCP Option to be turned on and hence will cause the TFTP Server Address to be requested by the DHCP Client in the DHCP Request.

MX: 4.4+

2 Disable This value will cause this DHCP Option to be turned off and hence will prevent the TFTP Server Address from being requested by the DHCP Client in the DHCP Request.

MX: 4.4+

Vendor Specific 186 Enable/Disable

Controls whether vendor-specific option 186 can be requested by the DHCP client. The potential returned value of this request is determined by the DHCP server vendor.

Parm Name: VendorSpecific1State

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured; any previously selected setting will be retianed.

MX: 5.0+

1 Enable Enables vendor-specific option 186 to be requested by the DHCP Client.

MX: 5.0+

2 Disable Prevents vendor-specific option 186 from being requested.

MX: 5.0+

Vendor Specific 188 Enable/Disable

Controls whether wendor-specific option 188 can be requested by the DHCP client. The potential returned value of this request is determined by the DHCP server vendor.

Parm Name: VendorSpecific2State

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured; any previously selected setting will be retianed.

MX: 5.0+

1 Enable Enables vendor-specific option 188 to be requested by the DHCP Client.

MX: 5.0+

2 Disable Prevents vendor-specific option 188 from being requested.

MX: 5.0+

Vendor Specific 230 Enable/Disable

Controls whether the vendor-specific option 230 can be requested by the DHCP client. The potential returned value of this request is determined by the DHCP server vendor.

Parm Name: VendorSpecific230State

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured; any previously selected setting will be retianed.

MX: 6.3+

1 Enable Enables vendor-specific DHCP Option 230 to be requested by the DHCP Client.

MX: 6.3+

2 Disable Prevents vendor-specific DHCP Option 230 from being requested.

MX: 6.3+

Request Custom Option Enable/Disable

Controls whether the DHCP client can request a Custom Option Number. This parameter is designed to allow the DHCP client to support new vendor options without the need for an OS update.

Parm Name: RequestCustomOption

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured; any previously selected setting is retained.

MX: 8.1+

1 Enable Enables the DHCP client to request a custom option number.

MX: 8.1+

2 Disable Prevents the DHCP client from requesting a custom option number.

MX: 8.1+

Custom Option Number

Used to enter a Custom Option Number.

Parm value input rules:

  • String from 1–255 characters

Shown if: Send Custom Option is set to "Enable" or "Disable"

Parm Name: RequestCustomOptionNumber

Requires:

  • MX: 8.1+

Send Custom Option Enable/Disable

Controls whether the DHCP client can send a Custom Option Number. This parameter is designed to allow the DHCP client to support new vendor options without the need for an OS update.

Parm Name: SendCustomOptionState

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no changes to how this DHCP Option is configured; any previously selected setting is retained.

MX: 8.1+

1 Enable Enables the DHCP client to send the Custom Option Number.

MX: 8.1+

2 Disable Prevents the DHCP client from sending a Custom Option Number.

MX: 8.1+

Custom Option Number

Used to enter the Custom Option Number to be sent.

Parm value input rules:

  • String from 1–255 characters

Shown if: Send Custom Option is set to "Enable" or "Disable"

Parm Name: SendCustomOptionNumber

Requires:

  • MX: 8.1+

Send Custom Option Value

Used to enter the Custom Option Value.

Parm value input rules:

  • String from 1–91 characters

Shown if: Send Custom Option is set to "Enable"

Parm Name: SendCustomOptionValue

Requires:

  • MX: 8.1+

Examples

Request custom option number


<wap-provisioningdoc>
    <characteristic type="DhcpOptionMgr">
        <characteristic type="RequestCustomOption">
            <parm name="RequestCustomOptionNumber" value="222"/>
            <parm name="RequestCustomOptionState" value="1"/>
        </characteristic>
        <characteristic type="SendCustomOption">
            <parm name="SendCustomOptionState" value="1"/>
            <parm name="SendCustomOptionValue" value="TestCustom"/>
            <parm name="SendCustomOptionNumber" value="200"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>    

Configure various DHCP options


<wap-provisioningdoc>
    <characteristic type="DhcpOptionMgr">
    <characteristic type="HostName">
        <parm name="HostNameState" value="1"/>
        <parm name="HostNameValue" value="DHCPTEST2"/>  
    </characteristic>
    <characteristic type="UserClass">
        <parm name="UserClassState" value="1"/>
        <parm name="UserClassValue" value="abcd efg"/>
    </characteristic>
    <characteristic type="BroadcastAddr">
        <parm name="BroadcastAddrState" value="1"/>
    </characteristic>
    <characteristic type="NTPServer">
        <parm name="NTPServerState" value="1"/>
    </characteristic>
    <characteristic type="TFTPServerName">
        <parm name="TFTPServerNameState" value="1"/>
    </characteristic>
    <characteristic type="BootFile">
        <parm name="BootFileState" value="1"/>
    </characteristic>
    <characteristic type="DomainSearch">
        <parm name="DomainSearchState" value="1"/>
    </characteristic>
    <characteristic type="TFTPServerAddr">
        <parm name="TFTPServerAddrState" value="1"/>
    </characteristic>
    <characteristic type="VendorClassId">
        <parm name="VendorClassIdState" value="1"/>
        <parm name="VendorClassIdValue" value="testid"/>
    </characteristic>
    <characteristic type="VendorEncapsulated">
        <parm name="VendorEncapsulatedState" value="1"/>
    </characteristic>
    <characteristic type="VendorSpecific1">
        <parm name="VendorSpecific1State" value="1"/>
    </characteristic>
    <characteristic type="VendorSpecific2">
        <parm name="VendorSpecific2State" value="1"/>
    </characteristic>
    </characteristic>
</wap-provisioningdoc>

Query DhcpOptionMgr version


<wap-provisioningdoc>
    <characteristic-query type="DhcpOptionMgr"/>
</wap-provisioningdoc>