# odhcp6c - Embedded DHCPv6 Client


### Abstract

odhcp6c is a minimal DHCPv6 and RA-client for use in embedded Linux systems
especially routers.


## Features

1. IPv6 bootstrap from different environments with autodetection
	* RA only
	* RA + stateless DHCPv6
	* RA + stateful DHCPv6 (either IA_NA or IA_PD or both)

2. Handling of non-temporary addresses (IA_NA)
	* handling of valid and preferred lifetimes
	* automatic fallback to stateless or PD-only mode

3. Support for DHCPv6 extension
	* Reconfigure-Messages
	* Prefix Delegation (including handling of valid and preferred lifetimes)
	* Prefix Exclusion
	* DNS Configuration Options
	* NTP Options
	* SIP Options
	* Information-Refresh Options
	* Configurable SOL_MAX_RT
	* DS-Lite AFTR-Name Option
	* Softwire address and port mapped clients (MAP, LW4over6)
	* Server unicast Option

4. Support for requesting and parsing Router Advertisements
	* parsing of prefixes, routes, MTU and RDNSS options


## Compiling

odhcp6c uses cmake:
* To prepare a Makefile use:  `cmake`.
* To build / install use: `make` / `make install` afterwards.
* To build DEB or RPM packages use: `make package` afterwards.


## State Script

The state script is called whenever the DHCPv6 state changes.
The script is called with the following parameters: `<interface>` `<state>`

| State								| Description														|
|-----------------------------------|-------------------------------------------------------------------|
| `started`							| The DHCPv6 client has been started								|
| `bound`							| A suitable server was found and addresses or prefixes acquired	|
| `informed`						| A stateless information request returned updated information		|
| `updated`							| Updated information was received from the DHCPv6 server			|
| `ra-updated`						| Updated information was received via Router Advertisements	 	|
| `rebound`							| The DHCPv6 client switched to another server						|
| `unbound`							| The DHCPv6 client lost all DHCPv6 servers and will restart		|
| `stopped`							| The DHCPv6 client has been stopped								|




| Environment						| Description														|
|-----------------------------------|-------------------------------------------------------------------|
| `SERVER`							| A space-separated list of upstream IPv6 routers					|
| `RDNSS`							| A space-separated list of recursive DNS servers					|
| `DOMAINS`							| A space-separated list of DNS search domains						|
| `SNTP_IP`							| A space-separated list of SNTP server IP addresses				|
| `SNTP_FQDN`						| A space-separated list of SNTP server FQDNs						|
| `SIP_IP`							| A space-separated list of SIP servers								|
| `SIP_DOMAIN`						| A space-separated list of SIP domains								|
| `OPTION_<num>`					| Custom option received as base-16									|
| 									| E.g. (Client ID) `OPTION_1` : `000300010badf00dcafe`				|
| `PREFIXES` 						| A space-separated list of prefixes currently assigned				|
| 									|	Format: `<prefix>/<length>,preferred,valid[,excluded=<excluded-prefix>/<length>][,class=<prefix class #>]`|
| `ADDRESSES`						| A space-separated list of addresses currently assigned			|
|									|	Format: `<address>/<length>,preferred,valid`					|
| `RA_ADDRESSES` 					| A space-separated list of addresses from RA-prefixes				|
|									|	Format: `<address>/<length>,preferred,valid`					|
| `RA_ROUTES`						| A space-separated list of routes from the RA						|
|									|	Format: `<address>/<length>,gateway,valid,metric`				|
| `RA_DNS`							| A space-separated list of recursive DNS servers from the RA		|
| `RA_DOMAINS`						| A space-separated list of DNS search domains from the RA			|
| `RA_HOPLIMIT`						| Highest hop-limit received in RAs									|
| `RA_MTU`							| MTU-value received in RA											|
| `RA_REACHABLE`					| ND Reachability time												|
| `RA_RETRANSMIT` 					| ND Retransmit time												|
| `AFTR`							| The DS-Lite AFTR domain name										|
| `MAPE` / `MAPT` / `LW4O6` 		| Softwire rules for MAPE, MAPT and LW4O6							|
| `CAPTIVE_PORTAL_URI` 				| RFC8910 captive portal API URI received from upstream				|
| `PASSTHRU` 						| The content of the last packet relayed							|



## Ubus Integration

Build with `ENABLE_UBUS` flag to connect odhcp6c to ubus. Object is registered at : `odhcp6c.{ifname}`.

Events are emitted whenever the DHCPv6 state changes and can replace the use of a state script. The variables are the same as those defined in the State Script section.

