===================
dhcp_option_util.py
===================
Version: 0.0.4
Author: Chris Marrison
Email: chris@infoblox.com
Description
-----------
Demonstration script for Hex Encoding/Decoding of DHCP Options
using the dhcputils from the bloxone module.
Prerequisites
-------------
Python 3.6 or above
bloxone Module
Modules
~~~~~~~
Requires:
- bloxone
- pyyaml
Installing the bloxone Module
-----------------------------
The bloxone module can be installed either from source or via PyPi::
pip3 install bloxone
Source is available from github::
https://github.com/ccmarris/python-bloxone
User Guide
----------
Help information is available via the --help option::
% ./dhcp_option_util.py --helpusage: dhcp_option_util.py [-h] [-c CONFIG]
[--vendor VENDOR] [--suboptions SUBOPTIONS] [--prefix PREFIX]
[--decode DECODE] [--data_only] [--type TYPE] [--dump DUMP]
DHCP Option Encoding and Decoding Utility
optional arguments:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
Path to vendor file
--vendor VENDOR Vendor Identifier
--suboptions SUBOPTIONS
Sub Options to encode
--prefix PREFIX Optional prefix for use with --suboptions
--decode DECODE Hex string to decode
--data_only Decode hex as 'string' or specified by --type
--type TYPE Optional data_type for --decode --data_only
--dump DUMP Dump Vendor
The script allows encoding of DHCP Options through either the use of a YAML
vendor dictionary file, or directly from the CLI.
A sample YAML file *vendor_dict.yaml* is included, whilst the file format is
described in the :ref:`yaml-format`.
Encoding examples
+++++++++++++++++
Encoding using the YAML vendor dictionary allows you to define both the
structure and the data to encode for one or more vendors. A number of examples
are included in the default *vendor_dict.yamnl* file, with the intention of
adding additional vendors over time.
To process all vendors in the configuration file::
$ ./dhcp_option_util.py -c vendor_dict.yaml
To process a specific vendor::
$ ./dhcp_option_util.py -c vendor_dict.yaml --vendor <vendor>
Dump the configuarion of a vendor::
$ ./dhcp_option_util.py -c vendor_dict.yaml --dump <vendor>
The script also supports direct encoding from the CLI using the *--sub-option*
option. This allows you to specify options using the format::
'<code>:<type>:<data>,<code>:<type>:<data>,<code>:<type>:<data>'
Encode direct from CLI::
$ ./dhcp_option_util.py --sub-options '1:string:https,2:ipv4_address:10.10.10.10'
Decoding examples
+++++++++++++++++
Decoding will, by default, attempt to decode as a set of encoded sub-options
but will also decode the provided hex as a single data string.
It is also possible to either specify a vendor (using the vendor
dictionary yaml file) or simple <code>:<type> definitions on the CLI using
--suboptions allowing the user to specify the data types used for Decoding
the data types.
To decode as data only it is possible to use the --data_only option and
optionally adding the data_type that should be used with --type. (By default
data will be decoded using the string type.)
.. Note:
The --sub-option only uses *code* and *type* for decoding. Therefore a
simpler set can be defined using <code>:<type>,<code>:<type>,...
Examples::
./dhcp_option_util.py --decode <hex_string>
./dhcp_option_util.py --decode <hex_string> --suboptions '1:string,2:ip'
./dhcp_option_util.py --decode <hex_string> --vendor 'MS-UC-Client
./dhcp_option_util.py --decode <hex_string> --data_only
./dhcp_option_util.py --decode <hex_string> --data_only --type array_of_ip
.. yaml-format:
YAML File Format
----------------
The base file definition allows for a file version number and a list of
vendors, a sample showing all of the options is shown below::
---
# DHCP Vendor Option Definitions
version: 0.0.1
vendors:
Sample-Vendor:
vci: sample-vci
description: My Vendor Class
prefix: "<prefix str if required>"
option-def:
parent-option:
name: option name
code: 43
type: binary
array: False
sub-options:
- name: Sub Opt 1
code: 1
type: string
data: Encode this string
array: False
data-only: False
- name: Sub Opt 2
code: 5
type: ipv4_address
data: 10.10.10.10,20.20.20.20
array: True
data-only: False
The format allows the complete definition of a vendor, with the core element
being the *option-def* that defines, in particular, the list of sub-options
for encoding.
The definition can include a prefix to prepend to the encoding, and data-only
flags to handle both option 43 style encodings and option 125 style encodings.
Example Definitions::
---
# DHCP Vendor Option Definitions
version: 0.0.1
vendors:
MS-UC-Client:
vci: MS-UC-Client
description: Microsoft Lync Client
option-def:
parent-option:
name: option 43
code: 43
type: binary
array: False
sub-options:
- name: UC Identifier
code: 1
type: string
data: MS-UC-Client
array: False
- name: URL Scheme
code: 2
type: string
data: https
array: False
- name: Web Server FQDN
code: 3
type: string
data: epslync01.epsilonhq.local
array: False
- name: Web Server Port
code: 4
type: string
data: 443
array: False
- name: Certificate Web Service
code: 5
type: string
data: /CertProv/CertProvisioningService.svc
array: False
####### CISCO
# Option 43 sub-option 241
Cisco AP:
vci: Cisco AP
description: Cisco Aironet Series APs
option-def:
parent-option:
name: option 43
code: 43
type: binary
array: False
sub-options:
- name: Controller IP
code: 241
type: ipv4_address
data: 10.150.1.15,10.150.50.15
array: True
####### MITEL
Mitel:
vci: Mitel
description: Mitel Phone (prepend 00000403)
prefix: "00000403"
option-def:
parent-option:
name: option 125
code: 125
type: binary
array: False
sub-options:
- code: 125
type: string
data: id:ipphone.mitel.com;call_srv=X;vlan=X;dscp=46;l2p=X;sw_tftp=X
data-only: True
License
-------
This project is licensed under the 2-Clause BSD License - please see LICENSE
file for details.
Aknowledgements
---------------
Thanks to John Steele, John Neerdael and Sif Baksh for their input and thanks
to Don Smith for the vendor examples.
