MIMIC DHCP Protocol Module Guide

Overview

The MIMIC Dynamic Host Configuration Protocol (DHCP) Protocol Module allows assigning addresses to agents dynamically from a DHCP server according to the DHCPv4 protocol defined in RFC 2131. at the startup time of an agent instance.

Installation

DHCP client support is made available in MIMIC as an optional dynamically loadable module. Starting with MIMIC 10.00, you can use the Protocol Wizard to install the DHCP module. If you prefer to enable DHCP by hand, you need to do the following:

Use File->Terminate to stop the any running MIMIC daemon.
Copy the DHCP library (dhcp.dll on Windows, dhcp.so on Unix) from "bin/dynamic/optional" to "bin/dynamic" in the install directory.
Install the license keys as detailed in the instructions e-mailed to you.
Restart MIMIC. You should see the following type of message in the MIMICLog that confirms that the DHCP module was properly loaded :
```
INFO  - DHCP : Loaded protocol from < path-to-DLL >
INFO  - DHCP (CableModem) v7.00 : Individual license #2345
```

Once DHCP is loaded, any agent instance configured to support the DHCP protocol will request an IP address from the DHCP server at agent start time.

Using DHCP from MIMICView

If the DHCP module is enabled, then Agent->Add, Agent->Configure and Agent->Paste dialogs will display DHCP as an additional checkbox in the Advanced pane along with the SNMP protocols. On selecting the checkbox a new DHCP pane will appear.

This DHCP configuration pane lets the user configure the Hardware Address used by the DHCP module while negotiating the IP address lease. In case the user leaves this field to be blank, the module auto generates unique hardware addresses based on the agent's id. (e.g. 00:00:00:00:00:01, 00:00:00:00:00:02, ...)

In order to send additional options in the DHCP DISCOVER and REQUEST messages, you can use the Additional Options field. This is a list of options of the form

OPT1,LEN1,VALUE1;OPT2,LEN2,VALUE2;........;OPTN,LENN,VALUEN[;]

where an OPT value can be 1 to 254 and LEN can be 1 to 255. VALUE can be either an ASCII string or hexadecimal string (eg. \xFF FF or \xFF:FF or \xFF-FF)

An action script can be configured to execute when an agent gets the IP address from the DHCP server (BOUND state action script). This is useful to react to lease and re-lease of IP addresses. The agent may want to start a TFTP transfer once an address is leased, or if the lease is renewed.

The script will be executed with the following global variables defined:

gCurrentAgent
This variable holds the agent that initiated the DHCP exchange.
gCurrentState
This variable holds the current state of the DHCP exchange (for now always will be BOUND).
gPreviousState
This variable holds the previous state of the DHCP exchange (one of REQUESTING, RENEWING or REBINDING).
gParams
Provides the DHCP parameters, same as those returned from the mimic agent protocol msg DHCP params command.

NOTE: During agent startup, the bound action script might be executed even before the agent transitioned to running state. So any command dependent on the agent's state could fail.

In the case of DOCSIS Cable Modem simulations, it is assumed that the DHCP server is configured to provide values for siaddr and file DHCP options, so that the agent will be able to retrieve follow-on configuration parameters to be used for the TFTP configuration file download. Retrieval of these settings is accomplished through use of a MIMIC agent startup action script start.mtcl, which is placed in the data/sim/SIMULATION-NAME directory corresponding to the simulated device in use. This file, created by the user, will run when the agent is started. It should contain lines resembling the following:

#
# parse the values received in the DHCP offer
#
set dhcp_param_list [mimic agent protocol msg DHCP params]
puts "Configured via DHCP at IP [mimic agent get host]"

# load server parameter 
set x [ lsearch $dhcp_param_list siaddr* ] 
puts " server_address = $x" 
set server_listvar [ lindex $dhcp_param_list $x ] 
set server [ lindex $server_listvar 1 ] 

#load file parameter 
set y [ lsearch $dhcp_param_list file* ] 
puts " file_name = $y " 
set file_listvar [ lindex $dhcp_param_list $y ] 
set file [ lindex $file_listvar 1 ]

This will cause the agent to parse the received DHCP offer and load variables with the parameters required for the TFTP portion of the configuration cycle. Another section below lists further commands associated with TFTP startup, which will also be included in the start.mtcl agent startup action script file.

When the agent is started, successful completion of the DHCP portion will be indicated in the log by entries resembling this:

INFO 08/09.10:19:32 - agent 3 configured at 192.9.200.211,161. 
INFO 08/09.10:19:33 - agent 3 loading 
INFO 08/09.10:19:38 - agent 3 loaded device
Configured via DHCP at IP 192.9.200.211
 server_address = 192.9.200.13
 file_name = modem.bin

Using DHCP from MIMICShell

A few new commands and some enhanced old commands can be used from the MIMICShell to use the DHCP functionality. Here is a synopsis:

mimic protocol msg DHCP get args