The following RPC methods are available:


| Method							| I/O		| Description														|
|-----------------------------------|-----------|-------------------------------------------------------------------|
| `get_state()`						| Output	| Returns the DHCPv6 state											|
|									| 			| OUT : see State Script section									|
| `get_statistics()`				| Output	| Returns the packet statistics										|
|									| 			| `dhcp_solicit` : Total number of SOLICIT messages sent			|
|									| 			| `dhcp_advertise` : Total number of ADVERTISE messages received	|
|									| 			| `dhcp_request` : Total number of REQUEST messages sent			|
|									| 			| `dhcp_confirm` : Total number of CONFIRM messages sent			|
|									| 			| `dhcp_renew` : Total number of RENEW messages sent				|
|									| 			| `dhcp_rebind` : Total number of REBIND messages sent				|
|									| 			| `dhcp_reply` : Total number of REPLY messages received			|
|									| 			| `dhcp_release` : Total number of RELEASE messages sent			|
|									| 			| `dhcp_decline` : Total number of DECLINE messages sent			|
|									| 			| `dhcp_reconfigure` : Total number of RECONFIGURE messages received	|
|									| 			| `dhcp_information_request` : Total number of INFORMATION-REQUEST messages sent	|
|									| 			| `dhcp_discarded_packets` : Total number of discarded DHCP packets 	|
|									| 			| `dhcp_transmit_failures` : Total number of DHCP messages that failed to be transmitted	|
| `reset_statistics()`				| Input		| Reset packet statistics											|
| `reconfigure_dhcp({...})`			| Input		| Reconfigure DHCP settings											|
|									| 			| `dscp` (int) : DSCP value used for DHCP packets					|
|									| 			| `release` (bool) : Send a RELEASE message on exit/reset			|
|									| 			| `sol_timeout` (int) : Maximum timeout for DHCPv6-SOLICIT			|
|									| 			| `sk_prio` (int) : Packet kernel priority							|
|									| 			| `opt_requested` (int[]) : Options to be requested					|
|									| 			| `opt_strict` (bool) : Do not request any options except those specified	|
|									| 			| `opt_reconfigure` (bool) : Send Accept Reconfigure option			|
|									| 			| `opt_fqdn` (bool) : Send Client FQDN option						|
|									| 			| `opt_unicast` (bool) : Ignore Server Unicast option				|
|									| 			| `opt_send` (string[]) : Options to be sent						|
|									| 			| `req_addresses` (string{`try|force|none`}) : Request addresses	|
|									| 			| `req_prefixes` (int) : Request Prefixes (0 = auto)				|
|									| 			| `stateful_only` (bool) : Discard advertisements without any address or prefix proposed	|
|									| 			| `irt_default` (int) : Default information refresh time (expressed in seconds)		|
|									| 			| `irt_min` (int) : Minimum information refresh time (expressed in seconds)			|
|									| 			| `rand_factor` (int) : Randomization factor for retransmission timeout				|
|									| 			| `auth_protocol` (string) : Authentication protocol to be used (`None`,`ConfigurationToken`, `ReconfigureKeyAuthentication`)|
|									| 			| `auth_token` (string) : Authentication token to be used when AuthenticationProtocol is set to `ConfigurationToken`|
|									| 			| `msg_solicit` (table) : Retransmission settings for SOLICIT				|
|									| 			| `msg_request` (table) : Retransmission settings for REQUEST				|
|									| 			| `msg_renew` (table) : Retransmission settings for RENEW					|
|									| 			| `msg_rebind` (table) : Retransmission settings for REBIND					|
|									| 			| `msg_release` (table) : Retransmission settings for RELEASE				|
|									| 			| `msg_decline` (table) : Retransmission settings for DECLINE				|
|									| 			| `msg_inforeq` (table) : Retransmission settings for INFORMATION-REQUEST	|
|									| 			| 																			|
|									| 			| Input arguments for Retransmission settings :								|
|									| 			| `delay_max` (int) : Maximum delay of first message (expressed in seconds)	|
|									| 			| `timeout_init` (int) : Initial message timeout (expressed in seconds)		|
|									| 			| `timeout_max` (int) : Maximum message timeout (expressed in seconds)		|
|									| 			| `rc_max` (int) : Maximum message retry attempts							|
| `renew()`							| Input		| Force transmission of RENEW/INFORMATION-REQUEST messages 					|
| `release()`						| Input		| Force transmission of RELEASE message and start new cycle					|

