Creates an OTP-compliant DHCP packet server.

An ExDhcp module binds to a UDP port, listens to DHCP messages sent to the port, and can resend DHCP messages (typically as a broadcast message) in response.

You may instrument whatever state you would like into the server; the DHCP-specific contents will be encapsulated into the internals of the server itself and all of the state exposed to the callbacks will be your own state.

Please consult the readme for crucial deployment information, as you won't be able immediately see or serve DHCP packets without some configuration external to the Erlang/Elixir VM.

ExDhcp is not a fully-functional DHCP server which conforms to the RFC 1531 specs.

It does not:

• accept configuration for handing out DHCP leases
• keep the state of the DHCP leases
• store DHCP lease information to durable storage
• manage arp tables

However, you could use ExDhcp to implement that functionality. For example, minimal ExDhcp server might look something like this:

defmodule MyDhcpServer do
  use ExDhcp
  alias ExDhcp.Packet

  def start_link(init_state) do
    ExDhcp.start_link(__MODULE__, init_state)
  end

  @impl true
  def init(init_state), do: {:ok, init_state}

  @impl true
  def handle_discover(request, xid, mac, state) do

    # insert code here.  Should assign the unimplemented values
    # for the response below:

    response = Packet.respond(request, :offer,
      yiaddr: issued_your_address,
      siaddr: server_ip_address,
      subnet_mask: subnet_mask,
      routers: [router],
      lease_time: lease_time,
      server: server_ip_address,
      domain_name_servers: [dns_server]))

    {:respond, response, new_state}
  end

  @impl true
  def handle_request(request, xid, mac, state) do

    # insert code here.

    response = Packet.respond(request, :ack,
      yiaddr: issued_your_address ...)

    {:respond, response, state}
  end

  @impl true
  def handle_decline(request, xid, mac, state) do
    # insert code here.

    response = Packet.respond(request, :offer,
      yiaddr: new_issued_address ...)

    {:respond, response, state}
  end

end

if you intend to ignore the particular DHCP packet, instead emit the following return from the callback:

{:norespond, state}

You must implement the following three DHCP functionalities as callbacks to successfully assign network hosts:

• handle_discover/4
• handle_request/4
• handle_decline/4

You may also want to implement these callbacks:

• handle_inform/4 to manage a DHCP client requesting early info
• handle_release/4 to manage DHCP clients relinquishing their leases

• handle_packet/4 to generically handle DHCP packets

  • this is most useful to monitor how other DHCP servers are responding on your network

Each of these DHCP callbacks take four arguments, in order:

1. the fully-parsed ExDhcp.Packet structure,
2. the xid (transaction id)
3. the mac address of the client
4. the current state of the ExDhcp GenServer

These are provided as arguments to enable you to easily trap their contents in pattern-matching guards.

NB: the ExDhcp.Packet structure has an :options field, and you may want to emit tags that are outside of the provided basic dhcp options (see ExDhcp.Options.Basic). In this case, you should implement your own parser module (see ExDhcp.Options.Macro) and instrument it into your ExDhcp module using the :dhcp_options option like so:

  use Dhcp, dhcp_options: [ExDhcp.Options.Basic, YourParserModule, AnotherParserModule]

ExDhcp also provides these optional callbacks

• handle_call/3
• handle_cast/2
• handle_continue/2
• handle_info/2

These operate identically to their counterparts in GenServer, but note that they are passed their encapsulated state, not the raw state of the GenServer.

Supervising an ExDhcp instance

The recommended supervision strategy is a single ExDhcp server under the main application. This can be achieved using the ExDhcp.Supervisor helper module.

defmodule MyProject.Application

  def start(_type, _args) do

    initial_value = ...
    dhcp_opts = ...

    children = [{ExDhcp.Supervisor, {MyModule, initial_value, dhcp_opts}}]

    Supervisor.start_link(children, strategy: :one_for_one)
  end

end

For Testing

ExDhcp will instrument inside of your module the b:port/1 call which will return the UDP port that your DHCP server is listening to, this is useful when you are running async tests and you assign your initial port to 0.

Note if you are testing supervised, and your dhcp process dies, then the port may be rebound to another number if you set it 0 initially.