This command lets the user gather the list of arguments required and their particulars. A sample exchange for this command would be:

  mimicsh> mimic protocol msg DHCP get args
  {{hwaddr} {Hardware Address} {macaddress} {} {optional} {}}
  {{server} {Server Address} {string} {} {optional} {}}
  {{relay} {Relay Address} {string} {} {optional} {}}
  {{classid} {Class Identifier} {string} {} {optional} {}}
  {{clientid} {Client Identifier} {string} {} {optional} {}}
  {{add_options} {Additional Options} {string} {} {optional} {}}
  {{script} {Action Script} {file} {scripts {{*.mtcl {MIMIC Tcl scripts}
  {edit yes} {new yes}} {*.tcl {Tcl script files} {edit yes} {new yes}}
  {*.so {C/C++ DLL files} {edit no} {new no}}} - both} {optional} {}}

mimic agent get protocol
This command lets the user look at the protocols currently configured on the agent. A sample exchange for this command would be:
```
  mimicsh> mimic agent get protocol
  snmpv1,snmpv2c
```
mimic agent set protocol
This command lets the user change the protocol setting for an agent. A sample exchange for this command would be:
```
  mimicsh> mimic agent set protocol snmpv1,DHCP
```
mimic agent protocol msg DHCP get config
This command lets the user get the current argument settings. A sample exchange for this command would be:
```
  mimicsh> mimic agent protocol msg DHCP get config
  {hwaddr=} {classid=} {add_options=} {script=}
```

mimic agent protocol msg DHCP set config [config]

This command lets the user change the current argument settings. A sample exchange for this command would be:

  mimicsh> mimic agent protocol msg DHCP set config {hwaddr=aa:bb:cc:dd:ee:ff}
  {add_options=67,4,boot} {script=dhcp_action.mtcl} "{classid=some string}"
  mimicsh> mimic agent protocol msg DHCP get config
  {hwaddr=aa:bb:cc:dd:ee:ff} {classid=some string} {add_options=67,4,boot} {script=dhcp_action.mtcl}

mimic agent protocol msg DHCP get trace
mimic agent protocol msg DHCP set trace [0 or 1]

This command lets the user change the DHCP tracing configuration for an agent. A sample exchange would be:

  mimicsh> mimic agent assign 9

  mimicsh> mimic agent protocol msg DHCP get trace
  0
  mimicsh>  mimic agent protocol msg DHCP set trace 1

  mimicsh> mimic agent protocol msg DHCP get trace
  1

and the log would show:

INFO  - agent 9 trace enabled for DHCP
INFO  - agent 9, sent DHCP-DISCOVER msg (broadcast)
INFO  - agent 9, received DHCP OFFER from 192.9.200.1.
INFO  - agent 9, sent DHCP-REQUEST msg (broadcast)
INFO  - agent 9, received DHCP ACK from 192.9.200.1.
INFO  - agent 9, REQUESTING: obtained lease for address=192.9.200.235. lease_time=43200, renew_time=21600, rebind_time=37800
INFO  - agent 9, BOUND: calling agent_start_pre_cb()
INFO  - agent 9 configured at 192.9.200.235,161.
INFO  - agent 9 loading
INFO  - agent 9 loaded device

mimic protocol msg DHCP get stats_hdr
mimic agent protocol msg DHCP get statistics
Returns DHCP statistics information:
- a list of statistic headers, and
- current statistics values for the specified client.
In order, the statistic values are:
- Number of DHCPDISCOVER messages sent
- Number of DHCPOFFER messages received
- Number of DHCPREQUEST messages sent
- Number of DHCPACK messages received
- Number of DHCPNAK messages received
- Number of DHCPDECLINE messages received
- Number of DHCPRELEASE messages sent
- Number of DHCPINFORM messages sent
- Number of timeouts
A sample exchange for these commands would be:
```
  mimicsh> mimic protocol msg DHCP get stats_hdr
  {{discover} {DHCP-DISCOVER}} {{offer} {DHCP-OFFER}} {{request} {DHCP-REQUEST}}
  {{ack} {DHCP-ACK}} {{nak} {DHCP-NAK}} {{decline} {DHCP-DECLINE}}
  {{release} {DHCP-RELEASE}} {{inform} {DHCP-INFORM}} {{timeout} {DHCP-TIMEOUT}}

  mimicsh> mimic agent protocol msg DHCP get statistics
  1 1 1 1 0 0 1 0 0
```

mimic agent protocol msg DHCP params

This command allows the user to retrieve parameters configured by the server in its DHCP-OFFER message. A sample exchange for this command would be:

  mimicsh> mimic agent protocol msg DHCP params
  {htype 1} {hlen 6} {ciaddr 0.0.0.0} {yiaddr 192.9.200.201} {siaddr 192.9.200.13}
  {giaddr 0.0.0.0} {chaddr 00 00 00 00 00 01} {sname } {file myconfig.dat}
  {options {53 1 {5}} {54 4 {192 9 200 39}} {1 4 {255 255 255 0}}
  {3 4 {192 9 200 22}} {28 4 {192 9 200 255}} {51 4 {0 0 0 10}}}

Compatibility

The DHCP protocol module has been tested for compatibility with a variety of DHCP servers. It works with the DHCP server included in Solaris 8, Windows Server 2003, RedHat Linux 7.3 and newer, and with the version 3.0 server in the Internet Software Consortium DHCP distribution.

The version 2.0 ISC DHCP server has bugs which prevent it from working with MIMIC. This server is included in RedHat Linux 6.x

MIMIC^® Online Documentation