Python policy – DHCPv4 API

• The system provides a Python object for input DHCPv4 packet: alc.dhcpv4.

• alc.dhcpv4 has following attributes to represent the DHCPv4 header fields:

  Table: alc.dhcpv4 attributes displays alc.dhcpv4 attributes.

  Table: alc.dhcpv4 attributes

  Class attributes	DHCPv4 header field	Access
  alc.dhcpv4.pkt_len	Integer Total length of original DHCPv4 packet (UDP/IP header excluded, including pad option) in bytes	read
  alc.dhcpv4.pkt_netlen	Integer Total length of original DHCPv4 packet (UDP/IP header excluded, pad option in the ‟options” field excluded) in bytes	read
  alc.dhcpv4.op	op	read
  alc.dhcpv4.htype	htype	read/write
  alc.dhcpv4.hlen	hlen	read/write
  alc.dhcpv4.hops	hops	read/write
  alc.dhcpv4.xid	xid	read
  alc.dhcpv4.secs	secs	read/write
  alc.dhcpv4.flags	flags	read/write
  alc.dhcpv4.ciaddr	ciaddr	read/write
  alc.dhcpv4.yiaddr	yiaddr	read/write
  alc.dhcpv4.siaddr	siaddr	read/write
  alc.dhcpv4.giaddr	giaddr	read/write
  alc.dhcpv4.chaddr	chaddr	read/write
  alc.dhcpv4.sname	sname	read/write
  alc.dhcpv4.file	file	read/write

All attributes, except alc.dhcpv4.pkt_len and alc.dhcpv4.pkt_netlen, are string with value of the actual bytes in the header.

The following is a list all functions of alc.dhcpv4:

• alc.dhcpv4.drop()

• alc.dhcpv4. getOptionList()

• alc.dhcpv4.pad(min_size=300)

• alc.dhcpv4. get(op_code)

• alc.dhcpv4. set(op_code,valTuple)

• alc.dhcpv4. clear(op_code)

• alc.dhcpv4.get_relayagent() / alc.dhcpv4.set_relayagent(D4OL)

• alc.dhcpv4.get_vendorspecific() / alc.dhcpv4.set_vendorspecific (D4OL)

DHCPv4 allows using sname and file fields to store options. However all DHCPv4 functions only operates with the ‟options” field. If a customer wants to manipulate options in the sname/file field, they need to do the parsing work in the script. (extended string.tlvxy method could help here)

• alc.dhcpv4. drop(): The system drops the result packet

• alc.dhcpv4. getOptionList(): Returns a tuple that includes the option-code of the existing top level DHCPv4 options in the packet.

  • The order of the element in the tuple is as same as the options that appear in the packet.

  • If there are multiple instances of the same option, then each instance is one element in the tuple.

  • Pad option(0) is excluded.

  • End option(255) is included

  • Example: A DHCP discovery packet with msg-type/lease-time/request-addr/parameter-request-list/agent-info/end returns (53,51,50,55,82,255)

• alc.dhcpv4.pad(min_size=300): This function pads the resulting DHCPv4 packet to the specified min_size with pad option(0) after executing the whole script. Padding is not added if the result packet is already >=min_size. The default value of min_size is 300. Although not defined in DHCPv4 RFC, many DHCPv4 implementation has a minimal length requirement of 300 bytes. So this function could pad the result packet to the specified min_size.

• alc.dhcpv4. get(op_code): Returns a tuple that includes all instances of the specified top level option as a string. The value of this string is the exact bytes of the option as it appears in packet(excludes option-code and option-len).

  • If the specified option does not exist, then the function returns ()

  • If the instance of the specified option does not have the value (len=0 or does not have len and value part), then the function returns ‟” for that instance in the tuple.

  • Example: There is an address lease time option(51) in the packet, with value 60, then alc.dhcpv4.get(51) should return: (‛\x00\x00\x00\x3c’,)

• alc.dhcpv4. set(op-code,valTuple): This function removes all the existing instances of specified top level option and insert a list of new options. Each element in valTuple is a string, representing one instance of the new option to be inserted; For each new option, the option-code is specified in op-code. The option-len is the length of the element. The rest of option is the element itself.

  Example: To insert an address lease time option(51) in the packet, with the value 60; use alc.dhcpv4.set(51, (‛\x00\x00\x00\x3c’,))

• alc.dhcpv4. clear(op-code): This function removes all the existing instances of specified top level option.

• Although alc.dhcpv4.get() and alc.dhcpv4.set() provide a generic way to manipulate DHCPv4 top level options, but some DHCPv4 options have a complex/hierarchical structure like option82 and option43. To provide a friendly access to these kinds of options, the system provides the following options’ specific functions:

  • alc.dhcpv4.get_relayagent() / alc.dhcpv4.set_relayagent(D4OL)

  • alc.dhcpv4.get_vendorspecific() / alc.dhcpv4.set_vendorspecific (D4OL)

  All alc.dhcpv4.get_XXX() returns a data structure:‟D4OL” (DHCPv4 Option List)

  • D4OL is a list. Each element in the list represents an instance of that option. For example, if there are 3 option82 in the ‟options” field of packet, then get_relayagent() returns a list of 3 elements. Each element represents one instance of the option in the packet.

  • Each element in D4OL is a dict (called dict as ‟D4O” in this example):

    The key of D4O is the sub-option- code. The value is a list of strings of sub-option-value of all instance of the sub-option.

  All alc.dhcpv4.set_XX(OPDL) accepts D4OL as the parameter. Remove all existing instances of the corresponding options and then insert the new options represented by specified D4OL.

Examples:

For a packet with an option82 like following

    Option: (82) Agent Information Option
        Length: 22
        Option (82) Suboption: (1) Agent Circuit ID
            Length: 8
            Agent Circuit ID: 4a616e737656e73
        Option 82 Suboption: (2) Agent Remote ID
            Length: 10
            Agent Remote ID 62617369632364617461

The option-data is (hex formatted) ‟01:08:4a:61:6e:73:73:65:6e:73:02:0a:62:61:73:69:63:23:64:61:74:61”

The following is an example script:

import alc

option82_list=alc.dhcpv4.get_relayagent()
#option82_list will be [{1:['\x4a\x61\x6e:73\x73\x65\x6e\x73',],2:['\x62\x61\x73\x69\x63\x23\x64\x61\x74\x61',]},]
Option82_list[0][2][0]='basic#video' #change remote-id to 'basic#video'
alc.dhcpv4.set_relayagent(option82_list)#update the option82