ex_dhcp

v0.1.5

ex_dhcp v0.1.5 ExDhcp.Packet View Source

Provides a structure for the DHCP UDP packet, according to RFC 1531 specifications. For a simpler reference on the DHCP protocol's binary layout, refer to Wikipedia.

  • OP: operation (request: 1, response: 2). ExDhcp will only respond to requests (except in handle_packet) and only send response packets.

  • HTYPE: specifies the hardware address type. Currently only ethernet is supported.

  • HLEN: specifies the hardware address length. Currently only 6-byte MAC is supported.

  • HOPS: number of hops. For when you implement 'relay-DHCP' (see RFC 1531: BOOTP relay agent).

  • XID: transaction id. Allows concurrent servicing of multiple DHCP requests. You may want to implement spawning of separate servers to handle different transmissions.

  • SECS: seconds since client has booted.

  • FLAGS: DHCP flags (see RFC 1531: figure 2).

  • CIADDR: "client internet address" (expected in :request requests).

  • YIADDR: "your (client) internet address" (expected in :offer responses)

  • SIADDR: "next server internet address" (expected in some :offer, :ack, and :nak responses)

  • GIADDR: "gateway internet address". For when you implement 'relay-DHCP' (see RFC 1531: BOOTP relay agent).

  • options: a {integer, binary} tuple list. Supported opcodes will be translated into {atom, value} tuples by ExDhcp.Options parser modules (see ExDhcp.Options.Macro).

Learn more about RFC 1531 here: ietf.org

Link to this section Summary

Types

t()

The Packet struct type.

udp_packet()

Erlang's internal representation of an active UDP packet.

Functions

decode(udp_packet, option_parsers \\ [Basic])

Converts a udp packet or a binary payload from a UDP packet and converts it to a ExDhcp.Packet struct.

encode(message, modules \\ [Basic])

Converts from a ExDhcp.Packet struct into an iolist().

respond(packet, type, params)

A convenience function used to craft a DHCP response based on the request.

send(packet, options \\ [])

For testing and instrumentation purposes. Allows you to send a particular packet to a DHCP port of your choice. Usually used to mock a client.

Link to this section Types

Link to this type

t() View Source 
t() :: %ExDhcp.Packet{
  chaddr: ExDhcp.Utils.mac(),
  ciaddr: ExDhcp.Utils.ip4(),
  flags: non_neg_integer(),
  giaddr: ExDhcp.Utils.ip4(),
  hlen: 6,
  hops: non_neg_integer(),
  htype: 1,
  op: 1 | 2,
  options: %{
    optional(non_neg_integer()) => binary(),
    optional(atom()) => any()
  },
  secs: non_neg_integer(),
  siaddr: ExDhcp.Utils.ip4(),
  xid: non_neg_integer(),
  yiaddr: ExDhcp.Utils.ip4()
}

The Packet struct type.

See ExDhcp.Packet for details on the struct parameters.

Link to this type

udp_packet() View Source 
udp_packet() ::
  {:udp, :gen_udp.socket(), ExDhcp.Utils.ip4(), :inet.ancillary_data(),
   binary()}

Erlang's internal representation of an active UDP packet.

Link to this section Functions

Link to this function

decode(udp_packet, option_parsers \\ [Basic]) View Source 
decode(udp_packet() | binary(), [module()]) :: t()

Converts a udp packet or a binary payload from a UDP packet and converts it to a ExDhcp.Packet struct.

NB: This function will fail if you attempt to pass it a UDP packet that does not contain the DHCP "magic cookie".

Link to this function

encode(message, modules \\ [Basic]) View Source

Converts from a ExDhcp.Packet struct into an iolist().

Typically, this will be sent directly to a :gen_udp.send/2 call. If you need to examine the contents of the iolist() as a binary, you may want to send the results to :erlang.iolist_to_binary/1

Link to this function

respond(packet, type, params) View Source 
respond(t(), :offer | :ack | :nak, keyword()) :: t()

A convenience function used to craft a DHCP response based on the request.

Usage

type should be one of [:offer, :ack, :nak].

  • The built-in values are copied into the response without change.
  • The DHCP opcode is automatically set to 2.
  • The options list is stripped.

params should be a flat keyword list containing DHCP parameters and options.

All of the options keys should be encodable by exactly one of your options parsing modules.

If you need to encode a value directly as an integer/binary pair because it's not parsed by any modules, do not use respond/3.

Example 

iex> ExDhcp.Packet.respond(%ExDhcp.Packet{}, :offer, yiaddr: {192, 168, 0, 5}, hostname: "foo")
%ExDhcp.Packet{yiaddr: {192, 168, 0, 5}, options: %{53 => <<2>>, hostname: "foo"}}

Note that in the example :yiaddr entered the packet struct, and :hostname entered the :options parameter.

Link to this function

send(packet, options \\ []) View Source

For testing and instrumentation purposes. Allows you to send a particular packet to a DHCP port of your choice. Usually used to mock a client.

options:

  • :addr - address to send to
  • :port - target port send from defaults to 68
  • :dest_port - target port to send to defaults to 67
  • :modules - modules to perform packet encoding defaults to [ExDhcp.Options.Basic]
  • :nowait - should not wait for the response
  • :bind_to_device - binds to a specific device in the tree
  • :ip - use an specific ip address in the request